homelab-infra/ops/borg-ui/BACKUP_SCOPE.md

Borg Backup Scope for KalliLabcore

Stand: 2026-05-04

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	file data	/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	file data (SQLite inside /data)	/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
Homepage	file data	/local/appdata/homepage
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	self-backup	/local/appdata/borg-ui/data
Komodo	config + Mongo dump	/local/borg-dumps, /local/appdata/komodo/periphery, /local/appdata/komodo/core
Nextcloud	raw DB path + file data	/local/appdata/nextcloud/html, /local/appdata/nextcloud/postgres, /local/appdata/nextcloud/redis; user data path see gap below
Grafana	file data	/local/appdata/grafana
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 database

Recovery currently relies on the raw live DB path /local/appdata/nextcloud/postgres. This is inconsistent with the policy "Do not back up raw live database storage directories as the primary recovery artifact" stated below.

Open decision:

• Option A: extend ops/borg-ui/scripts/pre-backup-dumps.sh with a nextcloud-postgres dump and treat the raw path as transient.
• Option B: accept the raw path as a documented Nextcloud-specific exception.

Until decided, the raw path is what Borg sees today and is the only Nextcloud DB recovery surface.

Nextcloud user data path is outside the borg-ui mount set

/mnt/user/documents/nextcloud-data is not mounted into borg-ui in ops/borg-ui/docker-compose.yml. Nextcloud user files are therefore not in the current Borg scope. Resolution requires a separate Compose change (add a read-only mount) and is not silently fixed in this scope document.

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.

Database Dumps Required

Shared PostgreSQL (postgresql17)

• mailarchiver
• paperless
• authelia

Dedicated PostgreSQL

• mealie
• immich

Other Databases

• Komodo MongoDB

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/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
• filebrowser app state

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.