Make backup and restore reliable, and keep NFS out of them (0.64.0)
CI / check (push) Successful in 14m50s
CI / build-and-push (push) Successful in 2m20s

A review of the backup path found several ways a backup was not one, and a
restore could destroy data it did not contain.

Data loss:
- Restore with overwrite rmtree'd the whole stack directory, including
  folders the backup had left out (over 2 GiB, deselected, an NFS share
  mounted inside). It now clears only what the backup holds, keeps the
  excluded paths (recorded in the manifest) and never crosses into another
  filesystem.
- The stack was only stopped when named volumes were selected, so data
  folders inside the stack directory were archived while in use. Any
  selected data now stops it.
- Retention matched by prefix: pruning "app" deleted "app-db"'s backups.
  It now matches backup-<id>-(full|config)-<date>.tar.gz exactly.
- A restore under a new name wrote into the original's volumes when they
  had an explicit name, and into its folders outside the stack directory.
  Both are skipped now; a volume owned by another stack or mounted by a
  running container is never overwritten.
- A truncated archive was only noticed after the old stack was gone. The
  whole archive is verified first, and the stack directory is unpacked
  next to the old one and swapped in.

Remote storage:
- Bind folders on a mounted share (fstab/autofs), bind-type volumes
  pointing at one and shares mounted inside the stack folder are detected
  by filesystem type and not selected; a folder du cannot measure in 20s
  is no longer selected by default either.

Reliability:
- After a backup exactly the containers that ran are started again with
  compose start (falling back to the Docker API), instead of up -d, which
  started services stopped on purpose and applied undeployed edits. A
  stack that cannot be stopped is not backed up.
- Backup and restore hold the stack lock; a scheduled backup that finds
  the stack busy retries after 10 minutes. Restore stops the stack while
  replacing its data and brings it back up.
- external: true volumes are backed up; anonymous ones are listed, not
  selected. Restored volumes get their original driver and options.
- A backup with uncaptured data or a stack that did not restart is
  reported as incomplete: in the dialog, and for schedules as a warning
  with a notification and without rotating older backups out.
- Archive writing and restore run off the event loop; downloads delete
  their temp file; helper containers use the long-timeout client; S3
  listing is paginated; a file changing mid-read no longer corrupts the
  archive.

Manifest format 3 records compose_binds/excluded and volume
driver/options/external; format 1/2 backups still restore.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
menzeljandClaude Opus 5 committed 2026-09-18 11:33:54 +02:00
1 parent ee98d0da6d
commit 8f0a01c4f5
12 files changed
+1938 -276

No files matched your search

+29
View File
@@ -590,6 +590,35 @@ it is what your saved destination credentials are encrypted with.
folders back at their host paths and preserves permissions, ownership and
symlinks (PUID/PGID-based images such as the *arr suite need this), with
optional rename and overwrite/conflict detection.
**How backup and restore stay reliable** (0.64.0):
- The stack's running containers are stopped whenever any data is captured —
also when the data is only folders inside the stack directory — and exactly
those are started again (`compose start`, not `up`, so services you stopped
stay stopped and undeployed compose edits are not applied). A stack that
cannot be stopped is not backed up. The stack is locked meanwhile, so a
deploy, update or scheduled backup cannot interleave (a scheduled backup
that finds the stack busy retries after 10 minutes).
- Remote storage is kept out by what it *is*, not only by how it is declared:
NFS/CIFS volumes, bind folders on a mounted share (`/mnt/nas/…` via fstab or
autofs), bind-type volumes pointing at one, and shares mounted inside the
stack folder. Folders too big to measure in 20 s are not selected either.
- Volumes the stack uses without owning them (`external: true`) are backed up
too; anonymous volumes are listed but not selected.
- Restore reads the whole archive first and refuses a damaged one before
touching anything, stops the stack while replacing its data, unpacks the
stack folder next to the old one and then swaps it in. With *Overwrite*,
folders the backup left out (too large, deselected, remote) and other
filesystems mounted inside the stack folder are **kept**, not deleted.
- Restoring under a new name never writes into the original stack: folders
outside the stack directory and volumes not named after the stack are
skipped, and a volume owned by another stack or mounted by a running
container is never overwritten. Missing volumes are recreated with their
original driver and options.
- A backup that could not capture everything, or left the stack down, is
reported as incomplete — in the dialog and for scheduled backups, which
then notify and do not rotate out older backups. Retention only matches
the stack's own files (it used to take `app-db`'s backups for `app`).
- **Notification webhooks**: ntfy, Discord, Slack, Gotify, or generic JSON, each
subscribed to chosen events (image update available, stack start/stop/error,
pull failed). Managed in **Settings → Notifications**; env `NOTIFY_WEBHOOKS`