Environment Variables Ceboelha API uses environment variables for configuration. All configuration is done through a .env file in the project root.
Create environment file
Copy the example environment file:
Configure required variables
Open .env and configure the required variables listed below.
Required Variables The following environment variables are required . The application will not start without them.
Database Connection MONGODB_URI = mongodb://localhost:27017/ceboelha
The MongoDB connection string. See Database Setup for different configuration options.
JWT Secrets JWT_ACCESS_SECRET = your-super-secret-access-key-at-least-32-characters-long JWT_REFRESH_SECRET = your-super-secret-refresh-key-at-least-32-characters-long
JWT secrets must be at least 32 characters long for security. The application will validate this on startup.
Generate secure secrets: Optional Variables Server Configuration PORT = 3333 NODE_ENV = development
Variable Default Description PORT3333Port the server listens on NODE_ENVdevelopmentEnvironment mode: development, production, or test
JWT Token Expiration JWT_ACCESS_EXPIRES_IN = 15m JWT_REFRESH_EXPIRES_IN = 7d
Variable Default Description JWT_ACCESS_EXPIRES_IN15mAccess token lifetime (short-lived for security) JWT_REFRESH_EXPIRES_IN7dRefresh token lifetime (long-lived)
Access tokens should be short-lived (15 minutes) for security. Refresh tokens can be longer-lived (7 days).
CORS Configuration CORS_ORIGIN = http://localhost:3000
Comma-separated list of allowed origins for CORS requests.
Examples: # Single origin CORS_ORIGIN = http://localhost:3000 # Multiple origins CORS_ORIGIN = http://localhost:3000,https://app.example.com # Allow all origins (not recommended for production) CORS_ORIGIN = *
Rate Limiting General API Rate Limiting RATE_LIMIT_MAX = 100 RATE_LIMIT_WINDOW = 60000
Variable Default Description RATE_LIMIT_MAX100Maximum requests per window RATE_LIMIT_WINDOW60000Time window in milliseconds (60000ms = 1 minute)
Default: 100 requests per minute
Authentication Rate Limiting AUTH_RATE_LIMIT_MAX = 5 AUTH_RATE_LIMIT_WINDOW = 900000
Variable Default Description AUTH_RATE_LIMIT_MAX5Maximum auth attempts per window AUTH_RATE_LIMIT_WINDOW900000Time window in milliseconds (900000ms = 15 minutes)
Default: 5 attempts per 15 minutes (stricter to prevent brute force attacks)
Security Settings Account Lockout MAX_LOGIN_ATTEMPTS = 5 LOCKOUT_DURATION = 900000
Variable Default Description MAX_LOGIN_ATTEMPTS5Failed login attempts before lockout LOCKOUT_DURATION900000Lockout duration in milliseconds (900000ms = 15 minutes)
After 5 failed login attempts, the account will be locked for 15 minutes.
Password Hashing Variable Default Description BCRYPT_SALT_ROUNDS12Bcrypt salt rounds for password hashing
Higher values are more secure but slower. 12 is recommended for production. For testing, you can use 10 for faster performance.
Environment Validation Ceboelha API automatically validates environment variables on startup:
Required variables must be presentJWT secrets must be at least 32 characters longNumeric values are validated and converted to numbers
If validation fails, the application will exit with a clear error message:
❌ Missing required environment variable: MONGODB_URI
or
❌ JWT_ACCESS_SECRET must be at least 32 characters
Complete Example Here’s a complete .env file example:
# Server PORT = 3333 NODE_ENV = development # Database MONGODB_URI = mongodb://localhost:27017/ceboelha # JWT JWT_ACCESS_SECRET = a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6 JWT_ACCESS_EXPIRES_IN = 15m JWT_REFRESH_SECRET = z9y8x7w6v5u4t3s2r1q0p9o8n7m6l5k4j3i2h1g0f9e8d7c6b5a4 JWT_REFRESH_EXPIRES_IN = 7d # CORS CORS_ORIGIN = http://localhost:3000 # Rate Limiting RATE_LIMIT_MAX = 100 RATE_LIMIT_WINDOW = 60000 AUTH_RATE_LIMIT_MAX = 5 AUTH_RATE_LIMIT_WINDOW = 900000 # Security MAX_LOGIN_ATTEMPTS = 5 LOCKOUT_DURATION = 900000 BCRYPT_SALT_ROUNDS = 12
Next Steps
Database Setup Configure MongoDB and understand database options
Authentication Learn how to authenticate API requests