What to back up

PostgreSQL holds your workspaces, sources, revisions, views, jobs, identities and audit records. The /data volume holds the keys Kumo.io creates for itself on first boot — keep it with the database, because a database restored without them is not the same installation.

Automatic backups

An all-in-one container (serve appliance) backs itself up every 24 hours and keeps the 7 newest scheduled backups. Each backup is a folder under /data/backups/ with a manifest that records a SHA-256 digest for every part:

Things worth knowing:

• The schedule counts from the last successful backup, so a restart never triggers an extra one, and an installation that was off past its interval backs up soon after it starts.
• Only scheduled backups are pruned. Manual, pre-upgrade and pre-restore backups are never deleted automatically.
• A failed scheduled backup is recorded and retried no sooner than every 15 minutes.

Change the schedule with two settings:

An invalid value stops Kumo.io at startup with a message naming the variable.

Ship backups off the machine

A backup on the same disk as the data protects you from mistakes, not from losing the machine. Point Kumo.io at a separate S3-compatible bucket:

Credentials come from the standard AWS SDK chain — environment variables, an instance or task role, or a shared profile.

Each backup uploads its parts first and its manifest last, so an interrupted upload is visibly incomplete. If an upload fails, the local backup still succeeds and its record says the upload failed. Kumo.io never deletes anything from the bucket — set a lifecycle rule on the bucket for off-box retention.

Use a bucket of its own. Backing the installation up into the same storage it already uses protects nothing.

Take a database backup yourself

kumo db backup writes a pg_dump (custom format) of Kumo.io's database to a file. On the single container:

docker exec kumo kumo db backup /data/kumo-manual.dump
docker cp kumo:/data/kumo-manual.dump ./kumo-manual.dump

On Docker Compose, take one before every upgrade — kumo deployment apply does not snapshot the volumes for you. With your own PostgreSQL, your usual backup tooling works as well.

Back up the whole volume

To capture everything on the single container — database, keys and backups — stop it and copy the volume:

docker stop -t 30 kumo
docker run --rm -v kumo:/data -v "$PWD":/backup alpine \
  tar czf /backup/kumo-data.tgz -C /data .
docker start kumo

Restore a database backup

kumo db restore replaces the database's contents with a dump taken by kumo db backup. It is destructive, so it refuses to run without --yes.

On the single container, stop Kumo.io, then restore with the volume attached so nothing else is writing to the database:

docker stop -t 30 kumo
docker run --rm -v kumo:/data -v "$PWD":/backup \
  kumoio/kumo:<version> db restore /backup/kumo-manual.dump --yes
docker start kumo

When Kumo.io starts again it brings the restored database's schema up to date.

Restore refuses a database whose host doesn't look local — localhost, or a Compose service named pg, postgres, db or database — unless you also pass --force-remote. It is a guard against restoring over the wrong server.

Restore an automatic backup

The installation's System · Backups page, at /admin/system/backups (for example http://localhost:9500/admin/system/backups), lists every backup with its reason, status and off-box copy. Log in as the owner first — see First run and recovery. From the page you can:

• choose Back up now to take a manual backup, and
• open Restore… on a backup that succeeded, type RESTORE, and choose Stage restore.

An automatic backup is restored in two stages, because Kumo.io can't safely replace a database it is using:

1. The owner stages the restore. Kumo.io checks the backup first — its manifest, its version, and every part's digest against the bytes on disk — and refuses with the exact problems if anything is wrong. Staging requires typing the confirmation RESTORE. The page then shows A restore is staged.
2. The restore stays queued until you restart the container. On the next start, before anything else runs, Kumo.io checks the archive again, takes a fresh pre-restore backup of the current state (the restore goes no further without one), puts back the keys and owner files, restores the database and stored files, and records whether the restore succeeded.

A restore that fails keeps a pointer to its pre-restore backup, so you can always go back. A failed restore never stops the installation from starting. If the container stops in the middle of a restore, the next start marks that restore failed — naming its pre-restore backup when one was taken — rather than leaving it running.

Recover onto a new machine

If the original machine is gone and your backups are in a bucket, copy the backup folder to the new machine. Its database.dump file is a pg_dump you can restore with kumo db restore; the installation identity and owner files in config.json are put back only by a staged restore. Restoring directly from the bucket is not available.

For a complete move to a new machine today, restore a copy of the whole /data volume.

Rolling back an upgrade

Database migrations only move forward, so the way back from an upgrade is a restore: restore the backup you took before upgrading, then start the previous version. Anything written after that backup is lost. See Upgrades and Migrations.