Volumes & snapshots

A Docker volume is where a project keeps data that has to survive a redeploy — a database's files, uploaded images, a cache. kimbap lists the volumes your projects use, and can copy one's contents into a snapshot you can restore later.

This is the other half of Backup & migration, which carries a project's configuration between hosts and deliberately leaves its data behind.

Seeing what you have

System → Volumes lists every volume belonging to a project kimbap manages. Each project also has its own Volumes tab showing just its own.

Sizes aren't shown until you press Calculate sizes — Docker works them out by walking every volume on the host, which takes a few seconds, and most visits don't need the number. The sizes it reports are rounded, so treat them as approximate.

Volumes from containers kimbap doesn't manage aren't listed. kimbap can't stop those containers, so it can't take a reliable copy of their data or safely put one back.

Taking a snapshot

Press Back up on a volume. One choice matters:

Stop the project while the copy runs (ticked by default). A database writes to several files at once. Copying them while it's running can catch it mid-write and produce a set of files that don't agree with each other — a snapshot that looks fine in the list and fails when you restore it. Stopping the containers first avoids that entirely.

The cost is that the project is down for as long as the copy takes. kimbap starts it again automatically afterwards, including when the copy fails.

Unticking it takes a hot snapshot with nothing stopped. That's a reasonable trade for static content — uploaded files, generated assets, a cache — and a bad one for anything with a database in it. Hot snapshots stay labelled as such for as long as they exist, because that's the caveat you need in front of you at the moment you reach for one.

Only one backup or restore runs at a time on a host. A second one is refused until the first finishes rather than queued.

Restoring

Press Restore on a snapshot.

Restoring erases the volume. Its current contents are replaced with the snapshot's, exactly — anything written since the snapshot was taken is gone, and there's no undo. kimbap makes you type the volume's name to confirm.

The project is stopped for the restore and started again afterwards. That isn't optional: writing into a volume while a database is using it doesn't risk corruption, it is corruption.

If the snapshot file turns out to be damaged, kimbap says so and stops before touching the volume — a bad archive costs you nothing.

You can also restore into a volume that no longer exists; kimbap recreates it with the right labels so Compose picks it up on the next deploy.

Where snapshots live, and what that means

Snapshots are stored on the same host, under volume-snapshots/ inside kimbap's state directory.

That makes them a good answer to "the upgrade broke the database" and no answer at all to "the disk died." A copy sitting next to the thing it's a copy of goes when that disk goes. For anything you genuinely can't lose, use Download to pull a snapshot off the host and keep it somewhere else.

System → Volumes shows how much disk snapshots are using and how much is left. kimbap refuses to start a snapshot it thinks won't fit. Nothing expires on its own — old snapshots stay until you delete them.

Moving data to another host

1. Take a snapshot on the old host (with the project stopped).
2. Download it.
3. On the new host, move the project across with Backup & migration, and deploy it once so its volumes exist.
4. On the new host, open the volume and Upload a snapshot.
5. Restore it.

An uploaded snapshot is marked hot, because kimbap has no way to know whether the containers were stopped when it was made.

Under the hood

kimbap reads and writes volume contents through a throwaway busybox container with the volume mounted — the only portable way to reach them, since on Docker Desktop the files live inside a VM and a volume may not be a local filesystem at all. The archive is an ordinary gzipped tar of the volume's contents, so you can open one with tar tzf or restore it by hand if you ever need to without kimbap involved.

The helper image is pulled once, the first time you take a snapshot. On a host that can't reach Docker Hub, set KIMBAP_VOLUME_HELPER_IMAGE to an image you can pull that has tar and find in it.

Backing up and restoring volume contents is admin-only, and every snapshot, restore, download, upload and delete is recorded in the audit log.

If kimbap restarts mid-backup

A snapshot that was running when kimbap stopped is marked interrupted and its half-written file is removed. If its project was stopped for the copy, kimbap starts it again on the next boot — a crash at the wrong moment won't leave a service down.