Complete reference for every environment variable used by AltBase, grouped by subsystem with defaults and descriptions.
Overview
AltBase reads configuration from environment variables at startup. Copy .env.example to .env for local development. In production, inject variables via your deployment platform (Docker, Kubernetes Secrets, etc.).
Required Variables
These variables must be set or the server will not start:
| Variable | Description | Component |
|---|
ATLAS_CONTROL_PLANE_DATABASE_URL | PostgreSQL connection string for the control plane database | atlas-db |
ATLAS_TENANT_DATABASE_URL | PostgreSQL connection string for the tenant database | atlas-db |
ATLAS_REDIS_URL | Redis connection string | atlas-common |
ATLAS_PLATFORM_JWT_SECRET | Secret for platform user JWTs (openssl rand -hex 32) | atlas-auth |
ATLAS_MASTER_KEY | 32-byte hex key for AES-256-GCM encryption (openssl rand -hex 32) | atlas-common |
Server
| Variable | Description | Default | Component |
|---|
ATLAS_HOST | IP address to bind the HTTP server | 0.0.0.0 | atlas-server |
ATLAS_PORT | Port to listen on | 4000 | atlas-server |
ATLAS_DASHBOARD_DIR | Path to built dashboard static files | /home/atlas/dashboard (Docker) | atlas-server |
Database
| Variable | Description | Default | Component |
|---|
ATLAS_CONTROL_PLANE_DATABASE_URL | PostgreSQL connection string for the control plane database | (required) | atlas-db |
ATLAS_TENANT_DATABASE_URL | PostgreSQL connection string for the tenant database | (required) | atlas-db |
ATLAS_DB_POOL_SIZE | Maximum number of connections per connection pool | 20 | atlas-db |
The control plane database stores platform metadata (organizations, projects, API keys, auth settings). The tenant database stores per-project schemas with application data.
Both URLs use standard PostgreSQL connection string format:
postgresql://user:password@host:port/database
WAL Requirements
The tenant database server must have wal_level=logical enabled for CDC to function. This is configured via PostgreSQL server flags, not environment variables.
Cache
| Variable | Description | Default | Component |
|---|
ATLAS_REDIS_URL | Redis connection string | (required) | atlas-common |
Redis is used for:
- Rate limiting -- per-project request counters with sliding windows
- Session cache -- fast JWT validation lookups
- Schema cache -- compiled schema metadata shared across requests
- TUS upload state -- resumable upload progress tracking
- Image transform cache -- cached transformed images
Messaging
| Variable | Description | Default | Component |
|---|
ATLAS_NATS_URL | NATS server connection string | nats://localhost:4222 | atlas-events |
NATS with JetStream handles all async communication:
- CDC fan-out (PostgreSQL WAL to WebSocket clients)
- Workflow step dispatch and completion
- Trigger condition evaluation
- Background job queuing
- Integration webhook delivery
Admin
| Variable | Description | Default | Component |
|---|
ATLAS_ADMIN_EMAILS | Comma-separated list of emails auto-promoted to super_admin on signup | (none) | atlas-control-plane |
ATLAS_APP_URL | Public URL used in email links (must be https in production) | (none) | atlas-common |
Invite-Only Mode
| Variable | Description | Default | Component |
|---|
ATLAS_INVITE_ONLY | Restrict signups to users with valid invite codes | false | atlas-auth |
ATLAS_INVITE_CODES | Comma-separated list of valid invite codes | (none) | atlas-auth |
Resource Limits
| Variable | Description | Default | Component |
|---|
ATLAS_MAX_ORGS_PER_USER | Maximum organizations per user (0 = unlimited) | 3 | atlas-control-plane |
ATLAS_MAX_PROJECTS_PER_ORG | Maximum projects per organization (0 = unlimited) | 5 | atlas-control-plane |
Email (SMTP)
| Variable | Description | Default | Component |
|---|
ATLAS_PLATFORM_SMTP_HOST | SMTP server hostname | (none) | atlas-auth |
ATLAS_PLATFORM_SMTP_PORT | SMTP server port | 465 | atlas-auth |
ATLAS_PLATFORM_SMTP_USER | SMTP username | (none) | atlas-auth |
ATLAS_PLATFORM_SMTP_PASS | SMTP password or API key | (none) | atlas-auth |
ATLAS_PLATFORM_SMTP_FROM | Sender email address | (none) | atlas-auth |
Email is used for magic links, OTP codes, password resets, and invite notifications. Resend is recommended as the SMTP provider.
Subdomain Routing
| Variable | Description | Default | Component |
|---|
ATLAS_BASE_DOMAIN | Base domain for subdomain routing | (none) | atlas-gateway |
ATLAS_CORS_ORIGINS | Comma-separated allowed CORS origins | (permissive in dev) | atlas-server |
Subdomain routing uses the pattern {org-slug}--{project-slug}.altbasedb.com.
Storage
| Variable | Description | Default | Component |
|---|
ATLAS_STORAGE_PROVIDER | Storage backend: filesystem, s3, or azure | filesystem | atlas-storage |
ATLAS_STORAGE_ROOT | Root path for filesystem storage | ./storage-data | atlas-storage |
ATLAS_S3_ENDPOINT | S3-compatible endpoint URL | (none) | atlas-storage |
ATLAS_S3_REGION | S3 region | (none) | atlas-storage |
ATLAS_S3_ACCESS_KEY | S3 access key ID | (none) | atlas-storage |
ATLAS_S3_SECRET_KEY | S3 secret access key | (none) | atlas-storage |
ATLAS_S3_BUCKET | S3 bucket name | (none) | atlas-storage |
ATLAS_AZURE_CONNECTION_STRING | Azure Blob Storage connection string | (none) | atlas-storage |
Billing (Stripe)
| Variable | Description | Default | Component |
|---|
STRIPE_SECRET_KEY | Stripe API secret key | (none) | atlas-billing |
STRIPE_WEBHOOK_SECRET | Stripe webhook signing secret | (none) | atlas-billing |
STRIPE_PRICE_PRO_MONTHLY | Stripe price ID for Pro plan | (none) | atlas-billing |
Search
| Variable | Description | Default | Component |
|---|
ATLAS_SEARCH_INDEX_PATH | Directory for Tantivy search indexes | ./search-data | atlas-search |
Functions
| Variable | Description | Default | Component |
|---|
ATLAS_FUNCTIONS_DIR | Directory for function source code | ./functions-data | atlas-functions |
ATLAS_FUNCTIONS_MAX_EXECUTION_MS | Maximum wall-clock execution time | 10000 | atlas-functions |
ATLAS_FUNCTIONS_MAX_MEMORY_MB | Maximum memory per function invocation | 128 | atlas-functions |
Rate Limiting
| Variable | Description | Default | Component |
|---|
ATLAS_RATE_LIMIT_DISABLED | Disable all rate limiting | false | atlas-gateway |
Set to true only in development. In production, rate limits protect the platform at three tiers:
| Tier | Requests per Minute |
|---|
| Free | 60 |
| Pro | 600 |
| Enterprise | 6000 |
Integrations (Nango)
| Variable | Description | Default | Component |
|---|
ATLAS_NANGO_SERVER_URL | URL of the Nango OAuth proxy | http://nango:3003 (Docker) | atlas-integrations |
ATLAS_NANGO_SECRET_KEY | Secret key for Nango API authentication | (none) | atlas-integrations |
Nango Container Variables
These variables configure the Nango service itself (set on the Nango container, not AltBase):
| Variable | Description | Default |
|---|
NANGO_DB_HOST | PostgreSQL host for Nango | postgres |
NANGO_DB_PORT | PostgreSQL port for Nango | 5432 |
NANGO_DB_USER | Database user | atlas |
NANGO_DB_PASSWORD | Database password | atlas_dev |
NANGO_DB_NAME | Database name | nango |
NANGO_ENCRYPTION_KEY | 64-character hex key for credential encryption | (required) |
NANGO_SERVER_URL | Public URL of the Nango server | http://nango:3003 |
NANGO_DASHBOARD_USERNAME | Admin dashboard username | admin |
NANGO_DASHBOARD_PASSWORD | Admin dashboard password | admin_dev |
NANGO_TELEMETRY | Enable or disable telemetry | false |
Docker Compose Defaults
The docker/docker-compose.yml file overrides the default port to 3000 for local development:
# AtlasDB service
ATLAS_HOST=0.0.0.0
ATLAS_PORT=3000
ATLAS_CONTROL_PLANE_DATABASE_URL=postgres://atlas:atlas_dev@postgres:5432/atlas_control_plane
ATLAS_TENANT_DATABASE_URL=postgres://atlas:atlas_dev@postgres:5432/atlas_tenants
ATLAS_REDIS_URL=redis://redis:6379
ATLAS_DB_POOL_SIZE=20
ATLAS_NATS_URL=nats://nats:4222
ATLAS_RATE_LIMIT_DISABLED=true
ATLAS_NANGO_SERVER_URL=http://nango:3003
# PostgreSQL
POSTGRES_USER=atlas
POSTGRES_PASSWORD=atlas_dev
POSTGRES_DB=atlas_control_plane
Note that inside Docker Compose, hostnames use container names (postgres, redis, nats, nango) rather than localhost. The default server port is 4000 natively but overridden to 3000 in Docker Compose.
.env.example
The repository ships a .env.example with all available variables. For running natively (outside Docker):
# Required
ATLAS_CONTROL_PLANE_DATABASE_URL=postgresql://atlas:YOUR_PASSWORD@localhost:5433/atlas_control_plane
ATLAS_TENANT_DATABASE_URL=postgresql://atlas:YOUR_PASSWORD@localhost:5433/atlas_tenants
ATLAS_REDIS_URL=redis://localhost:6379
ATLAS_PLATFORM_JWT_SECRET= # openssl rand -hex 32
ATLAS_MASTER_KEY= # openssl rand -hex 32
# Server
ATLAS_HOST=0.0.0.0
ATLAS_PORT=4000
ATLAS_NATS_URL=nats://localhost:4222
ATLAS_DB_POOL_SIZE=20
Port 5433 is used because the Docker Compose stack maps PostgreSQL's internal port 5432 to external port 5433 to avoid conflicts with a locally installed PostgreSQL.
Production Recommendations
| Variable | Recommendation |
|---|
ATLAS_PLATFORM_JWT_SECRET | Generate with openssl rand -hex 32, keep secret |
ATLAS_MASTER_KEY | Generate with openssl rand -hex 32, back up securely |
ATLAS_DB_POOL_SIZE | Set to max_connections / number_of_replicas |
ATLAS_RATE_LIMIT_DISABLED | Must be false (or unset) in production |
ATLAS_CORS_ORIGINS | Set explicit origins, never use permissive CORS |
ATLAS_APP_URL | Must be https:// in production |
NANGO_ENCRYPTION_KEY | Generate with openssl rand -hex 32 |
POSTGRES_PASSWORD | Use a strong, unique password |
| Database URLs | Use TLS connections (?sslmode=require) |
ATLAS_NATS_URL | Configure NATS authentication in production |
Adding Custom Variables
AltBase reads only ATLAS_* prefixed variables. If you need custom configuration for functions, triggers, or integrations, store values in the project settings table via the dashboard or API rather than environment variables.