Volumes

A volume is data the containers mount rather than a container Kamal runs: a Docker volume, or a directory on the host. It has no lifecycle of its own – nothing to boot, nothing to restart. What it has is backups.

This is how a cache directory, an uploads folder, or anything else with no dump command ends up somewhere that outlives the machine.

Adding one

Environment → Volumes → Add. Give it:

• A name, which is how you refer to it here
• A source: either a Docker volume name, or an absolute path for a bind mount
• The server it lives on – a volume is on one machine, and that is the machine that holds the data
• Optionally the container path it is mounted at, for the record

A source with a slash is a bind mount, already on the filesystem. A bare name is Docker’s own space under /var/lib/docker/volumes.

Backing one up

Archiving is a tar run in a pinned small image with the volume mounted. Whatever your app is written in has nothing to do with archiving its data, so the same image does every volume.

Set a schedule, retention in days, and which buckets to send to. A backup can also be taken on demand, restored, and downloaded.

Stopping containers

Some data cannot be archived while it is being written. A database that writes continuously does not restore from a live tar. Tick stop containers and the containers using the volume stand down for the archive and come back afterwards – a short outage, in exchange for a backup that actually restores.

Volumes and the machine

A volume names the machine holding it, so deleting that machine takes the volume record and its schedule with it. The backups already in buckets stay exactly where they are.

Deleting an environment removes its named Docker volumes along with the containers. Bind mounts are left alone: a directory somebody chose is often shared with things KamalCloud never deployed, so rm -rf on one is not KamalCloud’s to run.

As everywhere else, the first attempt to delete something holding data takes a farewell backup and refuses; the second goes through.

Restoring

A restore unpacks an archive back over the volume. Where the volume is one that stands its containers down for backups, the restore does the same. Check what you are restoring onto first – a restore is not reversible.