Configuration Reference

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