Environment Setup

CORTEX uses environment variables for all configuration. This guide covers all available settings.

Required Variables

These variables must be set for CORTEX to start:

Variable	Description	Example
DATABASE_URL	PostgreSQL connection string	postgresql://user:pass@localhost:5432/cortex
JWT_SECRET	Secret for signing access tokens (min 32 chars)	your-super-secret-jwt-key
JWT_REFRESH_SECRET	Secret for signing refresh tokens (min 32 chars)	your-refresh-secret-key

Optional Variables

Server Configuration

Variable	Description	Default
PORT	HTTP server port	8091
NODE_ENV	Environment (development, staging, production)	development
CORS_ORIGINS	Comma-separated list of allowed origins	http://localhost:3090

JWT Configuration

Variable	Description	Default
JWT_ACCESS_EXPIRY	Access token expiry	15m
JWT_REFRESH_EXPIRY	Refresh token expiry	7d

Security Configuration

Variable	Description	Default
RATE_LIMIT_TTL	Rate limit window in seconds	60
RATE_LIMIT_MAX	Max requests per window	100
LOCKOUT_THRESHOLD	Failed login attempts before lockout	5
LOCKOUT_DURATION_MINUTES	Lockout duration	15

Redis Configuration (Optional)

Variable	Description	Default
REDIS_URL	Redis connection string	redis://localhost:6379
REDIS_HOST	Redis host (if not using URL)	localhost
REDIS_PORT	Redis port	6379

Example .env File

# Database
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/cortex?schema=public"

# JWT Secrets (generate with: openssl rand -base64 32)
JWT_SECRET="your-super-secret-jwt-key-at-least-32-characters-long"
JWT_REFRESH_SECRET="your-refresh-secret-key-at-least-32-characters-long"

# Server
PORT=8091
NODE_ENV=development
CORS_ORIGINS=http://localhost:3090,http://localhost:3000

# JWT Expiry
JWT_ACCESS_EXPIRY=15m
JWT_REFRESH_EXPIRY=7d

# Security
RATE_LIMIT_TTL=60
RATE_LIMIT_MAX=100
LOCKOUT_THRESHOLD=5
LOCKOUT_DURATION_MINUTES=15

# Redis (optional)
REDIS_URL=redis://localhost:6379

Generating Secrets

Use OpenSSL to generate secure secrets:

# Generate JWT secret
openssl rand -base64 32

# Generate refresh secret
openssl rand -base64 32

Environment-Specific Configuration

Development

NODE_ENV=development
JWT_ACCESS_EXPIRY=1h  # Longer expiry for convenience

Staging

NODE_ENV=staging
CORS_ORIGINS=https://staging.myapp.com

Production

NODE_ENV=production
CORS_ORIGINS=https://myapp.com
RATE_LIMIT_MAX=50  # Stricter rate limiting

Validation

CORTEX validates all environment variables on startup. If a required variable is missing or invalid, the application will fail to start with a descriptive error message.

Error: JWT_SECRET must be at least 32 characters