Backups and restore
Ottertrail does not make backups automatically. Run the backup script before each update, and on a regular schedule.
Make a backup
Section titled “Make a backup”Run the script in the instance’s folder:
./backup.shThe instance keeps running. The script writes three files into backups/ beside it, named by the time:
| File | Contents |
|---|---|
ottertrail-<time>.zip |
ClickHouse: events, errors, traces, logs, and metrics |
ottertrail-<time>.dump |
PostgreSQL: accounts, projects, and settings |
ottertrail-<time>-objects.tar |
The object store: source maps and session replays. Without an object store, the file holds only a manifest that says so. |
- Only the user who ran the script can read the files.
- If a step fails, the script names the step. It keeps no file that looks like a complete backup.
- An object that was deleted during the backup, such as an expired replay, is left out. The script tells you how many.
Disk space
Section titled “Disk space”- ClickHouse writes its backup into its own volume first. The disk needs free space of about two times ClickHouse’s data.
- The objects need about two times their size too: one time as files, one time in the tar file.
Before it starts, the script prints the free space and what the backup needs. If there is not enough, it warns and goes on. A run that fails keeps no file. The Storage tab of the instance settings warns with “The next backup would fail” when the disk is short of this space. See Storage and warnings.
Keep backups safe
Section titled “Keep backups safe”- Copy all three files off the server. A backup on the same disk is lost with the disk.
- Delete old backups yourself. They hold your users’ data, including events that you deleted after the backup.
Restore a backup
Section titled “Restore a backup”Restore into empty databases that have not been migrated: on a new server before its first docker compose up -d, or after docker compose down -v. Do not run docker compose up -d first, as Install and First start do: it runs the migrations, and the restore then refuses. Put the three files in backups/, then give the name without the extension:
./restore.sh backups/ottertrail-2026-11-17T062707ZThe script works in this order:
- It checks the object backup before it changes anything. A damaged tar file, a missing object store, or a store that does not answer stops the restore here. The databases stay as they were.
- It starts PostgreSQL and ClickHouse only, and restores both.
- It puts the objects back in the object store, before the worker starts.
- It starts the rest of the stack.
- The databases must be empty and not yet migrated: ClickHouse refuses to restore into a table that holds data, and the migrations record themselves in one. If the restore fails after step 1, the script says that the databases changed. Run
docker compose down -v, then start again. - The bucket does not need to be empty. An object with the same name is replaced. Other objects stay.
Restore without the objects
Section titled “Restore without the objects”If the -objects.tar file is missing, the script refuses to run. To restore the databases without the source maps and session replays, add --without-objects:
./restore.sh --without-objects backups/ottertrail-2026-11-17T062707ZAfter this restore, replays do not play. Upload the source maps of the releases in use again.
Disk space for a restore
Section titled “Disk space for a restore”The three files, plus the unpacked objects, about as large as their tar file, until the restore ends.
Options
Section titled “Options”-
Both scripts run in their own folder, next to
compose.yamland.env, from wherever you call them. -
Both scripts run
docker compose. To use another command, setCOMPOSE:Terminal window COMPOSE="podman compose" ./backup.sh -
restore.shstarts Garage whenCOMPOSE_PROFILESin.envincludesobject-store. Without that profile it does not start Garage, and its check stops after a minute.backup.shdoes not start Garage: it must already be running. -
The scripts run their helper containers as your user, so that you own the files. Rootless Docker, rootless Podman on Linux, and SELinux hosts are not tested.