HomeBackup/CLAUDE.md

HomeBackup Project Conventions

Purpose

Backup solution for home lab: 7 Raspberry Pis, OpenWrt router, Linux servers → Synology NAS.

Architecture

• Restic via REST server (Docker on Synology) for daily incremental backups — HTTP basic auth, no SSH keys
• dd over NFS for monthly full SD card images
• Ansible for deployment and management — password auth via sshpass
• OpenWrt pushes config to a designated Pi; that Pi includes it in its restic backup

Key Decisions

• Shared restic repo (all devices, max dedup); snapshots identified by hostname
• REST server backend — avoids SSH key management for backup transport
• Retention per host: 7 daily, 4 weekly, 6 monthly
• Docker containers stopped before backup, restarted after (consistent volumes)
• Image backups kept for 3 months on Synology NFS share

Directory Layout

ansible/
  ansible.cfg
  vault.yml               # ansible-vault encrypted — never commit plaintext
  inventory/
    hosts.yml
    group_vars/           # vars scoped to groups
    host_vars/            # per-device overrides
  roles/
    restic-client/        # installs restic, systemd timer, repo init
    docker-backup/        # pre/post hooks to stop/start containers
    image-backup/         # monthly dd image via NFS
  playbooks/
    deploy.yml            # push backup stack to all devices
    run-backup.yml        # ad-hoc trigger
    check.yml             # verify repo health and timer status
scripts/
  openwrt-backup.sh       # runs on OpenWrt router (ash/busybox compatible)
  synology-setup.sh       # one-time REST server bootstrap on Synology
docs/
  restore.md              # recovery runbooks per device type
  synology-setup.md       # Synology setup guide

Secrets

• All passwords in ansible/vault.yml, encrypted with ansible-vault encrypt
• Vault password kept outside the repo (e.g. in a password manager)
• Never commit an unencrypted vault.yml

Common Commands

# Deploy to all Pis
ansible-playbook ansible/playbooks/deploy.yml --ask-vault-pass

# Deploy to a single host
ansible-playbook ansible/playbooks/deploy.yml --limit pi1 --ask-vault-pass

# Trigger ad-hoc backup
ansible-playbook ansible/playbooks/run-backup.yml --ask-vault-pass

# Check backup health
ansible-playbook ansible/playbooks/check.yml --ask-vault-pass

# Encrypt vault after editing
ansible-vault encrypt ansible/vault.yml

Adding a New Device

1. Add host to ansible/inventory/hosts.yml under the correct group
2. Add ansible/inventory/host_vars/<hostname>.yml for any overrides
3. Add password to vault if different from group default
4. Run deploy with --limit <hostname>

Requirements (Control Node)

• Ansible >= 2.12
• sshpass package installed (apt install sshpass)
• Python 3