# 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`
- `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:

```bash
#!/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. Freshness check verifies expected dumps.
4. Borg UI backs up `/local/borg-dumps` together with the rest of `critical_infra`.
5. 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`.