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

Unraid User Scripts Setup

This document describes the intended automation path for pre-backup-dumps.sh.

Decision

The pre-backup dump refresh 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-backup-dumps.sh currently 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. Store the script on the host, for example at:
   • /mnt/user/appdata/borg-ui/scripts/pre-backup-dumps.sh
2. Make it executable:
   • chmod +x /mnt/user/appdata/borg-ui/scripts/pre-backup-dumps.sh
3. Create a User Scripts entry such as:
   • borg-pre-backup-dumps
4. Let that entry run:
   • on a fixed schedule before the expected Borg backup window
   • or manually before ad hoc Borg runs
5. Keep Borg UI focused on backing up /local/borg-dumps, not on generating the dumps itself.

Operational model

The intended sequence is:

1. Host script refreshes latest dump artifacts.
2. Borg UI backs up /local/borg-dumps together with the rest of critical_infra.
3. 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.