Backups

Two things can be backed up: accessories that have a dump command, and volumes. Both go to the same place – an S3-compatible bucket you own.

Buckets

Buckets → Add. A bucket is account-level: any environment can use it.

Field
Endpoint	the bucket’s own API URL, e.g. https://fsn1.your-objectstorage.com, https://s3.eu-central-1.amazonaws.com, https://<id>.r2.cloudflarestorage.com
Bucket	the bucket name, by S3’s naming rules
Access key / secret	encrypted at rest; a stored secret is never shown again, so an empty box on edit means keep
Prefix	optional folder inside the bucket

Test connection in the dialog checks a bucket before you save it. After saving, KamalCloud verifies it on its own, and again whenever the endpoint, bucket, prefix or keys are edited: it writes a small marker object and deletes it, since a read-only key could list a bucket just as well. A key issued seconds ago is retried before a refusal is believed.

Where a backup names its buckets, those are used. Where it names none, only verified buckets are.

KamalCloud reaches buckets through a throwaway mc container on a runner, with the credentials passed in the environment rather than on a command line. Any ready runner will do – the bucket is reached over the internet, not from a particular machine.

Scheduling a backup

On the accessory or the volume:

• Schedule — cron, or plain English: every day at 3am, every monday at 7am
• Retention — how many days to keep. Older backups are pruned, and pruning removes the object from the bucket, not just the row
• Buckets — which buckets to send to. Leave it empty and every verified bucket is used, so adding a second bucket anywhere makes the next backup redundant

Several buckets

Sending one backup to two buckets is only redundancy if they can fail separately. Two buckets at one company are one place: one suspension, one region, one unpaid invoice takes both. KamalCloud says so, and says it loudest in the case that matters – every copy of your data held by the same company that holds the machine.

A backup that reached some of its buckets but not all fires backup.incomplete. One that reached none fires backup.failed. A scheduled accessory or volume with no successful backup in the last 36 hours fires backup.overdue; KamalCloud looks every 6 hours. Volume backups raise the same three as accessory backups.

A backup cannot be stopped once it has started. A dump stopped halfway leaves a truncated object that looks like a backup.

Restoring

Restore takes one backup and puts it back. For an accessory that means piping the dump through the image’s own restore command; for a volume it means unpacking the archive over it, standing containers down first if that volume is configured to.

Restores are not reversible, and cannot be stopped either – half a restore is worse than none. Read what you are about to overwrite.

Downloading

A backup is downloaded one copy at a time, because the point of having several is that they are in different places and one of them may be gone. Pick the bucket, get the object.

Farewell backups

Nothing holding data is deleted until its data is somewhere else. The first attempt to delete an app, environment, accessory or volume takes a backup of everything under it and refuses; the attempt after that goes through. The refusal names what it took and what it could not, so a missing bucket is a sentence rather than a silent success.

Only a kept backup counts, and only if it is under an hour old, so the archive is of what is actually being deleted. A scheduled one is destroyed along with its subject.

What is not backed up

Your repository – it is already in git. The servers themselves – rebuild them; that is what provisioning and hardening are for. KamalCloud’s own records of your account.