Backup and maintenance

What must be backed up

Data	Location	How
PostgreSQL and TimescaleDB	`${DATA_DIR}/postgresql`, `${DATA_DIR}/timescaledb`	`deploy/scripts/backup.sh` (`pg_dump` custom format).
The `.env` file	`deploy/.env`	Copy it somewhere safe. Do not commit it.
`SECRETS_KEY`	in `.env`	A separate copy off the server (a password manager). Without this key, stored credentials cannot be read even if the database is restored.
Firmware files	`${DATA_DIR}/firmware`	Copy the folder.
Your own CA certificate	`${DATA_DIR}/tls-ca/`	Back up `ca.key`.

A per-workspace configuration backup by users (Backup and restore) complements, but does not replace, a server backup.

Daily backup

# cron (02:15 every day)
15 2 * * * /opt/celestian/deploy/scripts/backup.sh >> /var/log/celestian-backup.log 2>&1

The script writes postgresql.dump and timescaledb.dump to ${BACKUP_DIR}/<date-time>/ and deletes backups older than BACKUP_KEEP_DAYS (7 days by default).

Restoring

# PostgreSQL
docker compose exec -T postgresql pg_restore -U postgres -d celestian --clean --if-exists < postgresql.dump

# TimescaleDB: must be wrapped in pre/post restore
docker compose exec -T timescaledb psql -U postgres -d celestian -c "SELECT timescaledb_pre_restore();"
docker compose exec -T timescaledb pg_restore -U postgres -d celestian --clean --if-exists < timescaledb.dump
docker compose exec -T timescaledb psql -U postgres -d celestian -c "SELECT timescaledb_post_restore();"

The “circular foreign-key” warning when dumping TimescaleDB is normal. Practice the restore procedure in a test environment before you need it.

Automatic maintenance

The server runs several background tasks by itself:

Task	Description
Database migrations	Automatic when `api` starts (with an advisory lock, safe for several instances).
Message retention	Compression after 7 days and deletion after 365 days (the TimescaleDB hypertable).
Journal retention	180 days by default, cleaned up hourly.
Rule executions	The 7-day trace is cleaned up hourly.
Report results	Kept according to `REPORTS_RETENTION`.
Workspace deletion	A frozen workspace is deleted permanently after the grace period; its messages are cleaned up gradually.

Monitoring

GET /healthz and GET /readyz on the backend (used by the Docker HEALTHCHECK).
docker compose ps and docker compose logs -f api for status and logs.
Each workspace’s Home page shows message activity for 24 hours.
Common log warnings: “cannot connect to the broker yet” at startup (normal), and REPORTS_PDF_URL empty when PDF is not used.

Total reset (test environments only)

docker compose down
# delete the contents of DATA_DIR through a container (the files belong to the container uid), with a literal path:
docker run --rm -v /srv/celestian-data:/d alpine sh -c 'rm -rf /d/postgresql /d/timescaledb /d/redis /d/fluxmq'