freeCodeCamp Local Development & Deployment Guide

Prerequisites

• Node.js: LTS version (v18 or v20 recommended)
• Package Manager: pnpm (preferred) or npm
• Database: MongoDB (local instance or Docker) and/or SQL database supported by Prisma
• Git: For cloning and version control
• System Resources: Minimum 4GB RAM, 10GB free disk space

Installation

1. Clone the repository

   git clone https://github.com/freeCodeCamp/freeCodeCamp.git
   cd freeCodeCamp
   

2. Install dependencies

   # Using pnpm (recommended)
   pnpm install
   
   # Or using npm
   npm install
   

3. Generate Prisma client

   cd api
   npx prisma generate
   cd ..
   

4. Seed the database (if seed scripts are available)

   pnpm run seed
   

Configuration

Create environment files based on the sample configurations:

1. API Environment (api/.env)

   # Required for JWT signing/verification
   JWT_SECRET=your-jwt-secret-min-32-characters-long
   
   # API location for redirects and CORS
   API_LOCATION=http://localhost:3000
   
   # Database connection (Prisma)
   DATABASE_URL="mongodb+srv://user:pass@cluster/db?retryWrites=true&w=majority"
   # OR for SQL databases
   DATABASE_URL="postgresql://user:password@localhost:5432/freecodecamp"
   
   # Session configuration
   SESSION_SECRET=another-secret-key
   
   # Development flags
   SHOW_UPCOMING_CHANGES=true
   

2. Client Environment (client/.env or client/config/env.json)

   {
     "showUpcomingChanges": true,
     "apiLocation": "http://localhost:3000"
   }
   

3. Prisma Schema (if using custom database)

   • Verify api/prisma/schema.prisma matches your database type
   • Run migrations if applicable:

     cd api
     npx prisma migrate dev
     

Build & Run

Development Mode

Run both client and API concurrently:

# From root directory
pnpm run develop

Or run separately:

# Terminal 1 - API
cd api
pnpm run dev
# Server runs on http://localhost:3000

# Terminal 2 - Client
cd client
pnpm run develop
# Client runs on http://localhost:8000

Production Build

1. Build the API

   cd api
   pnpm run build
   pnpm start
   

2. Build the Client

   cd client
   pnpm run build
   # Serve using any static file server or
   pnpm serve
   

Exam Environment Setup (Optional)

For exam functionality, ensure:

• JWT_SECRET is set and consistent
• Database includes exam tables (handled by Prisma schema)
• Moderation status enum is seeded in database

Deployment

Docker Deployment (Recommended)

# Multi-stage build example
FROM node:18-alpine AS builder
WORKDIR /app
COPY . .
RUN npm ci
RUN npm run build

FROM node:18-alpine
WORKDIR /app
COPY --from=builder /app/api/dist ./api/dist
COPY --from=builder /app/client/public ./client/public
ENV NODE_ENV=production
ENV JWT_SECRET=${JWT_SECRET}
ENV DATABASE_URL=${DATABASE_URL}
EXPOSE 3000
CMD ["node", "api/dist/server.js"]

Platform-Specific Deployment

Railway/Render/Heroku:

• Set environment variables in dashboard
• Build command: pnpm run build
• Start command: pnpm start
• Add MongoDB/PostgreSQL addon

AWS/DigitalOcean:

• Use PM2 for process management: pm2 start api/dist/server.js
• Configure Nginx reverse proxy for client static files and API routes
• Set up SSL certificates for HTTPS (required for JWT secure cookies)

Vercel/Netlify (Client Only):

• Connect repository
• Set build directory to client/public or client/dist
• Configure API proxy to external backend

Production Checklist

• Set strong JWT_SECRET and SESSION_SECRET
• Configure CORS origins in API settings
• Set up database backups
• Enable logging and monitoring (Fastify logs to stdout by default)
• Configure rate limiting for /exam-environment/* routes
• Set NODE_ENV=production

Troubleshooting

Database Connection Errors

Issue: PrismaClientInitializationError or connection timeouts Solution:

• Verify DATABASE_URL format matches Prisma schema provider (mongodb/postgresql)
• Ensure database is accessible from host (check firewalls)
• For MongoDB Atlas, whitelist IP addresses

JWT Verification Failures

Issue: invalid signature or jwt malformed errors Solution:

• Ensure JWT_SECRET is set and at least 32 characters
• Verify system clock is synchronized (JWT is time-sensitive)
• Check token isn't expired (default expiration varies by route)

Port Conflicts

Issue: EADDRINUSE errors on startup Solution:

• Change API port: modify PORT env variable (default: 3000)
• Change client port: use gatsby develop -p 9000 or modify client config

Type Generation Issues

Issue: TypeScript errors about missing types or Prisma client Solution:

cd api
npx prisma generate
# If schema changed:
npx prisma migrate dev

Exam Environment 403 Errors

Issue: Cannot access /exam-environment/exams endpoints Solution:

• Verify user has isHonest: true in database
• Check that user completed prerequisite challenges (query completedChallenges array)
• Ensure JWT token includes required claims

Build Memory Issues

Issue: JavaScript heap out of memory during build Solution:

export NODE_OPTIONS="--max-old-space-size=4096"
pnpm run build