Backup

Restic backups for every host in [backup_clients], run by backup.yml and scheduled weekly in Semaphore. One run backs up all clients, then maintains the repository once and reports to Home Assistant.

What is backed up

Source	How	Snapshot tags
Every /docker/<service>	Running containers are stopped, backed up, and exactly those are started again (always, also on failure). Stacks that are down stay down.	<service>, docker
backup_data_paths	Hot, from local disk. Only the path's own excludes apply.	<name>, data
Home Assistant	Full backup via ha backups new, then the backup directory	homeassistant, appliance
OPNsense	config.xml via the API (needs Diagnostics: Configuration History)	opnsense, appliance

New /docker directories are included automatically. Skipped: glances, gdu, restic-server, appliance-backups (+ backup_host_skip_services).

Exclusions

1. Global (backup_global_excludes, /docker only): cache, .cache, logs, *.log, MediaCover, .git, plus --exclude-caches and any directory with a .nobackup file.
2. Per service (backup_service_excludes, host_vars), relative to /docker/<svc>, e.g. llm-stack: ["ollama/data"].
3. Extra paths that belong to a service (backup_service_extra_paths), e.g. a database in a named Docker volume, are snapshotted with it while it is stopped.

Key Parameters

Variable	Default	Description
backup_restic_version	0.19.1	Pinned client, installed from the release with checksum
restic_backup_repo / restic_backup_password	(vault)	Repository URL and password
backup_retention_args	--keep-weekly 8 --keep-monthly 12	forget policy, grouped by host + tags
backup_check_read_subset	5%	Share of pack data read back by restic check per run
backup_offsite_repo	""	Second repository; when set, restic copy runs after each backup
backup_hot_services	[]	Services backed up without stopping them
backup_report_enabled	true	Publish sensor.homelab_backup_* to Home Assistant

Workflow

1. Install the pinned restic, check the repository (init only if it does not exist)
2. Per host: back up each service, data path and appliance, recording each outcome
3. Once, on the repository host: forget --prune, check --read-data-subset, optional off-site copy
4. Report to Home Assistant through mqtt.publish (retained MQTT discovery sensors)
5. Fail the run if any item failed, a client was missed, or check failed

Home Assistant sensors

Entity	State	Attributes
sensor.homelab_backup_status	ok / failed	the full report: per-service last snapshot, age, count, oldest, size; failures; missed hosts
sensor.homelab_backup_last_run	timestamp
sensor.homelab_backup_repo_size	GB

Restore

# A /docker service, from its latest snapshot on that host
ansible-playbook backup.yml -e backup_mode=restore -e backup_services=mealie --limit runner

Data paths and appliances are restored by hand:

restic snapshots --tag pictures                       # find the snapshot
restic restore <id> --target / --include /mnt/rstorage/media/pictures

Home Assistant: restore the restic-<date> backup file from the snapshot into /var/lib/homeassistant/backup, then restore it in HA. OPNsense: upload the config-<date>.xml under System → Configuration → Backups.