Skip to content

Install & self-host Atlas

Atlas runs as a single service plus a PostgreSQL database. The quickest way to stand it up is Docker Compose.

Requirements

  • Docker with the Compose plugin.
  • A PostgreSQL database (the bundled Compose file provisions one for you).
  • A reverse proxy in front of Atlas for TLS and authentication (any of Caddy, nginx, or Traefik works).

Bring it up

cp .env.example .env
# Edit .env — set a strong DB_PASSWORD at minimum.
docker compose up -d --build

Atlas listens on port 8400. The /health endpoint is anonymous; everything under /api/v1/* requires authentication.

curl http://localhost:8400/health

Authentication modes

Atlas has three auth surfaces that coexist:

  • OIDC login — interactive users log in through your own OpenID Connect provider. See SSO setup.
  • Forward-auth — a reverse proxy plus an identity outpost injects trusted identity headers. Leave OIDC unset to use this model.
  • Machine tokens — non-interactive automation authenticates with Authorization: Bearer atlas_sk_… regardless of the human auth mode.

For local evaluation you can set ATLAS_FORWARD_AUTH=false (the default), which treats every local request as the operator. Do not run with forward-auth disabled on a network-reachable deployment — put Atlas behind a proxy that enforces identity, and set ATLAS_FORWARD_AUTH=true.

The API at a glance

Everything below /api/v1/ is versioned. A few of the read endpoints:

curl http://localhost:8400/api/v1/customers
curl http://localhost:8400/api/v1/customers/<slug>
curl http://localhost:8400/api/v1/deployments?product=<product>

Write endpoints (create/update customers, register deployments, trigger ingest) require operator identity or a scoped machine token. Machine tokens are least-privilege: a token can never delete a customer, mint or revoke tokens, or reach an admin route — its blast radius is exactly the scopes you grant, and it is revocable instantly.

Upgrading

Atlas cuts versioned releases. Pin a version for production and upgrade deliberately; the machine-readable release channel and upgrade flow are still being finalized during alpha.

Getting help

Email support@seglamater.com for installation help, managed hosting, or consulting.