Documentation
Getting started
Self-hosting
Concepts
Sign-in methods
Organizations & teams
Enterprise SSO & SCIM
Customization
Security
Integrations & operations
For AI agents

Configuration & secrets

AdminUpdated Sep 11, 2026

Configuration & secrets

Atlas is configured almost entirely through environment variables (deploy/atlas.env.example is the annotated reference). Most are plumbing; a few are secrets you must handle carefully — above all the root encryption key.

Core configuration

Variable

Purpose

DATABASE_URL

PostgreSQL connection string

REDIS_URL

Redis connection string

DATA_ENCRYPTION_KEY

The root key for envelope encryption (below)

PLATFORM_INSTANCE_ID

The instance that authenticates the dashboard

ATLAS_ORIGIN / FAPI_ORIGIN / BAPI_ORIGIN

The single HTTPS origin the app and API share

NODE_ENV

production by default

The root encryption key

DATA_ENCRYPTION_KEY is the most important secret in the system. Atlas uses envelope encryption: the root key wraps a per-instance data key, and those data keys encrypt every sensitive value — OAuth provider secrets, refresh tokens, BYOK messaging credentials, CAPTCHA and Stripe secrets.

Generate it once and keep it stable:

openssl rand -base64 48

Two rules that matter enormously:

  • Back it up off-box. Store the value in a password manager or secrets vault, separate from your database backups, recoverable by at least two people. A database backup is useless without the key that decrypts it.

  • Rotating it is not a re-key. Changing DATA_ENCRYPTION_KEY orphans every existing ciphertext — provider secrets and refresh tokens become undecryptable. Never rotate it without a re-encryption migration.

Optional: wrap the root key with a KMS (Vault transit)

For production you can keep the raw key out of plaintext env. Atlas can store a sealed vault:v1:… ciphertext and unseal it at boot via HashiCorp Vault's transit engine:

  1. Enable transit and create a non-exportable wrapping key (transit/keys/atlas-root).

  2. Wrap your existing key with node deploy/wrap-root-key.mjs — this seals the same key, so nothing already encrypted breaks.

  3. Set DATA_ENCRYPTION_KEY to the vault:v1:… output and give the app VAULT_ADDR, VAULT_TRANSIT_KEY and a decrypt-only VAULT_TOKEN.

Startup is fail-closed: if Vault is unreachable or the token is unauthorized, the service refuses to boot rather than run with a key it can't recover. Keep the raw key in your password manager as the break-glass copy.

Optional integrations

Everything else degrades gracefully when unset:

  • Asset storage (S3-compatible / Cloudflare R2) — enables logo/avatar uploads; unset means uploads return 503 and nothing else changes.

  • Stripe (STRIPE_SECRET_KEY, STRIPE_PRICE_PRO, STRIPE_WEBHOOK_SECRET) — billing; unset means billing is simply "not configured".

  • Email/SMS — sending is per-instance BYOK, configured in the dashboard, not env. An optional env-managed mailer exists for simple self-hosts.

  • OpenTelemetry (OTEL_EXPORTER_OTLP_ENDPOINT) and Sentry-compatible error reporting (SENTRY_DSN) — observability; unset means the SDKs aren't even loaded.

  • GeoIP / network signals — baked into the image; a missing file resolves to "no geo" harmlessly.

Next

Keep it safe and keep it current → Backups & upgrades.

Was this page helpful?