Installation & Development Setup

Overview

Penn Clubs consists of two main components that need to be running for development:

Backend: Django REST API (Python 3.13)
Frontend: Next.js application (Node 22 with Bun)

This guide will walk you through setting up both components on Mac, Linux, or Windows Subsystem for Linux (WSL).

Questions during setup? Check out the extended development guide for FAQs and troubleshooting.

Prerequisites

Backend Requirements

Python 3.13
uv package manager
PostgreSQL (for dependency compilation)
Git

Frontend Requirements

Node.js 22.11.0 (exact version)
Bun package manager
Git

Penn Clubs requires Node 22 specifically. Other versions (including 18 and 20) are not supported and may cause build failures.

Backend Setup

Install uv Package Manager

Install uv, a fast Python package manager:

Mac/Linux
With pip
With Homebrew

curl -LsSf https://astral.sh/uv/install.sh | sh

pip install uv

brew install uv

Install PostgreSQL Dependencies (Mac)

On Mac, you need to install PostgreSQL and OpenSSL for the psycopg2 dependency:

# Install PostgreSQL and OpenSSL
brew install postgresql
brew install openssl
brew unlink openssl && brew link openssl --force

# Add OpenSSL to your shell configuration
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"

If you’re not modifying dependencies right away, you can skip this step and return to it later if needed.

Install Python Build Dependencies (Linux)

On Linux, install build dependencies:

sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt-get update
sudo apt-get install gcc python3.13-dev libpq-dev

Clone Repository and Install Dependencies

# Clone the repository
git clone https://github.com/pennlabs/penn-clubs.git
cd penn-clubs/backend

# Install Python dependencies
uv sync

The first uv sync may take a few minutes. If you skipped installing PostgreSQL dependencies, you might see locking errors - this is expected and won’t affect basic development.

Set Up Pre-commit Hooks

Install pre-commit hooks for code quality checks:

uv run pre-commit install

These hooks will run automatically before each commit to ensure code formatting and linting standards.

Initialize Database

Run Django migrations and populate with test data:

# Apply database migrations
uv run ./manage.py migrate

# Populate database with dummy data (development only)
uv run ./manage.py populate

The populate command creates test clubs and a test user:

Username: bfranklin
Password: test

# Example clubs created by populate command
clubs = [
    {
        "code": "pppjo",
        "name": "Penn Pre-Professional Juggling Organization",
        "description": """The PPPJO is looking for intense jugglers seeking to juggle
their way to the top. Come with your juggling equipment (and business formal attire) to
hone your skills in time for recruiting season!""",
        "size": Club.SIZE_MEDIUM,  # 21-50 members
        "application_required": Club.OPEN_MEMBERSHIP,
        "recruiting_cycle": Club.RECRUITING_OPEN,
        "tags": ["Professional", "Athletics", "Undergraduate"]
    }
    # ... more test clubs
]

Start Development Server

uv run ./manage.py runserver

The backend will be available at http://localhost:8000

Access the Django admin interface at http://localhost:8000/api/admin using the test credentials.

Run Tests (Optional)

Run the test suite to verify your setup:

uv run ./manage.py test

Frontend Setup

Do not kill your backend server! Open a new terminal window for frontend setup.

Install Node.js 22

Penn Clubs requires Node.js 22.11.0. Install it using your preferred method:

nvm (Recommended)
Homebrew (Mac)
Direct Download

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install Node 22
nvm install 22.11.0
nvm use 22.11.0

brew install node@22

Verify your Node version:

node --version  # Should output v22.11.0

Install Bun Package Manager

Install Bun, a fast JavaScript package manager and runtime:

curl -fsSL https://bun.sh/install | bash

Or with npm:

npm install -g bun

Navigate to Frontend Directory

cd frontend  # If you're still in the backend directory
# Or from the project root:
cd penn-clubs/frontend

Install Dependencies

bun install

This will install all dependencies defined in package.json, including:

{
  "dependencies": {
    "next": "~15.2.7",
    "react": "^19.2.2",
    "react-dom": "^19.2.2",
    "typescript": "5.5.4",
    "styled-components": "npm:@sanity/css-in-js",
    "formik": "^2.4.9",
    "fuse.js": "^7.1.0",
    "react-big-calendar": "^1.19.4"
    // ... and many more
  }
}

Start Development Server

bun dev

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

The frontend automatically proxies API requests to http://localhost:8000 as configured in package.json:

{
  "proxy": "http://localhost:8000/"
}

Navigate to http://localhost:3000
Click Login in the top right corner
Use credentials:
- Username: bfranklin
- Password: test

Or access the admin interface directly at http://localhost:3000/api/admin

Environment Variables

Production Environment Variables

The following environment variables are required for production deployments but are NOT needed for local development.

Backend (.env)
Frontend (.env.local)
Ticketing (Optional)

Create a .env file in the backend directory for production:

# Required
SECRET_KEY=your-secret-key-here
SENTRY_URL=https://your-sentry-url

# AWS S3 Storage
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_STORAGE_BUCKET_NAME=your-bucket-name

# Penn Labs Platform OAuth
LABS_REDIRECT_URI=https://pennclubs.com/callback
LABS_CLIENT_ID=your-client-id
LABS_CLIENT_SECRET=your-client-secret

# Optional
NEXT_PUBLIC_SITE_NAME=clubs  # or 'fyh' for Hub@Penn

