Backups & restore

A self-hosted instance keeps its state in three stores and one file: Postgres for application data, ClickHouse for the observability records (spans and traces), object storage for uploads, exports and media, and .env for the secrets. Back up all four. Redis holds caches, locks and live updates, so there is nothing in it to back up.

Where object storage lives depends on the setup. In Standalone it runs inside the app container and keeps its files in the app-data volume; in Distributed it is the minio container. On Kubernetes, see Back up and restore for the Helm chart.

If you’ve already moved to managed data stores, your provider’s backup tooling replaces the steps below for those stores.

With the production overlay, add its --env-file and -f flags to every docker compose command on this page, as in Start Distributed with the production overlay. A plain docker compose stop there stops only the services of the Standalone file.

The named volumes

The Compose project name is futureagi unless COMPOSE_PROJECT_NAME in .env says otherwise, and every volume is prefixed with it. docker volume ls | grep futureagi lists them.

An upgraded install made before Standalone became the default may also still have futureagi_rabbitmq-data and, if it once ran the Kafka catalog sequencer, futureagi_property-catalog-sequencer-data. Nothing mounts them any more: see Upgrading older installs for when to delete them.

Postgres

Postgres holds the application data, so back it up on a schedule. Use the custom format, and pass -T so docker compose exec doesn’t allocate a TTY and mangle the binary dump. The commands assume the default PG_USER and PG_DB, both futureagi.

docker compose exec -T postgres \
  pg_dump -U futureagi -d futureagi --format=custom \
  > backup-$(date +%F).dump

On Distributed, Temporal keeps its workflow state in the same futureagi database, so the dump carries it, and a restore rewinds it with the rest. Restore has the restore steps.

ClickHouse

ClickHouse holds data that exists nowhere else. The collector writes spans straight into it, so they are not recoverable from Postgres. Back it up on its own schedule with ClickHouse’s BACKUP command to S3, rather than copying files. Include property_catalog (PROPERTY_CATALOG_DATABASE), the separate database the attribute suggestions in trace filters are read from, next to default. ClickHouse refuses to write a backup to a path that already holds one, so give each run its own path:

docker compose exec -T clickhouse clickhouse-client --query \
  "BACKUP DATABASE default, DATABASE property_catalog TO S3('https://your-bucket.s3.amazonaws.com/ch-backup/$(date +%F)/', 'YOUR_ACCESS_KEY', 'YOUR_SECRET_KEY')"

If BACKUP reports that property_catalog does not exist, as on some installs made before Standalone became the default, leave it out of the command.

clickhouse-client inside the container signs in with the CH_PASSWORD that Compose hands the container, so the commands work whether or not your install has a ClickHouse password. The options of BACKUP and RESTORE are in ClickHouse’s Backup and Restore docs.

Object storage

docker compose stop app
docker run --rm -v futureagi_app-data:/data -v "$PWD":/backup alpine \
  tar czf /backup/app-data-$(date +%F).tgz -C /data .
docker compose up -d

mc alias set local http://localhost:9005 futureagi <MINIO_ROOT_PASSWORD>
mc alias set s3 https://s3.amazonaws.com <AWS_ACCESS_KEY> <AWS_SECRET_KEY>

mc mirror local/ s3/your-bucket/     # back up

Secrets

Back up .env (with the production overlay, deploy/.env.production and the root .env) with the data, and store the copy as carefully as the data: it holds the generated secrets. A restored database needs the same INTEGRATION_ENCRYPTION_KEY: integration credentials saved with one key cannot be read with another, and those integrations must be connected again. ./bin/uninstall --wipe-data deletes the volumes but keeps .env, so a reinstall reuses its secrets.

Restore

Restore Postgres, then ClickHouse from a backup taken at or after the same point, then object storage, with nothing else running. Restore the secrets file first if you lost it: the data needs the credentials it was created with.

docker compose stop                          # every service
docker compose up -d postgres clickhouse     # only the data stores; Distributed: add minio

docker compose exec -T postgres \
  pg_restore -U futureagi -d futureagi --clean --if-exists \
  < backup-2026-04-22.dump

docker compose rm -sf clickhouse
docker volume rm futureagi_clickhouse-data
docker compose up -d clickhouse

docker compose exec -T clickhouse clickhouse-client --query \
  "RESTORE DATABASE default, DATABASE property_catalog FROM S3('https://your-bucket.s3.amazonaws.com/ch-backup/2026-04-22/', 'YOUR_ACCESS_KEY', 'YOUR_SECRET_KEY')"

docker run --rm -v futureagi_app-data:/data -v "$PWD":/backup alpine \
  sh -c 'find /data -mindepth 1 -delete && tar xzf /backup/app-data-2026-04-22.tgz -C /data'

mc mirror s3/your-bucket/ local/

docker compose up -d

Dive deeper