Skip to main content
Brainbox server behavior is controlled through environment variables. This page documents all available configuration options.

​
General Server Settings

​
Node Environment

NODE_ENV=production  # production | development
Controls the runtime environment. Use production for deployments.

​
Server Identity

SERVER_NAME="Brainbox Local"
SERVER_AVATAR=
  • SERVER_NAME: Display name shown in the UI
  • SERVER_AVATAR: URL to server avatar image (optional)

​
Server Mode

SERVER_MODE=standalone  # standalone | cluster
  • standalone: Single server instance (default)
  • cluster: Multiple instances with Redis coordination (required for Kubernetes replicas)
Use cluster mode when running multiple server replicas in Kubernetes or behind a load balancer. This enables proper WebSocket synchronization across instances.

​
Port Configuration

PORT=3000  # Default server port
The port where the Fastify server listens. Default is 3000.

​
Path Prefix

SERVER_PATH_PREFIX=/api  # Optional
Base path for all API routes. Useful when deploying behind a reverse proxy.

​
CORS Settings

SERVER_CORS_ORIGIN=http://localhost:4000
SERVER_CORS_MAX_AGE=7200
  • SERVER_CORS_ORIGIN: Allowed origin for CORS requests
  • SERVER_CORS_MAX_AGE: CORS preflight cache duration in seconds

​
Logging Configuration

LOGGING_LEVEL=info  # trace | debug | info | warn | error | fatal | silent
Controls log verbosity:
  • trace: Most verbose, includes all debug information
  • debug: Detailed debugging information
  • info: General informational messages (default)
  • warn: Warning messages only
  • error: Error messages only
  • fatal: Critical errors only
  • silent: No logging
For production, use info or warn. For development debugging, use debug or:
DEBUG=brainbox:* npm run dev

​
Account Configuration

​
Verification Type

ACCOUNT_VERIFICATION_TYPE=automatic  # automatic | manual | email
  • automatic: New accounts are verified immediately (best for private instances)
  • manual: Admin must manually approve each account
  • email: Email verification required (requires SMTP configuration)

​
OTP Timeout

ACCOUNT_OTP_TIMEOUT=600  # seconds
One-time password expiration time in seconds. Default is 600 (10 minutes).

​
Google OAuth

ACCOUNT_GOOGLE_ENABLED=true
ACCOUNT_GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
ACCOUNT_GOOGLE_CLIENT_SECRET=your-client-secret
Enable Google sign-in. Obtain credentials from Google Cloud Console.

​
Storage Limits

​
Workspace Limits

WORKSPACE_STORAGE_LIMIT=10737418240   # 10 GB in bytes
WORKSPACE_MAX_FILE_SIZE=104857600     # 100 MB in bytes
Optional limits per workspace. Leave empty for unlimited. 
# 1 GB
WORKSPACE_STORAGE_LIMIT=1073741824

# 10 GB
WORKSPACE_STORAGE_LIMIT=10737418240

# 50 GB
WORKSPACE_STORAGE_LIMIT=53687091200

# 100 MB per file
WORKSPACE_MAX_FILE_SIZE=104857600

# 500 MB per file
WORKSPACE_MAX_FILE_SIZE=524288000

​
User Limits

USER_STORAGE_LIMIT=10737418240   # 10 GB in bytes
USER_MAX_FILE_SIZE=104857600     # 100 MB in bytes
Storage limits per user account.
Setting unlimited storage (empty values) is not recommended for production. Always configure appropriate limits to prevent abuse.

​
PostgreSQL Configuration

​
Connection URL

POSTGRES_URL=postgres://colanode_user:postgrespass123@localhost:5432/colanode_db
Full PostgreSQL connection string. Format: 
postgres://[user]:[password]@[host]:[port]/[database]

POSTGRES_URL=postgres://colanode_user:postgrespass123@postgres:5432/colanode_db

​
PostgreSQL SSL

POSTGRES_SSL_REJECT_UNAUTHORIZED=false
POSTGRES_SSL_CA=/path/to/ca-cert.pem
POSTGRES_SSL_KEY=/path/to/client-key.pem
POSTGRES_SSL_CERT=/path/to/client-cert.pem
  • POSTGRES_SSL_REJECT_UNAUTHORIZED: Set to false for self-signed certificates
  • POSTGRES_SSL_CA: Path to CA certificate file
  • POSTGRES_SSL_KEY: Path to client key file
  • POSTGRES_SSL_CERT: Path to client certificate file
For managed databases (RDS, Cloud SQL, Azure Database), SSL is typically required. Download the CA certificate from your provider and configure accordingly.

​
Redis Configuration

​
Connection URL

REDIS_URL=redis://:your_valkey_password@localhost:6379/0
Redis connection string. Format: 
redis://[username]:[password]@[host]:[port]/[db]

REDIS_URL=redis://:your_valkey_password@valkey:6379/0

​
Advanced Redis Settings

REDIS_DB=0
REDIS_JOBS_QUEUE_NAME=jobs
REDIS_JOBS_QUEUE_PREFIX=brainbox
REDIS_TUS_LOCK_PREFIX=brainbox:tus:lock
REDIS_TUS_KV_PREFIX=brainbox:tus:kv
REDIS_EVENTS_CHANNEL=events
  • REDIS_DB: Database number (0-15)
  • REDIS_JOBS_QUEUE_NAME: BullMQ queue name
  • REDIS_JOBS_QUEUE_PREFIX: Key prefix for job queues
  • REDIS_TUS_LOCK_PREFIX: Lock prefix for TUS uploads
  • REDIS_TUS_KV_PREFIX: Key prefix for TUS metadata
  • REDIS_EVENTS_CHANNEL: Pub/sub channel for events
Only modify these if you need custom Redis namespacing or are sharing Redis with other applications.

