Snapshots and backups

A snapshot is a copy of an application’s storage, kept on the device that runs it. Take one before a risky change; if the change damages the data, restore it.

What a snapshot protects against, and what it does not:

Protects against	Does not protect against
An update that corrupts or migrates the data badly	The device’s disk failing
A file or table deleted by mistake	The device being lost, stolen or wiped
A bad configuration change	A mistake you notice after the 5 newest snapshots rotated past it

For the second column you need a copy somewhere else — see Copy a snapshot off the device.

What can be snapshotted

Snapshots cover the application’s persistent storage: the spec.storage[] entries with type: persistent (see Application YAML).

Application	Supported	Notes
Docker Compose, Docker, managed process	Yes	The app is stopped for the copy, then started again.
Virtual machine	Yes	The VM is shut down and its whole disk is copied. That takes a while and needs free space on the device about the size of the disk.
Pre-existing service	No	Edgible does not start or stop the service and does not know where it keeps its data. The answer is 400 SNAPSHOT_NOT_SUPPORTED; back it up with the service’s own tools, or by hand.
No spec.storage	No	Nothing to copy: 400 SNAPSHOT_NO_STORAGE.

Snapshots also need:

• the application to run on one serving device (the snapshots live on that device);
• that device to be online and to run agent 1.4.14 or newer.

Take a snapshot

edgible application storage snapshot web

The application stops while its storage is copied, then starts again — expect a short outage. All of its persistent storage is copied under one snapshot id, so several volumes (for example a database and its uploads folder) stay consistent with each other. To copy one volume only:

edgible application storage snapshot web --storage data

The snapshot id is the time it was taken, in UTC: 20261014T093015Z is 14 October 2026, 09:30:15.

The device keeps the newest 5 snapshots per storage volume; taking a sixth deletes the oldest.

List snapshots

edgible application storage snapshots web
edgible -o json application storage snapshots web

The list shows each snapshot’s id, volume, size and the time it was taken, newest first.

Restore a snapshot

Restoring replaces the live data with the snapshot. Anything written since the snapshot was taken is lost, so the command asks first:

edgible application storage restore web --snapshot 20261014T093015Z

Add --yes to skip the question (scripts, CI), and --storage <name> to restore one volume only.

What happens, in order:

1. The snapshot is unpacked next to the live data and its checksum is verified — while the application keeps running. A damaged snapshot stops here; the live data is not touched.
2. The application is stopped.
3. The unpacked copy is swapped in for the live data in one step.
4. The application is started again.

Delete a snapshot

edgible application storage delete-snapshot web --snapshot 20261014T093015Z

Deleting the application deletes its snapshots too (they are kept for 24 hours in the device’s storage trash, like the application’s data).

Template upgrades take a snapshot first

When a catalog template lists backup volumes (its spec.backup.volumes) and asks for a snapshot before upgrading (snapshotBeforeUpgrade, on by default), edgible template upgrade snapshots those volumes right before it applies the new version:

edgible template upgrade nextcloud
# … Snapshot 20261014T093015Z taken of data.

• If the snapshot fails, the upgrade stops and nothing is changed.
• --no-snapshot upgrades without one.
• In the web app, the upgrade dialog has a Snapshot the data first checkbox, ticked by default.

If the new version turns out to damage the data, undo both halves: roll the release back with edgible application rollback, then restore the snapshot with edgible application storage restore.

Copy a snapshot off the device

Snapshots are plain files on the device:

/var/lib/edgible/backups/<application-id>/<storage-name>/<snapshot-id>.tar
/var/lib/edgible/backups/<application-id>/<storage-name>/<snapshot-id>.sha256

Copy both files somewhere safe and check them:

scp root@edge-01:/var/lib/edgible/backups/app-1a2b/data/20261014T093015Z.* ./backups/
cd backups && sha256sum -c 20261014T093015Z.sha256

To put an off-device copy back, push the tar file into the volume — the application is stopped across the swap:

edgible application storage push --app web --storage-name data \
  --path ./backups/20261014T093015Z.tar --no-pack --quiesce --apply-mode replace

Back up anything else by hand

For a pre-existing service, or data outside Edgible’s storage, stop the service and archive its data directory yourself:

sudo systemctl stop myservice
sudo tar --create --sparse --numeric-owner --xattrs --acls \
  --file=/root/myservice-$(date -u +%Y%m%dT%H%M%SZ).tar --directory=/srv/myservice .
sudo systemctl start myservice

Restore by stopping the service, emptying the directory, and extracting the archive with tar --extract --file=<archive> --directory=/srv/myservice.

From code

The SDK runs the same jobs and waits for them:

const applicationId = 'app-1a2b';
const taken = await client.storage.snapshots.create({ applicationId });
const { snapshots } = await client.storage.snapshots.list({ applicationId });
const snapshotId = snapshots[0]?.snapshotId ?? taken.snapshots[0]?.snapshotId;
if (snapshotId) await client.storage.snapshots.restore({ applicationId, snapshotId });

A job that fails on the device throws StorageSnapshotJobError (code: 'SNAPSHOT_JOB_FAILED') carrying the device’s message.

Scheduled backups

spec.storage[].backup (scheduled, retained backups) is still rejected at apply with 400 BACKUPS_NOT_SUPPORTED. Take snapshots on demand, or schedule edgible application storage snapshot from cron on a machine that is logged in to Edgible.