Home Lab Backup, Disaster Recovery & Update Runbook

The goal: recover services, not just files

A backup is useful only if you can identify it, decrypt/read it, restore it, and return the service to a known-good state. This runbook treats recovery as an operational capability.

Protect → verify → rehearse → recover → document the gap

Your important layers are: Home Assistant and its add-ons; the Linux host; Docker applications and volumes; Firefly III plus MariaDB; Hermes state/configuration; and the Git-backed KB source. Each fails differently, so each needs an appropriate backup.

The 3-2-1 baseline

Keep 3 copies on 2 different media types, with 1 copy off-site. A local disk protects against accidental deletion; it does not protect against theft, fire, ransomware, or a failed host.

Your current recovery map

The host runs three healthy Firefly-related containers: the core service, importer, and MariaDB database. The KB is Git-backed and can be rebuilt statically. Home Assistant has its own backup facility. Keep these systems separate in your mind: a successful container restart is not a database backup, and a Git push is not a backup of uncommitted local work.

Never publish or paste .env files, database dumps, tokens, credentials, or private financial records into a KB page, Git issue, or chat.

Backup schedule and retention

Use a schedule that balances recovery point objective (how much work you can lose) with storage and effort.

Encrypt off-site backups and protect the recovery key separately. An encrypted backup without a recovery key is not recoverable; an unencrypted off-site financial backup is not acceptable.

Pre-change checklist

Run this before Home Assistant, Docker, Hermes, database, operating-system, or network updates:

[ ] Read the release notes and identify breaking changes.
[ ] Confirm a current backup exists and its age is acceptable.
[ ] Record current version and service health.
[ ] Define rollback: restore, downgrade, or redeploy?
[ ] Avoid changes immediately before travel or severe weather.
[ ] Change one layer at a time.
[ ] Verify the service and its critical dependency chain after the change.

Home Assistant recovery

1. Confirm HA reaches Running and the dashboard loads.
2. Check critical integrations: Zigbee2MQTT, Matter Server, climate, notifications, and network monitoring.
3. Verify animal- and safety-relevant entities before relying on automations.
4. Use the built-in backup/restore flow for a full HA recovery.
5. If a peripheral integration fails, restore only the relevant configuration where possible instead of rolling back the whole house blindly.

HA smoke test

[ ] A critical light/switch accepts a safe command.
[ ] Climate state is plausible and controllable.
[ ] Coop door sensors show a believable state.
[ ] Zigbee2MQTT bridge is connected.
[ ] WAN ping monitor is reachable.
[ ] No new high-severity errors in Settings → System → Logs.

Docker and database recovery

Treat application definition and application data separately.

# Inspect services without exposing secrets
docker ps
docker compose ps

# Capture a MariaDB dump before a Firefly or database upgrade
# Replace placeholders locally; never put credentials in shell history or documentation.
docker exec <database-container> mariadb-dump --single-transaction <database-name> | gzip > backup.sql.gz

gzip -t backup.sql.gz

To recover, create the intended database/service version first, import the dump into an empty target database, start the application, and validate account count, recent transaction totals, and importer access. Never test restoration against the only live database.

Host failure recovery order

A calm order reduces cascading mistakes:

1. Network and power: router, switch/AP, DNS, internet path.
2. Host: storage health, OS boot, time synchronisation, Docker availability.
3. Control plane: Home Assistant and core networking integrations.
4. Data services: database before dependent applications.
5. Applications: Firefly, Hermes, KB toolchain, other services.
6. Automation verification: critical safety/household workflows.
7. Observability: backups, alerts, logs, and monitoring.

Do not start from “what is easiest to click.” Start from dependencies.

Incident playbooks

A service is down but host is up

docker ps -a
docker logs --tail 100 <container>
docker inspect <container> --format '{{.State.Status}} {{.State.ExitCode}}'
docker compose up -d <service>

Check database reachability before repeatedly restarting an application. Repeated restarts can obscure the original error.

The host restarts unexpectedly

• Record approximate time and symptoms before making changes.
• Confirm disk space, storage health, uptime, and service logs.
• Run the HA and Docker smoke tests.
• Do not infer “fixed” from one successful reboot; monitor for recurrence.

The network is down

Your WAN watchdog is intentionally monitoring-only. First distinguish ISP outage, router failure, Wi-Fi-only failure, and HA/host failure. Preserve evidence before manually rebooting gateway equipment.

Restore rehearsal

Schedule a small restore rehearsal quarterly:

1. Choose one non-critical artifact: a DB dump, HA backup, or KB clone.
2. Restore it into an isolated/test location.
3. Confirm the expected data/configuration appears.
4. Measure time and note missing prerequisites.
5. Update this runbook and the backup procedure.

Recovery record template

Incident:
Start/end time:
User impact:
Affected layer:
Evidence retained:
Root cause (known / suspected):
Recovery actions:
Data loss window:
Follow-up prevention:
Runbook update needed:

Reference links

• Home Assistant backups
• Docker backup and restore guidance
• Firefly III documentation
• Git documentation

Use this as the source of truth for process, then keep private paths, keys, and recovery contacts in a separately protected record.