​
S3 Storage Configuration

​
MinIO (Self-Hosted)

STORAGE_S3_ENDPOINT=http://localhost:9000
STORAGE_S3_ACCESS_KEY=minioadmin
STORAGE_S3_SECRET_KEY=your_minio_password
STORAGE_S3_BUCKET=brainbox
STORAGE_S3_REGION=us-east-1
STORAGE_S3_FORCE_PATH_STYLE=true

STORAGE_S3_ENDPOINT=http://minio:9000
STORAGE_S3_ACCESS_KEY=minioadmin
STORAGE_S3_SECRET_KEY=your_minio_password
STORAGE_S3_BUCKET=brainbox
STORAGE_S3_REGION=us-east-1
STORAGE_S3_FORCE_PATH_STYLE=true

​
AWS S3

STORAGE_S3_ENDPOINT=https://s3.amazonaws.com
STORAGE_S3_ACCESS_KEY=AKIAIOSFODNN7EXAMPLE
STORAGE_S3_SECRET_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
STORAGE_S3_BUCKET=brainbox-production
STORAGE_S3_REGION=us-east-1
STORAGE_S3_FORCE_PATH_STYLE=false

​
Other S3-Compatible Services

STORAGE_S3_ENDPOINT=https://nyc3.digitaloceanspaces.com
STORAGE_S3_ACCESS_KEY=your-access-key
STORAGE_S3_SECRET_KEY=your-secret-key
STORAGE_S3_BUCKET=brainbox
STORAGE_S3_REGION=nyc3
STORAGE_S3_FORCE_PATH_STYLE=false
Set STORAGE_S3_FORCE_PATH_STYLE=true for MinIO and some S3-compatible services. Use false for AWS S3 and most managed S3 services.

​
SMTP Email Configuration

​
Basic SMTP

SMTP_ENABLED=false
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=[email protected]
SMTP_PASSWORD=your-app-password
SMTP_EMAIL_FROM=[email protected]
SMTP_EMAIL_FROM_NAME=Brainbox

SMTP_ENABLED=true
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=[email protected]
SMTP_PASSWORD=your-app-password
SMTP_EMAIL_FROM=[email protected]
SMTP_EMAIL_FROM_NAME=Brainbox
For Gmail, you must create an App Password instead of using your regular password. Regular passwords will not work.

​
Example Configurations

​
Development (Docker Compose)

.env
NODE_ENV=development
SERVER_MODE=standalone
SERVER_NAME="Brainbox Dev"

# PostgreSQL
POSTGRES_URL=postgres://colanode_user:postgrespass123@postgres:5432/colanode_db

# Redis
REDIS_URL=redis://:dev_password@valkey:6379/0

# MinIO
STORAGE_S3_ENDPOINT=http://minio:9000
STORAGE_S3_ACCESS_KEY=minioadmin
STORAGE_S3_SECRET_KEY=minioadmin123
STORAGE_S3_BUCKET=brainbox
STORAGE_S3_REGION=us-east-1
STORAGE_S3_FORCE_PATH_STYLE=true

# Accounts
ACCOUNT_VERIFICATION_TYPE=automatic

# No limits in dev
USER_STORAGE_LIMIT=
USER_MAX_FILE_SIZE=

​
Production (Kubernetes with Managed Services)

values-prod.yaml (partial)
brainbox:
  config:
    NODE_ENV: production
    SERVER_MODE: cluster
    SERVER_NAME: "Brainbox Production"
    
    # Managed PostgreSQL (RDS)
    POSTGRES_URL: "postgres://admin:[email protected]:5432/brainbox"
    POSTGRES_SSL_REJECT_UNAUTHORIZED: "false"
    
    # Managed Redis (ElastiCache)
    REDIS_URL: "redis://:[email protected]:6379/0"
    
    # AWS S3
    STORAGE_S3_ENDPOINT: "https://s3.amazonaws.com"
    STORAGE_S3_ACCESS_KEY: "AKIAIOSFODNN7EXAMPLE"
    STORAGE_S3_SECRET_KEY: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
    STORAGE_S3_BUCKET: "brainbox-prod"
    STORAGE_S3_REGION: "us-east-1"
    STORAGE_S3_FORCE_PATH_STYLE: "false"
    
    # Email verification
    ACCOUNT_VERIFICATION_TYPE: email
    
    # SMTP (SendGrid)
    SMTP_ENABLED: "true"
    SMTP_HOST: "smtp.sendgrid.net"
    SMTP_PORT: "587"
    SMTP_USER: "apikey"
    SMTP_PASSWORD: "SG.your-api-key"
    SMTP_EMAIL_FROM: "[email protected]"
    SMTP_EMAIL_FROM_NAME: "Brainbox"
    
    # Storage limits
    USER_STORAGE_LIMIT: "53687091200"  # 50 GB
    USER_MAX_FILE_SIZE: "524288000"    # 500 MB

​
Environment File Security

Never commit .env files containing secrets to version control. Always use .env.example for templates and .gitignore for actual .env files.

​
Best Practices

  1. Use strong passwords: Generate random passwords for all services 
    openssl rand -base64 32
  2. Store secrets securely:
    • Use Kubernetes Secrets for K8s deployments
    • Use AWS Secrets Manager, HashiCorp Vault, etc. for production
    • Never log or expose secrets in error messages
  3. Rotate credentials regularly: Change passwords periodically
  4. Limit access: Only give credentials to services that need them
  5. Use separate environments: Different credentials for dev/staging/production

​
Next Steps

Docker Setup

Deploy with Docker Compose

Kubernetes Setup

Deploy on Kubernetes

Troubleshooting

Resolve configuration issues

Build docs developers (and LLMs) love

Get started for freeTalk to us