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

Backups & upgrades

AdminUpdated Sep 11, 2026

Backups & upgrades

Once Atlas is holding real accounts, two operational disciplines matter more than anything else: backups (of both the database and the root key) and a safe upgrade path.

Back up the database

There is no backup unless you set one up. Do at least one of:

  • Scheduled backup to off-box storage — in Coolify, enable a daily scheduled backup on the Postgres resource with an S3 destination and a retention window. Confirm a backup actually lands in the bucket.

  • cron pg_dump — dump atlas on a schedule and copy the gzip off the box (S3/rclone). A backup on the same disk as the database is not a backup.

Do a restore drill

A backup you have never restored is a guess. Restore a dump into a throwaway database and diff row counts:

gunzip -c atlas-YYYYMMDD.sql.gz | psql -U postgres -d atlas_restore_test

Back up the root key

Separately from the database, store DATA_ENCRYPTION_KEY in a secrets vault or password manager, recoverable by two people. As covered in Configuration & secrets, a database backup cannot be decrypted without this key — losing it loses every encrypted value even if the data survives.

Upgrades

An upgrade is a rebuild-and-migrate:

  1. Pull the new revision and let Coolify (or CI) build fresh api/worker/web images.

  2. Run migrations from the new image before or as part of the rollout:

    docker run --rm --network <net> -e DATABASE_URL=$DATABASE_URL \
  <new-atlas-api-image> packages/db/dist/migrate.js

  3. Deploy the new images. The proxy keeps serving until the new containers are healthy.

  4. Verify GET /v1/health and a full sign-in.

Before you upgrade

  • Take a fresh database backup.

  • Read the release notes for any migration that's expensive or one-way.

  • Because migrations run from the production image, staging first (a copy of the DB) is the safest way to time a large migration.

Health and observability

  • GET /v1/health is your liveness check; wire it into the proxy and your monitoring.

  • Enable OpenTelemetry and/or the Sentry-compatible error reporting (see Configuration & secrets) so you see problems before your users report them.

Next

Connect Atlas to the rest of your systems → Integrations & operations.

Was this page helpful?