Configuration Reference
All configuration files, settings, and runtime knobs for deploying and operating AltBase.
Configuration Overview
AltBase is configured through environment variables and a small number of configuration files. The server reads environment variables at startup and does not require a central config file -- the .env file is a convenience for local development.
Environment Variable Categories
All environment variables use the ATLAS_ prefix. See the dedicated Environment Variables page for the full list.
| Category | Key Variables | Purpose |
|---|---|---|
| Server | ATLAS_HOST, ATLAS_PORT | Bind address and port |
| Database | ATLAS_CONTROL_PLANE_DATABASE_URL, ATLAS_TENANT_DATABASE_URL | PostgreSQL connection strings |
| Connection Pool | ATLAS_DB_POOL_SIZE | Maximum connections per pool |
| Redis | ATLAS_REDIS_URL | Cache, sessions, rate limits, TUS state |
| NATS | ATLAS_NATS_URL | Message broker for CDC, jobs, workflows |
| Rate Limiting | ATLAS_RATE_LIMIT_DISABLED | Disable rate limits (dev only) |
| Integrations | ATLAS_NANGO_SERVER_URL, ATLAS_NANGO_SECRET_KEY | Nango OAuth proxy |
| Dashboard | ATLAS_DASHBOARD_DIR | Path to built dashboard static files |
Configuration Files
Provider Presets (config/provider_presets.toml)
This TOML file defines OAuth and OIDC provider presets that populate the auth setup wizard and SSO configuration UI. Each preset includes the provider's protocol, endpoints, scopes, attribute mapping, and documentation link.
[[presets]]
name = "google"
display_name = "Google"
protocol = "oidc"
discovery_url = "https://accounts.google.com/.well-known/openid-configuration"
default_scopes = "openid email profile"
icon_url = "/icons/google.svg"
docs_url = "https://console.cloud.google.com/apis/credentials"
[presets.attribute_mapping]
email = "email"
name = "name"
avatar_url = "picture"
provider_id = "sub"
Available Presets
The file ships with 47 provider presets organized into categories:
| Category | Providers |
|---|---|
| Big 4 | Google, Apple, Microsoft, Facebook |
| Developer | GitHub, GitLab, Bitbucket |
| Messaging | Slack, Discord, Telegram, LINE |
| Social | Twitter/X, LinkedIn, Twitch, Spotify, TikTok, Reddit |
| Productivity | Notion, Zoom, Figma, Dropbox, Shopify, Salesforce |
| Enterprise IdPs | Okta, Azure AD/Entra ID, Auth0, OneLogin, PingIdentity, JumpCloud, Google Workspace, Keycloak |
Protocol Types
| Protocol | How It Works |
|---|---|
oidc | Uses a discovery_url to fetch endpoints automatically |
oauth2 | Requires explicit authorize_url, token_url, and userinfo_url |
Some presets use discovery_url_template with template_fields for providers that require a tenant-specific domain (e.g., Okta, Azure AD, Keycloak):
[[presets]]
name = "okta"
protocol = "oidc"
discovery_url_template = "https://{domain}/.well-known/openid-configuration"
template_fields = ["domain"]
Attribute Mapping
Every preset maps the provider's user info response to standard AltBase fields:
| AltBase Field | Description |
|---|---|
email | User's email address |
name | Display name |
avatar_url | Profile picture URL |
provider_id | Unique identifier from the provider |
groups | Group membership (enterprise IdPs only) |
Database Configuration
Two Database Contexts
AltBase uses two separate PostgreSQL databases (which can be on the same server or different servers):
| Database | Variable | Contents |
|---|---|---|
| Control Plane | ATLAS_CONTROL_PLANE_DATABASE_URL | Organizations, projects, API keys, auth settings, SSO configs, billing, connector templates |
| Tenant | ATLAS_TENANT_DATABASE_URL | Per-project schemas (proj_{id}) containing user data, auth tables, storage metadata |
Connection Pooling
The ATLAS_DB_POOL_SIZE variable controls the maximum number of connections in each pool. The default is 20. In production, size this based on your PostgreSQL max_connections setting divided by the number of AtlasDB replicas.
WAL Configuration
CDC (Change Data Capture) requires logical replication. The PostgreSQL server must start with:
wal_level=logical
max_replication_slots=10
max_slot_wal_keep_size=4GB
These are set automatically in the Docker Compose stack.
Redis Configuration
Redis is used for four purposes:
| Purpose | Key Pattern |
|---|---|
| Rate limiting | rl:{project_id}:{read|write}:{window} |
| Session cache | session:{token} |
| Schema cache | schema:{project_id} |
| TUS upload state | tus:{upload_id} |
Configure via ATLAS_REDIS_URL. The URL follows standard Redis URI format: redis://[password@]host:port[/db].
NATS Configuration
NATS must run with JetStream enabled (--jetstream flag). The subject naming convention is:
atlasdb.events.{project_id}.{event_type}
atlasdb.{project_id}.{environment_id}.{table}.{INSERT|UPDATE|DELETE}
atlasdb.jobs.{project_id}
atlasdb.workflows.{project_id}.{run_id}
atlasdb.triggers.{project_id}
Configure via ATLAS_NATS_URL using standard NATS URI format: nats://host:port.
Storage Backend Configuration
AltBase supports pluggable storage backends via the StorageProvider trait:
| Backend | When to Use |
|---|---|
| Azurite | Local development (default in Docker Compose) |
| Azure Blob Storage | Production on Azure |
| Amazon S3 | Production on AWS |
| Local Filesystem | Simple deployments without object storage |
The backend is selected via environment variables. The Azurite emulator runs on ports 10000 (blob) and 10001 (queue) in the development stack.
Rate Limiting
Rate limits are applied per-project based on the project tier:
| Tier | Read Requests/min | Write Requests/min |
|---|---|---|
| Free | 60 | 60 |
| Pro | 600 | 600 |
| Enterprise | 6000 | 6000 |
Set ATLAS_RATE_LIMIT_DISABLED=true to disable rate limiting in development.
Nango Integration Configuration
| Variable | Description |
|---|---|
ATLAS_NANGO_SERVER_URL | URL of the Nango server (e.g., http://nango:3003) |
ATLAS_NANGO_SECRET_KEY | Secret key for authenticating with Nango |
NANGO_ENCRYPTION_KEY | 64-character hex key for encrypting credentials at rest |
NANGO_DASHBOARD_USERNAME | Username for the Nango admin dashboard |
NANGO_DASHBOARD_PASSWORD | Password for the Nango admin dashboard |