Skip to main content
This guide walks you through setting up Penn Clubs on your local machine for development. Penn Clubs supports Mac and Linux/WSL development.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Python 3.13 - Required for the Django backend
  • uv - Python package manager
  • Node.js 20 - Required for the React/Next.js frontend (v20.11.1 is stable)
  • Bun - JavaScript runtime and package manager
  • PostgreSQL - Required for psycopg2 (Mac only, see below)
Our codebase requires Node 20 specifically. Other versions are not supported.

​
Backend Setup

The backend is a Django REST API that handles all data operations, authentication, and business logic.

​
Mac: Install PostgreSQL Dependencies

On Mac, you need to install PostgreSQL and OpenSSL to build psycopg2:
1

Install PostgreSQL and OpenSSL

brew install postgresql
brew install openssl
brew unlink openssl && brew link openssl --force
2

Configure environment

Add OpenSSL to your PATH and configure build flags:
echo 'export PATH="/usr/local/opt/openssl@3/bin:$PATH"' >> ~/.zshrc
export LDFLAGS="-L/usr/local/opt/openssl@3/lib"
export CPPFLAGS="-I/usr/local/opt/openssl@3/include"

​
Linux: Install Build Dependencies

On Linux, install Python development packages and PostgreSQL libraries: 
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt-get update
sudo apt-get install gcc python3.13-dev libpq-dev

​
Install Backend Dependencies

1

Navigate to backend directory

cd backend
2

Install Python dependencies

This may take a few minutes on first run:
uv sync
3

Install pre-commit hooks

uv run pre-commit install
4

Run database migrations

uv run ./manage.py migrate
5

Populate database with test data

This creates dummy data for development, including a test user:
uv run ./manage.py populate
6

Start the development server

uv run ./manage.py runserver
The backend will be available at http://localhost:8000

​
Test User Credentials

The populate command creates a test user:
  • Username: bfranklin
  • Password: test
Access the Django admin at http://localhost:8000/api/admin

​
Frontend Setup

The frontend is a Next.js application built with React that provides the user interface.
1

Open a new terminal

Keep your backend server running and open a new terminal window.
2

Navigate to frontend directory

cd frontend
3

Install dependencies

bun install
4

Start the development server

bun dev
The frontend will be available at http://localhost:3000

​
Environment Variables

​
Development Environment Variables

For local development, most variables have sensible defaults. Create a .env file in the backend directory if you need to customize settings.

​
Optional Development Variables

  • NGROK_URL - Required for testing CyberSource payment flows (see Payment Testing below)
  • CYBERSOURCE_SA_PROFILE_ID - CyberSource test profile ID
  • CYBERSOURCE_SA_ACCESS_KEY - CyberSource test access key
  • CYBERSOURCE_SA_SECRET_KEY - CyberSource test secret key

​
Production Environment Variables

These variables must be set in production environments.

​
Backend Variables

  • SECRET_KEY - Django secret key for cryptographic signing
  • DATABASE_URL - PostgreSQL connection string
  • SENTRY_URL - Sentry DSN for error tracking
  • AWS_ACCESS_KEY_ID - AWS access key for S3 file storage
  • AWS_SECRET_ACCESS_KEY - AWS secret key
  • AWS_STORAGE_BUCKET_NAME - S3 bucket name
  • LABS_REDIRECT_URI - OAuth redirect URI
  • LABS_CLIENT_ID - Platform OAuth client ID
  • LABS_CLIENT_SECRET - Platform OAuth client secret
  • REDIS_HOST - Redis host for caching and channels
  • EMAIL_HOST - SMTP server hostname
  • EMAIL_USERNAME - SMTP username
  • EMAIL_PASSWORD - SMTP password

​
Frontend Variables

  • NEXT_PUBLIC_GOOGLE_API_KEY - Google Maps API key
  • NEXT_PUBLIC_SITE_NAME - Site branding (clubs for Penn Clubs, fyh for Hub@Penn)

​
Ticketing/Payment Variables

For CyberSource Secure Acceptance Hosted Checkout:
  • CYBERSOURCE_SA_PROFILE_ID - Secure Acceptance profile ID
  • CYBERSOURCE_SA_ACCESS_KEY - Access key for the profile
  • CYBERSOURCE_SA_SECRET_KEY - Secret key for signing requests
  • FRONTEND_URL - Base URL for post-payment redirects (defaults to https://pennclubs.com)

​
Payment Testing with ngrok

To test the ticketing/payment flow locally, you need a publicly accessible URL for CyberSource callbacks.
1

Install ngrok

curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc \
  | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null \
  && echo "deb https://ngrok-agent.s3.amazonaws.com buster main" \
  | sudo tee /etc/apt/sources.list.d/ngrok.list \
  && sudo apt update && sudo apt install ngrok
2

Start ngrok tunnel

In a separate terminal:
ngrok http 3000
Copy the HTTPS forwarding URL (e.g., https://abc123.ngrok-free.app)
3

Configure environment variables

Create backend/.env with your ngrok URL and CyberSource test credentials:
CYBERSOURCE_SA_PROFILE_ID=your-test-profile-id
CYBERSOURCE_SA_ACCESS_KEY=your-test-access-key
CYBERSOURCE_SA_SECRET_KEY=your-test-secret-key
NGROK_URL=https://abc123.ngrok-free.app
4

Start both servers

Start the backend:
cd backend
DJANGO_SETTINGS_MODULE=pennclubs.settings.development uv run ./manage.py runserver
Start the frontend in another terminal:
cd frontend
bun dev
5

Access the application

Access at http://localhost:3000 (NOT the ngrok URL)
The NGROK_URL variable configures the CyberSource callback URL and adds the ngrok URL to CSRF_TRUSTED_ORIGINS. Always use http://localhost:3000 in your browser for proper session handling.

​
CyberSource Test Credentials

To obtain CyberSource test credentials:
  1. Log into the CyberSource Business Center
  2. Navigate to Payment Configuration → Secure Acceptance Settings
  3. Create or select a Hosted Checkout profile
  4. Generate security keys and note the Profile ID, Access Key, and Secret Key
Use CyberSource test card numbers for testing payments.

​
Troubleshooting

​
psycopg2 Build Errors (Mac)

If you encounter errors building psycopg2, ensure you’ve followed the Mac PostgreSQL setup steps and exported the LDFLAGS and CPPFLAGS environment variables.

​
Node Version Issues

Verify you’re using Node 20: 
node --version
If you have a different version, use nvm to install Node 20: 
nvm install 20
nvm use 20

​
Port Already in Use

If port 8000 or 3000 is already in use:
  • Backend: uv run ./manage.py runserver 8001
  • Frontend: Update package.json proxy setting to match your backend port

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us