What Environment Variables Are Required to Run the freeCodeCamp API Server?

To start the freeCodeCamp API server, you must set twelve mandatory environment variables validated at startup in api/src/utils/env.ts, including HOME_LOCATION, API_LOCATION, AUTH0_CLIENT_ID, AUTH0_CLIENT_SECRET, AUTH0_DOMAIN, JWT_SECRET, STRIPE_SECRET_KEY, MONGOHQ_URL, and COOKIE_SECRET, with additional variables required for production deployments.

The freeCodeCamp open-source repository (freeCodeCamp/freeCodeCamp) provides a comprehensive curriculum platform backed by a Fastify-based API server. Before the server can handle authentication, payments, or database queries, it validates that all required environment variables are present in process.env. According to the source code in api/src/utils/env.ts, missing variables trigger an immediate assertion error that prevents startup.

Core Required Environment Variables

The API groups mandatory variables into functional categories. If any of these are undefined, the server throws an AssertionError and exits.

Application URLs and Deployment Context

Three variables define where the API runs and how it constructs links:

• HOME_LOCATION: The base URL for client-side redirects and navigation (e.g., https://localhost:8000). Referenced at lines 54-55.
• API_LOCATION: The public endpoint for API requests, used to build absolute URLs (line 61).
• DEPLOYMENT_ENV: Specifies the runtime context as development, staging, or production (line 56).

Authentication Provider Credentials

The integration with Auth0 and internal JWT signing requires four secrets:

• AUTH0_CLIENT_ID: The OAuth client identifier.
• AUTH0_CLIENT_SECRET: The confidential secret for token exchange.
• AUTH0_DOMAIN: The tenant domain (e.g., dev-12345.auth0.com).
• JWT_SECRET: A private key for signing JSON Web Tokens that protect API routes.

These are validated together at lines 58-63.

Database and Payment Processing

• MONGOHQ_URL: The MongoDB connection string. The code derives test-specific URLs from this value at lines 64-71.
• STRIPE_SECRET_KEY: The private key for processing donations and payments, checked at lines 62-64.

Session Security

• COOKIE_SECRET: A secret key for signing encrypted session cookies (lines 65-66).

Production-Specific Environment Variables

When DEPLOYMENT_ENV is set to production, the API enforces additional required variables for external services.

AWS SES Email Configuration

The email provider defaults to ses in production, requiring AWS credentials:

• EMAIL_PROVIDER: Must be set to ses in production environments (lines 32-33).
• SES_ID: AWS SES access key ID (lines 95-96).
• SES_SECRET: AWS SES secret access key (lines 95-99).
• SES_REGION: Optional, defaults to us-east-1 (lines 112-113).
• COOKIE_DOMAIN: Required in production to set the cookie domain attribute (lines 102-103).

Observability and Error Tracking

• SENTRY_DSN: The Data Source Name for Sentry error tracking (lines 104-107).
• SENTRY_ENVIRONMENT: Environment label sent to Sentry (e.g., production) (lines 104-107).
• DEPLOYMENT_VERSION: Version identifier shown in logs and telemetry (lines 106-108).

Growthbook Feature Flagging

For A/B testing in production:

• GROWTHBOOK_FASTIFY_API_HOST: The Growthbook SDK host endpoint (lines 144-150).
• GROWTHBOOK_FASTIFY_CLIENT_KEY: The client key for fetching feature flags (lines 152-158).

Optional Feature Flags for Development

The API supports several boolean toggles that are not required but enable debugging tools:

• FCC_ENABLE_SWAGGER_UI: Exposes interactive API documentation at /documentation (lines 84-89).
• FCC_ENABLE_DEV_LOGIN_MODE: Allows shortcut authentication for local development (must be false in production) (lines 88-90).
• FCC_ENABLE_SHADOW_CAPTURE: Enables request shadowing for traffic replication (lines 91-94).
• FCC_ENABLE_SENTRY_ROUTES: Activates Sentry performance tracing for route handlers (lines 94-96).

Validating Configuration at Startup

The api/src/utils/env.ts file acts as the central authority for environment configuration. During module initialization, it asserts the presence of each required variable using Node.js assert statements. If validation fails, the process exits immediately with a descriptive error:

AssertionError [ERR_ASSERTION]: HOME_LOCATION not set

This strict validation prevents runtime errors in production by ensuring the Fastify server only starts with a complete configuration.

Local Development Setup

To configure the API for local development:

1. Copy the sample environment file from the repository root:

cp sample.env .env

2. Edit .env to include the mandatory variables. A minimal development configuration includes:

HOME_LOCATION=https://localhost:8000
API_LOCATION=http://localhost:8000/api
DEPLOYMENT_ENV=development
AUTH0_CLIENT_ID=your_auth0_client_id
AUTH0_CLIENT_SECRET=your_auth0_client_secret
AUTH0_DOMAIN=your-tenant.auth0.com
JWT_SECRET=your_jwt_secret
STRIPE_SECRET_KEY=sk_test_your_key
MONGOHQ_URL=mongodb://localhost:27017/freecodecamp
COOKIE_SECRET=your_cookie_secret

3. Install dependencies and build the TypeScript source:

npm ci
npm run build

4. Start the server:

npm start

The server will bind to the configured ports only after api/src/utils/env.ts confirms all assertions pass.

Summary

• Twelve core variables are mandatory for every environment: HOME_LOCATION, API_LOCATION, DEPLOYMENT_ENV, AUTH0_CLIENT_ID, AUTH0_CLIENT_SECRET, AUTH0_DOMAIN, JWT_SECRET, STRIPE_SECRET_KEY, MONGOHQ_URL, and COOKIE_SECRET.
• Production deployments require additional AWS SES credentials (SES_ID, SES_SECRET), Sentry configuration (SENTRY_DSN, SENTRY_ENVIRONMENT), and Growthbook keys (GROWTHBOOK_FASTIFY_API_HOST, GROWTHBOOK_FASTIFY_CLIENT_KEY).
• Validation occurs in api/src/utils/env.ts, which throws an AssertionError if any required variable is missing.
• Optional flags like FCC_ENABLE_SWAGGER_UI and FCC_ENABLE_DEV_LOGIN_MODE facilitate local development without affecting production security.

Frequently Asked Questions

What happens if I forget to set a required environment variable?

The API server performs strict validation during the startup sequence in api/src/utils/env.ts. If any mandatory variable is undefined, the application throws an AssertionError with the specific variable name and exits immediately. This prevents the Fastify server from starting with an incomplete configuration.

Can I run the freeCodeCamp API without Auth0 credentials?

No. The source code explicitly requires AUTH0_CLIENT_ID, AUTH0_CLIENT_SECRET, and AUTH0_DOMAIN at lines 58-60. These credentials are essential for the OAuth authentication flow that protects user accounts and API endpoints.

Is MongoDB required to start the server?

Yes. The MONGOHQ_URL variable is mandatory for database connectivity. The validation logic at lines 64-71 checks for this connection string, and the server cannot initialize without it.

Do I need AWS SES credentials for local development?

No. The SES_ID, SES_SECRET, and related email variables are only enforced when DEPLOYMENT_ENV is set to production. For local development, you can omit these or leave them empty, though transactional emails will not function without valid AWS credentials.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}