Implement Linastorage project backups

2026-05-14 12:45:43 -07:00
parent ccc750d789
commit 3fd347d1f6
5 changed files with 347 additions and 8 deletions
@@ -0,0 +1,99 @@
+# Agrarian Project Backup Runbook
+
+Agrarian project backups run from the Codex/dev host and write encrypted,
+deduplicated restic snapshots to Linastorage.
+
+## Paths
+
+- Source: `/mnt/projects/AgrarianGameBulid`
+- NAS mount: `/mnt/backups/linastorage`
+- Backup root: `/mnt/backups/linastorage/backups/agrarian-game/project`
+- Restic repository: `/mnt/backups/linastorage/backups/agrarian-game/project/restic-repository`
+- State files: `/mnt/backups/linastorage/backups/agrarian-game/project/state`
+- Password file: `/root/.backup-secrets/agrarian-project-restic.password`
+- Script: `/usr/local/sbin/agrarian-project-backup`
+- Service: `agrarian-project-backup.service`
+- Timer: `agrarian-project-backup.timer`
+
+## Schedule
+
+The timer runs every two hours with a small randomized delay. The script exits
+without creating a snapshot when there are no changes compared to the latest
+snapshot.
+
+The first implementation attempt used `rsync --link-dest`, but Linastorage over
+SMB did not support the hard-link operations required for that model. The active
+job uses restic instead. Restic stores encrypted, deduplicated chunks as normal
+files, which is a better fit for this SMB target.
+
+Manual snapshots can be created before risky work:
+
+```bash
+sudo /usr/local/sbin/agrarian-project-backup --manual
+```
+
+Force a scheduled-style snapshot even if no changes are detected:
+
+```bash
+sudo /usr/local/sbin/agrarian-project-backup --force
+```
+
+Check whether a snapshot would be created:
+
+```bash
+sudo /usr/local/sbin/agrarian-project-backup --dry-run
+```
+
+## Included
+
+- Unreal project files.
+- Git metadata, including unpushed local history when practical.
+- Local source data under `Data/`, including raw terrain source inputs excluded
+  from GitHub.
+- Scripts, docs, configs, plugins, content, and project metadata.
+
+## Excluded
+
+- `DerivedDataCache/`
+- `Intermediate/`
+- `Saved/`
+- `Binaries/`
+- `Builds/`
+- transient Git LFS temp files
+- local Visual Studio temp files
+
+## Retention
+
+The script uses restic retention:
+
+- All snapshots within 7 days.
+- Daily snapshots for 30 days.
+- Weekly snapshots for 12 weeks.
+- Monthly snapshots for 12 months.
+
+The script records a source signature and skips scheduled runs when no project
+changes are detected.
+
+## Restore Test
+
+Restore one file to a temporary path:
+
+```bash
+mkdir -p /tmp/agrarian-project-restore-test
+sudo sh -c 'RESTIC_PASSWORD_FILE=/root/.backup-secrets/agrarian-project-restic.password \
+  restic -r /mnt/backups/linastorage/backups/agrarian-game/project/restic-repository \
+  dump latest /mnt/projects/AgrarianGameBulid/AGRARIAN_DEVELOPMENT_ROADMAP.md \
+  > /tmp/agrarian-project-restore-test/AGRARIAN_DEVELOPMENT_ROADMAP.md'
+diff -q /mnt/projects/AgrarianGameBulid/AGRARIAN_DEVELOPMENT_ROADMAP.md \
+  /tmp/agrarian-project-restore-test/AGRARIAN_DEVELOPMENT_ROADMAP.md
+```
+
+List snapshots:
+
+```bash
+sudo RESTIC_PASSWORD_FILE=/root/.backup-secrets/agrarian-project-restic.password \
+  restic -r /mnt/backups/linastorage/backups/agrarian-game/project/restic-repository \
+  snapshots --tag agrarian-game --tag project
+```
+
+Record restore tests in the handoff log with the snapshot name and result.