Self-hosting Atlas
- Written for
- ＋ Written for
- Deprecated
- ＋ Deprecated
- Applies to
- ＋ Applies to
Self-hosting Atlas
Atlas is self-hostable — you can run the entire platform on your own infrastructure and keep every user, key, and session inside your own boundary. This page is a high-level map of a deployment; your dashboard and repository carry the exact, version-specific steps.
What runs
An Atlas deployment is three services plus two datastores:
Component | What it does |
|---|---|
api | The Frontend API (FAPI), Backend API (BAPI), and dashboard API. |
web | The dashboard single-page app (served as static files). |
worker | Background jobs — webhook delivery, sweeps, and other async work. |
Postgres | The system of record: users, sessions, organizations, keys, configuration. |
Redis | Caching and ephemeral coordination. Treated as losable — sign-in keeps working from Postgres if Redis is lost. |
One origin
The dashboard SPA and the API must be served same-site over HTTPS. The refresh-token cookie is Secure, SameSite=Lax, and path-scoped to the API, so a split-origin setup won't hold a session. Put both behind one host and route by path (for example, /v1 and /.well-known to the API, everything else to the web app).
Configuration essentials
Configuration is environment-driven. The values you must set:
DATABASE_URL— your Postgres connection string (Atlas uses a dedicated database).REDIS_URL— your Redis connection string.DATA_ENCRYPTION_KEY— a 32+ byte base64 root key for envelope encryption of secrets at rest. Generate it once and keep it stable: rotating it makes existing encrypted provider secrets undecryptable. Generate withopenssl rand -base64 48.ATLAS_ORIGIN/ host — the public HTTPS origin the deployment is served from.
Email is per-instance, not env
Outbound email is configured per instance as an encrypted bring-your-own-key provider row (dashboard → Messaging), not as a global environment secret — so each instance sends from its own verified domain. A simple env-managed mailer (Resend / SES / Brevo / Mailgun) exists as an optional path for the most basic self-host, but the per-instance provider is the norm.
Bring it up
Create the database on your Postgres.
Deploy the api, web, and worker images behind your single HTTPS origin.
Migrate the database using the shipped migration entrypoint.
Bootstrap the platform instance and an admin user (the bootstrap script prints a generated password when you don't supply one).
Sign in to the dashboard at your origin with the admin credentials, then create your first application.
Operations
Atlas is built to be operated: key signing supports ordinary rotation (old public key kept published briefly so in-flight tokens still verify) and an emergency rotation that drops the old key with zero grace. Sessions can be revoked instance-wide by bumping a sessions version. Kill switches — disabling a flaky OAuth provider, for instance — are config flags that take effect on the next request, not redeploys. Audit logs are append-only.
Running Atlas in production? Email support@atlasauth.net.