Create a .env.local file in the frontend directory:

# Google Maps API (for location features)
NEXT_PUBLIC_GOOGLE_API_KEY=your-google-api-key

# Site configuration (optional)
NEXT_PUBLIC_SITE_NAME=clubs  # 'clubs' or 'fyh'

For CyberSource payment processing (optional, only if testing ticketing):

# CyberSource Secure Acceptance
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 for local development
NGROK_URL=https://abc123.ngrok-free.app
FRONTEND_URL=https://pennclubs.com  # Production callback URL

See the Ticketing Development section for setup instructions.

Ticketing Development

Setting Up Local Ticketing (Advanced)

Penn Clubs uses CyberSource Secure Acceptance Hosted Checkout for payment processing. Local development requires ngrok to create a publicly accessible URL for payment callbacks.

Install ngrok

Mac
Ubuntu/Debian
Snap

brew 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

sudo snap install ngrok

Start ngrok Tunnel

In a separate terminal:

ngrok http 3000

Copy the HTTPS forwarding URL (e.g., https://abc123.ngrok-free.app)

Configure Backend

Create .env in the backend directory:

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

Restart Backend with Settings

cd backend
DJANGO_SETTINGS_MODULE=pennclubs.settings.development uv run ./manage.py runserver

Access via Localhost

Always access the app at http://localhost:3000 (NOT the ngrok URL) to maintain proper authentication and session handling.

Payment Flow:

User initiates checkout → Backend generates signed payment parameters
Frontend submits form POST to CyberSource with signed parameters
User enters payment details on CyberSource’s hosted page
CyberSource POSTs results to /api/tickets/payment_complete/ via ngrok
Backend validates signature and processes payment

Use CyberSource test card numbers when testing. The development environment automatically uses the test endpoint.

Code Quality Tools

Backend Linting

cd backend

# Run pre-commit hooks manually
uv run pre-commit run --all-files

# Format code with Black
uv run black .

# Check with flake8
uv run flake8

Frontend Linting

cd frontend

# Lint code
bun run lint

# Auto-fix issues
bun run clean

# Type check
bun run test

Building for Production

Backend
Frontend

The backend doesn’t require a build step, but you can prepare for deployment:

# Collect static files
uv run ./manage.py collectstatic --no-input

# Run migrations
uv run ./manage.py migrate

# Start with gunicorn (production)
uv run gunicorn pennclubs.wsgi:application

cd frontend

# Build production bundle
env NODE_ENV=production bunx next build

# Start production server
env NODE_ENV=production bunx next start

The build creates an optimized production bundle with:

Static page generation
Image optimization
Code splitting
Minification

Common Issues and Troubleshooting

Port Already in Use

If ports 8000 or 3000 are already in use:

# Find process using port
lsof -i :8000  # or :3000

# Kill the process
kill -9 <PID>

Node Version Mismatch

Ensure you’re using Node 22:

node --version  # Should be v22.11.0

# Switch with nvm
nvm use 22.11.0

Database Connection Errors

The development setup uses SQLite by default. If you see database errors:

cd backend

# Delete database and start fresh
rm db.sqlite3

# Recreate database
uv run ./manage.py migrate
uv run ./manage.py populate

Module Import Errors

If you see import errors:

# Reinstall dependencies
cd backend
uv sync --refresh

# Or for frontend
cd frontend
rm -rf node_modules
bun install

Next Steps

Read the Contributing Guide

Learn about our development workflow and contribution guidelines

Explore the API

Browse the REST API documentation

Join Penn Labs

Apply to join our team of student developers

Report Issues

Found a bug? Let us know on GitHub

Additional Resources

Django Docs

Django framework documentation

Next.js Docs

Next.js framework documentation

REST Framework

Django REST Framework docs

Bun Docs

Bun package manager documentation

uv Docs

uv package manager documentation

TypeScript Docs

TypeScript language documentation

Get Started

Features

User Guides

Development

Installation & Development Setup

Overview

Prerequisites

Backend Requirements

Frontend Requirements

Backend Setup

Frontend Setup

Environment Variables

Production Environment Variables

Ticketing Development

Code Quality Tools

Backend Linting

Frontend Linting

Building for Production

Common Issues and Troubleshooting

Next Steps

Read the Contributing Guide

Explore the API

Join Penn Labs

Report Issues

Additional Resources

Django Docs

Next.js Docs

REST Framework

Bun Docs

uv Docs

TypeScript Docs

Build docs developers (and LLMs) love

Get Started

Features

User Guides

Development

​Overview

​Prerequisites

Backend Requirements

Frontend Requirements

​Backend Setup

​Frontend Setup

​Environment Variables

​Production Environment Variables

​Ticketing Development

​Code Quality Tools

Backend Linting

Frontend Linting

​Building for Production

​Common Issues and Troubleshooting

​Next Steps

Read the Contributing Guide

Explore the API

Join Penn Labs

Report Issues

​Additional Resources

Django Docs

Next.js Docs

REST Framework

Bun Docs

uv Docs

TypeScript Docs

Build docs developers (and LLMs) love

Overview

Prerequisites

Backend Setup

Frontend Setup

Environment Variables

Production Environment Variables

Ticketing Development

Code Quality Tools

Building for Production

Common Issues and Troubleshooting

Next Steps

Additional Resources