homelab-infra/ops/borg-ui/scripts/USER_SCRIPTS_SETUP.md

Unraid User Scripts Setup

This document describes the intended automation path for the Borg pre-flight scripts.

Decision

The Borg pre-flight should run:

• on the Unraid host
• through the User Scripts plugin or host cron
• before the Borg UI repository job starts

It should not be implemented as a Borg UI inline hook in the current design.

Why host-side

pre-borg.sh currently chains the host-side checks:

• services/posture-check/posture-check.sh
• ops/borg-ui/scripts/pre-backup-dumps.sh including the Unraid flash config archive
• ops/restore-tests/check-restore-freshness.sh

The dump step assumes:

• access to the host Docker daemon via docker exec
• access to host paths under /mnt/user/...
• the ability to write fresh dump artifacts into the shared dump directory

That makes host execution simpler, more transparent, and lower-risk than giving Borg UI additional host-level responsibilities.

Recommended rollout

1. Use the repo clone on the host:
   • /mnt/user/services/homelab-infra
2. Make the scripts executable:
   • chmod +x /mnt/user/services/homelab-infra/ops/borg-ui/scripts/pre-borg.sh
   • chmod +x /mnt/user/services/homelab-infra/ops/borg-ui/scripts/pre-backup-dumps.sh
3. Create a User Scripts entry:
   • borg-pre-backup-dumps
4. Script body:

#!/bin/bash
REPO_ROOT=/mnt/user/services/homelab-infra \
DUMP_ROOT=/mnt/user/backups/borg/dumps \
ALLOW_POSTURE_WARNING=1 \
bash /mnt/user/services/homelab-infra/ops/borg-ui/scripts/pre-borg.sh

5. Schedule: daily at 04:00, before the expected Borg backup window.
6. Keep Borg UI focused on backing up /local/borg-dumps, not on generating the dumps itself.

Operational model

The intended sequence is:

1. Host wrapper checks posture.
2. Host script refreshes latest dump artifacts.
3. Host script writes unraid-flash-config.tar.gz plus checksum and manifest into the same dump set.
4. Freshness check verifies expected dumps and the flash config archive.
5. Borg UI backs up /local/borg-dumps together with the rest of critical_infra.
6. Borg history preserves dump history, so the host only needs to keep the most recent dump set.

Current dump target

• /mnt/user/backups/borg/dumps/latest

This target is intentionally separate from live app state so that dump artifacts live under the backup share instead of appdata.