# Borg Backup Scope for KalliLabcore

Stand: 2026-05-16

This file defines the target state for replacing Backrest with Borg in this homelab.

## Goal

Use Borg as the single backup system for:

- critical file-backed application data
- secrets, keys, and reverse-proxy state
- database dumps generated before each Borg backup

Do not back up raw live database storage directories as the primary recovery artifact.

## Strategy

1. A pre-backup dump script runs on the host and writes fresh dumps to `/mnt/user/backups/borg/dumps/latest`.
2. Borg backs up `/local/borg-dumps` plus the critical mounted paths below.
3. Borg retention handles history; the dump directory itself keeps only the latest artifacts.

The inclusion of `/local/secrets` is intentional: Borg is expected to cover disaster recovery for selected secret material as part of the current homelab restore strategy.

## Service Inventory

| Service | Recovery Method | What Borg Should Capture |
| --- | --- | --- |
| Vaultwarden | SQLite dump + file data | `/local/borg-dumps`, `/local/appdata/vaultwarden` |
| Paperless | DB dump + file data | `/local/borg-dumps`, `/local/appdata/paperless-ngx/data`, `/local/paperless/media`, `/local/paperless/export`, `/local/paperless/consume` |
| Immich | DB dump + file data | `/local/borg-dumps`, `/local/immich/upload`, `/local/immich/external` |
| Gitea | SQLite dump + file data | `/local/borg-dumps`, `/local/gitea/data` |
| Mealie | DB dump + file data | `/local/borg-dumps`, `/local/appdata/mealie/data` |
| Mail-archiver | shared Postgres dump + data protection keys | `/local/borg-dumps`, `/local/appdata/mailarchiver/data-protection-keys` |
| Authelia | shared Postgres dump + config + secrets | `/local/borg-dumps`, `/local/appdata/authelia/config`, `/local/secrets` |
| Traefik | file data | `/local/appdata/traefik` |
| ntfy | file data | `/local/appdata/ntfy` |
| Paperless-GPT | file data | `/local/appdata/paperless-gpt` |
| Tailscale | file data | `/local/appdata/tailscale` |
| AdGuard | config only | `/local/appdata/adguard/conf` |
| Borg UI | SQLite dump + self-backup | `/local/borg-dumps`, `/local/appdata/borg-ui/data` |
| Komodo | config + Mongo dump | `/local/borg-dumps`, `/local/appdata/komodo/periphery`, `/local/appdata/komodo/core` |
| GitOps host automation | repo clone + Komodo workspaces + host-check state | `/local/services/homelab-infra`, `/local/services/stacks`, `/local/services/posture-check` |
| Nextcloud | DB dump + file data | `/local/borg-dumps`, `/local/appdata/nextcloud/html`, `/local/nextcloud/data` |
| Grafana | SQLite dump + file data | `/local/borg-dumps`, `/local/appdata/grafana` |
| Filebrowser | file-backed state dump + file data | `/local/borg-dumps`, `/local/appdata/filebrowser` |
| InfluxDB 3 Core | file data | `/local/appdata/influxdb3/data`, `/local/appdata/influxdb3/plugins` |
| Hermes Agent | file data + SSH key | `/local/appdata/hermes-agent/data`, `/local/secrets/hermes_runner_id_ed25519` |
| BentoPDF | rebuildable | no critical persistence in compose |

## Open Decisions and Coverage Gaps

These are deviations from the standard "DB dump first, file path second" strategy. Decide deliberately, do not silently extend.

### Nextcloud

Option A umgesetzt: `pre-backup-dumps.sh` writes `nextcloud.dump` from `nextcloud-postgres`. Borg UI also mounts `/mnt/user/documents/nextcloud-data` read-only as `/local/nextcloud/data`, so database and user files are both inside scope after the Borg UI stack is recreated.

### Komodo Mongo dump

`komodo-mongo.archive.gz` was produced and verified on 2026-05-04 (`gzip -t` ok). The dump function is in place in `pre-backup-dumps.sh`. Re-verify after any Komodo or Mongo major upgrade.

### GitOps host automation

The live Unraid User Scripts execute repo scripts from `/mnt/user/services/homelab-infra`, while Komodo keeps stack workspaces below `/mnt/user/services/stacks`. These paths are now mounted into Borg UI as `/local/services/...` and included explicitly so host-side script hotfixes, stack workspace state, and posture-check state are recoverable.

## Database Dumps Required

### Shared PostgreSQL (`postgresql17`)

- `mailarchiver`
- `paperless`
- `authelia`

### Dedicated PostgreSQL

- `mealie`
- `immich`
- `nextcloud`

### Other Databases

- Komodo MongoDB
- SQLite: `gitea`, `vaultwarden`, `uptime-kuma`, `speedtest-tracker`, `borg-ui`, `grafana`
- File-backed state: `filebrowser.bolt.dump`

## Explicitly Not Backed Up as Raw Live DB Files

- `/mnt/user/appdata/postgresql17`
- `/mnt/user/appdata/mealie/postgres`
- `/mnt/user/appdata/immich_postgres`
- `/mnt/user/appdata/nextcloud/postgres`
- `/mnt/user/appdata/komodo/mongo`
- `/mnt/user/appdata/redis`
- `/mnt/user/appdata/scrutiny/influxdb`

## Low-Priority / Rebuildable

These are not part of the first-class Borg scope:

- Plex metadata and cache
- AdGuard query log
- code-server extensions cache
- uptime-kuma
- scrutiny metrics history
- dozzle, glances, speedtest

## Suggested Retention

- daily: 7
- weekly: 4
- monthly: 6

## Repository Recommendation

Recommended primary Borg repository: `critical-infra`

Primary sources are listed in `all-important-sources.txt`.