Skip to main content

Environment Variables Configuration

FSS uses environment variables for configuration across all packages. This guide covers all available environment variables and how to set them up.

Backend Environment Variables​

Create a .env file in the projects/fss/backend directory:

Database Configuration​

# Database
DATABASE_URL="postgresql://user:password@localhost:5432/fss"
DATABASE_HOST="localhost"
DATABASE_PORT=5432
DATABASE_USER="fss_user"
DATABASE_PASSWORD="your-secure-password"
DATABASE_NAME="fss"

# Prisma
NODE_ENV="development"

Redis Configuration​

# Redis
REDIS_HOST="localhost"
REDIS_PORT=6379
REDIS_PASSWORD=""
REDIS_DB=0

# Rate Limiting
REDIS_THROTTLE_TTL=60
REDIS_THROTTLE_LIMIT=100

JWT Configuration​

# JWT Secrets (Generate secure random strings for production)
JWT_SECRET="your-super-secret-jwt-key-min-32-chars"
JWT_REFRESH_SECRET="your-super-secret-refresh-key-min-32-chars"

# Token Expiration
JWT_EXPIRES_IN="15m"
JWT_REFRESH_EXPIRES_IN="7d"
JWT_REMEMBER_ME_EXPIRES_IN="30d"

# MFA
JWT_TOTP_ISSUER="FSS"

Email Configuration​

# SMTP Settings
SMTP_HOST="smtp.example.com"
SMTP_PORT=587
SMTP_USER="[email protected]"
SMTP_PASSWORD="your-email-password"
SMTP_FROM="[email protected]"
SMTP_FROM_NAME="FSS"

# Email Queue
EMAIL_QUEUE_NAME="email"
EMAIL_RETRY_ATTEMPTS=3
EMAIL_RETRY_DELAY=1000

CAPTCHA Configuration​

# reCAPTCHA v2
RECAPTCHA_SECRET_KEY="your-recaptcha-secret-key"
RECAPTCHA_SITE_KEY="your-recaptcha-site-key"

# Cloudflare Turnstile (Alternative)
TURNSTILE_SECRET_KEY="your-turnstile-secret"
TURNSTILE_SITE_KEY="your-turnstile-site-key"

# hCaptcha (Alternative)
HCAPTCHA_SECRET_KEY="your-hcaptcha-secret"
HCAPTCHA_SITE_KEY="your-hcaptcha-site-key"

# CAPTCHA Provider Selection
CAPTCHA_PROVIDER="recaptcha"  # Options: recaptcha, turnstile, hcaptcha

Security Settings​

# Password Requirements
PASSWORD_MIN_LENGTH=8
PASSWORD_REQUIRE_UPPERCASE=true
PASSWORD_REQUIRE_LOWERCASE=true
PASSWORD_REQUIRE_NUMBER=true
PASSWORD_REQUIRE_SPECIAL=true

# Account Lockout
MAX_LOGIN_ATTEMPTS=5
LOCKOUT_DURATION=15  # minutes

# Session Settings
SESSION_MAX_CONCURRENT=5
SESSION_TIMEOUT=30  # minutes

API Configuration​

# API Settings
API_PREFIX="/api"
API_VERSION="v1"

# CORS
CORS_ORIGIN="http://localhost:3000"
CORS_METHODS="GET,POST,PUT,DELETE,PATCH"
CORS_CREDENTIALS=true

# Rate Limiting
THROTTLE_TTL=60
THROTTLE_LIMIT=100

AI Provider Configuration​

FSS includes an optional multi-provider AI module. Add any or all of these keys to activate the corresponding provider — omitting a key simply disables that provider with no errors.

# Anthropic (Claude)
ANTHROPIC_API_KEY="sk-ant-api03-..."

# OpenAI (GPT)
OPENAI_API_KEY="sk-..."

# Google Gemini
GOOGLE_AI_API_KEY="AIzaSy..."

# Groq
GROQ_API_KEY="gsk_..."

See AI Integrations for usage and available models.

Monitoring & Observability​

# OpenTelemetry
OTEL_ENABLED=false
OTEL_SERVICE_NAME="fss-backend"
OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"

# Prometheus
PROMETHEUS_ENABLED=true
PROMETHEUS_PATH="/metrics"

# Health Check
HEALTH_CHECK_INTERVAL=30000

Frontend Environment Variables​

Create a .env.local file in the projects/fss/frontend directory:

API Configuration​

# API URL
NEXT_PUBLIC_API_URL="https://localhost:3443"
NEXT_PUBLIC_APP_URL="http://localhost:3000"

# API Timeout
NEXT_PUBLIC_API_TIMEOUT=10000

Authentication​

# Token Names
NEXT_PUBLIC_JWT_TOKEN_NAME="auth_token"
NEXT_PUBLIC_REFRESH_TOKEN_NAME="refresh_token"

# Token Storage
NEXT_PUBLIC_TOKEN_STORAGE="cookie"  # Options: cookie, localStorage

Security​

# CAPTCHA
NEXT_PUBLIC_CAPTCHA_SITE_KEY="your-site-key"

# CSP
NEXT_PUBLIC_CSP_NONCE_ENABLED=true

Feature Flags​

NEXT_PUBLIC_ENABLE_MFA=true
NEXT_PUBLIC_ENABLE_RECAPTCHA=true
NEXT_PUBLIC_ENABLE_ANALYTICS=false

Mobile Environment Variables​

Create a .env file in the projects/fss/mobile directory:

API Configuration​

# API URL
EXPO_PUBLIC_API_URL="https://your-backend-api.com"

Features​

EXPO_PUBLIC_ENABLE_PUSH_NOTIFICATIONS=true
EXPO_PUBLIC_ENABLE_OFFLINE_MODE=true

Security​

# Certificate Pinning (Production only)
EXPO_PUBLIC_ENABLE_CERTIFICATE_PINS=true

Docker Environment Variables​

Create a .env file in the root directory for Docker Compose:

# PostgreSQL
POSTGRES_USER=fss_user
POSTGRES_PASSWORD=secure-password
POSTGRES_DB=fss

# Redis
REDIS_PASSWORD=redis-password

# Backend
BACKEND_PORT=3443
NODE_ENV=production

# Frontend
NEXT_PUBLIC_API_URL=https://api.yourdomain.com

Environment-Specific Configuration​

Development (.env.development)​

NODE_ENV=development
DEBUG=true
LOG_LEVEL=debug

Production (.env.production)​

NODE_ENV=production
DEBUG=false
LOG_LEVEL=error

Security Best Practices​

⚠️ Important Security Notes​

  1. Never commit .env files to version control
  2. Use strong, random secrets for all JWT keys
  3. Rotate secrets regularly
  4. Use different secrets for development and production
  5. Validate all environment variables at startup

Generating Secure Secrets​

# Generate JWT secret
openssl rand -base64 32

# Generate password
openssl rand -base64 16

# Generate API key
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Validation​

FSS validates environment variables on startup:

// Example: Required environment variables
const requiredEnvVars = [
  'DATABASE_URL',
  'JWT_SECRET',
  'JWT_REFRESH_SECRET',
];

requiredEnvVars.forEach((envVar) => {
  if (!process.env[envVar]) {
    throw new Error(`Missing required environment variable: ${envVar}`);
  }
});

Next Steps​