Skip to main content

Data and backups

All of your instance's state is in one place, which makes both backup and recovery a file operation. The routine backup commands are in Operating; this page is the recovery side and the one mistake that can't be undone.

Where the data is​

Everything lives under ./data/ next to your compose file, one folder per service:

  • data/db is the databases (the platform database plus one per workspace).
  • data/files is uploads and images.
  • data/caddy is issued certificates.
  • data/modules is installed module code.

No named volumes, so a plain copy of ./data/ is a full backup, and moving to a new disk is one rsync.

Restoring the whole instance​

From a folder copy, restore is the reverse of backup: bring the stack down, put the tree back, bring it up.

docker compose down
rm -rf data                 # or move it aside
cp -a /path/to/backup/data ./data
docker compose up -d

Restore the .env and docker-compose.yml from the same backup too, so the config matches the data. In particular the .env you restore must carry the same TENANT_CREDS_ENCRYPTION_KEY the data was encrypted with (see below).

Restoring from a database dump​

If your backup is a SQL dump (from the pg_dumpall command in Operating) rather than a folder copy, load it back into a running db:

gunzip -c cobblr-backup-2026-07-01.sql.gz | docker compose exec -T db psql -U cobblr

A dump restores the databases but not uploaded files or certificates; the folder copy is the complete one.

The encryption key​

TENANT_CREDS_ENCRYPTION_KEY encrypts the per-workspace credentials Cobblr stores (the keys and tokens you enter for integrations and connected services). It is derived into an AES-256 key and used to encrypt those values at rest.

Losing it is unrecoverable. If you change the key, or restore a database without the matching key, every stored credential becomes undecryptable ciphertext. The data isn't corrupted and the rest of the instance runs, but each affected integration has to be reconnected with its secret re-entered.

  • Keep a copy of the key somewhere off this box: a password manager, or an encrypted note. Store it wherever you keep the recovery material for anything else you couldn't rebuild.
  • When you restore, restore the .env that goes with the data, so the key comes along.

The reasoning and the operator-side discipline for this key are in Secrets and keys.

A backup didn't run​

Cobblr does not run backups for you by default. The commands in Operating are what you schedule (a cron entry, a systemd timer, whatever your box uses). If you expected backups and there are none, check that the schedule exists and that its output path is writable.

For restorable snapshots of a single workspace, and off-box destinations like Google Drive, use the in-app tools in Backup and export. Those are separate from the whole-instance folder copy: one is a workspace's own data on demand, the other is everything on the box.