Docker Compose

Docker Compose is the recommended starting point for self-hosting Atomic.

Basic Setup

Clone the repository and start the included compose file:

git clone https://github.com/kenforthewin/atomic.git

cd atomic
docker compose up -d

Open http://localhost:8080 and complete first-run setup.

The default compose file starts:

  • server - ghcr.io/kenforthewin/atomic-server:latest
  • web - ghcr.io/kenforthewin/atomic-web:latest
  • proxy - nginx:1.28-bookworm
  • litestream - optional backup profile

Published image pages:

Public URL

Set PUBLIC_URL when deploying behind a public domain:

PUBLIC_URL=https://atomic.example.com docker compose up -d

PUBLIC_URL is used for OAuth/MCP discovery. Without it, OAuth discovery endpoints return 404.

Reverse Proxy

The included nginx proxy listens on host port 8080. If you already run Caddy, Traefik, nginx, or another proxy, route traffic to the compose services instead.

Your proxy must support:

  • Standard HTTP routes for the web UI and /api/*
  • WebSocket upgrades for /ws
  • MCP traffic for /mcp
  • /.well-known/* routes for OAuth/MCP discovery when using remote auth

Data Persistence

The atomic-data volume stores the registry and data databases. Back this volume up to preserve your knowledge base.

docker volume inspect atomic_atomic-data

Volume names are prefixed by the compose project name, so yours may differ.

Optional Litestream Backup

The compose file includes a litestream service under the backup profile. Configure these environment variables before enabling it:

  • LITESTREAM_ACCESS_KEY_ID
  • LITESTREAM_SECRET_ACCESS_KEY
  • LITESTREAM_BUCKET
  • LITESTREAM_ENDPOINT
  • LITESTREAM_PATH

Then run:

docker compose --profile backup up -d

Upgrade

docker compose pull

docker compose up -d

Check the server after upgrading:

curl http://localhost:8080/health

Troubleshooting

  • Web UI loads but API fails - check proxy routing for /api/*.
  • Chat/ingestion progress does not update - check WebSocket forwarding for /ws.
  • MCP remote auth fails - set PUBLIC_URL and confirm /.well-known/oauth-authorization-server is reachable.
  • Data disappeared after recreation - confirm the persistent volume was reused.