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

Borg Backup Scope for KalliLabcore

Stand: 2026-05-31

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
• Unraid flash configuration artifacts 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 plus unraid-flash-config.tar.gz 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. The Unraid flash configuration archive is intentional as well and must be treated as secret backup material.

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
Unraid OS flash	generated config archive	/local/borg-dumps/unraid-flash-config.tar.gz plus checksum and manifest
Nextcloud	DB dump + file data	/local/borg-dumps, /local/appdata/nextcloud/html, /local/nextcloud/data
Grafana	SQLite dump from monitoring_grafana_data + provisioned config in Git	/local/borg-dumps, monitoring/grafana/provisioning, monitoring/grafana/dashboards
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, runtime PostgreSQL 18)

• mailarchiver
• paperless
• authelia

Dedicated PostgreSQL

• mealie
• immich
• nextcloud

Other Databases

• Komodo MongoDB
• SQLite: gitea, vaultwarden, speedtest-tracker, borg-ui, grafana
• File-backed state: filebrowser.bolt.dump
• Unraid flash config: unraid-flash-config.tar.gz plus unraid-flash-config.tar.gz.sha256

Explicitly Not Backed Up as Raw Live DB Files

• /mnt/user/appdata/postgresql17
• /mnt/user/appdata/postgresql18
• /mnt/user/appdata/mealie/postgres
• /mnt/user/appdata/mealie/postgres18
• /mnt/user/appdata/immich_postgres
• /mnt/user/appdata/immich_postgres_vectorchord
• /mnt/user/appdata/nextcloud/postgres
• /mnt/user/appdata/nextcloud/postgres18
• /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
• 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.