Document Backrest restore and fix the Paths field autocomplete claim

2026-09-09 14:23:25 +02:00
parent 12242579a0
commit 0f9b039e11
2 changed files with 18 additions and 4 deletions
@@ -87,7 +87,7 @@ services:

 The `/srv/docker`, `/etc` and `/home` lines above cover what's actually worth an off-site backup on a homelab server, per [folders and partitions](/general/linux/filesystem): `/srv/docker` holds every stack's config and data (databases, uploaded files, Vaultwarden's vault, Pocket ID's users, and so on), `/etc` holds your system configuration (the SSH hardening from the [installation guide](/serveex/core/installation#close-the-door-behind-you), your SWAG `.subdomain.conf` files, systemd units), and `/home` holds your own scripts and notes. All three are mounted read-only, a backup tool has no business writing to what it's backing up.

-What's usually **not** worth it: a big media library or a torrent download folder sitting on a separate data disk. It's often huge, replaceable, and rarely worth paying for cloud storage or SSH bandwidth to protect. Mount it too if you disagree, `/media:/userdata/media:ro` for instance, just think about the size first.
+What's usually **not** worth it: a big media library or a torrent download folder sitting on a separate data disk. It's often huge, replaceable, and rarely worth paying for cloud storage or SSH bandwidth to protect.

 ::tip{icon=""}
 ✨ __Tip:__ Add the Watchtower label to automate updates
@@ -231,7 +231,7 @@ Back in Backrest, go to **Add Plan**. This form covers what to back up and when,

 - **Plan Name**: same rule as the repo name, pick something clear, you can't change it later.
 - **Repository**: the one you just created above.
- **Paths**: click **Add** to add a row, then type in the container-side path for whatever you mounted above, there's no folder browser, just a plain text field. `/userdata/docker` for your stacks, `/userdata/etc` for your system config, `/userdata/home` for your own files. Click **Add** again for each additional folder, the small `-` button removes a row you don't need.
+- **Paths**: click **Add** to add a row, then type in the container-side path for whatever you mounted above, it's a plain text field, but it autocompletes real paths from the container's filesystem as you type, handy to confirm a mount actually landed where you think. `/userdata/docker` for your stacks, `/userdata/etc` for your system config, `/userdata/home` for your own files. Click **Add** again for each additional folder, the small `-` button removes a row you don't need.
 - **Excludes** and **Excludes (Case Insensitive)**: patterns to skip within those paths, handy for cache folders or anything genuinely disposable that would otherwise bloat every snapshot for no reason.
 - **Schedule Type**: same three choices as the repository's own schedules above, `Disabled`, an `Interval`, or a `Cron Expression`. A nightly cron like `0 3 * * *` (every day at 3 AM) is a reasonable default for a homelab.
 - **Retention Policy**: how many snapshots to keep, and for how long. **By Time Period** lets you say "keep 7 daily, 4 weekly, 6 monthly" independently, which gives you plenty of restore points spread over time without the repository growing forever, since restic deduplicates unchanged data between snapshots anyway. **By Count** instead just keeps the last N snapshots regardless of age. **Latest (Count)** on top of either mode guarantees a minimum number of recent snapshots always survive, whatever the rest of the policy says.
@@ -243,4 +243,11 @@ That retention policy is your real defense against ransomware, by the way: if so
 ✨ __Going further:__ if some of what you're backing up includes a live database, stopping its container for the few seconds a backup takes is safer than backing it up while it's being written to. See **Backrest Docker Stop** for a script that does exactly that, triggered automatically by Backrest itself.
 ::

+## Restoring a backup
+A backup you've never tried restoring is a guess, not a plan, so it's worth doing once before you actually need it. Open the plan, click into a snapshot, expand **Snapshot Browser** down to whatever you need, then click the **...** menu next to it and pick **Restore to path**.
+
+Leave the path field empty and Backrest streams it straight to your browser's downloads instead, the simplest option for grabbing a single file. Type a path and Backrest writes the restored data inside the container at that location instead, and it pre-fills a scratch folder like `/userdata-backrest-restore-<snapshot id>`, deliberately not your original mount.
+
+That default isn't an accident: `/srv/docker`, `/etc` and `/home` are mounted `:ro`, so restic can't write back into them, restoring straight into `/userdata/docker` fails with a read-only filesystem error. Restore to that suggested scratch path (or download instead), check what you got, then copy the files into their real place yourself with `sudo cp -a`, from the host, outside of Backrest entirely. It's one extra step, but it also means a restore can never silently clobber live data by accident, exactly the caution you want mid-incident.
+
 And that's it, you now have an actual backup strategy instead of a folder called `backup_final_v2_REAL`.