Skip to content

Rebuild a node

Bring a wiped node back into service from this repository and the backups. Order matters: platform, network, data, then services.

vps-apps

  1. OS: Debian, non-root user with sudo + docker group.
  2. Docker: install, then apply the daemon policy from the repo: log caps (max-size 10m, max-file 3), MTU, DNS (pi-home mesh IP + 9.9.9.9) — mirror /etc/docker/daemon.json.
  3. NFS mounts: recreate the wg-direct client config for /mnt/pi-hdd (exports restrict to this host's tunnel IP) and mount the nfs_* volume trees.
  4. Repo: clone to /opt/homelab, install the sync timer, then for each tracked stack cp .env.example → .env and fill from the secret vault before compose up -d.
  5. Data: restore from restic per restore.md into /opt/homelab-data/.
  6. Timers: docker-prune, musicload purge, model refresh, session prune (unit files ship in the repo under vps-apps/maintenance/, hermes-agent).
  7. Mesh: re-register the peer; restore its mesh IP assignment.
  8. Verify the whole manifest against nodes.md.

pi-home

  1. OS: Raspberry Pi base image; set hostname; create admin user.
  2. Storage: mount/format the HDD at /mnt/pi-hdd; recreate the userdata tree; nfs-server exports re-point to the vps-apps tunnel IP.
  3. Units: re-install the native units (vaultwarden, radicale, ntfy, pocket-id, hydroxide, filebrowser, syncthing, beszel hub/agents, cloudflared, telegram-bot, pihole-FTL config, dropbear on the custom port, fail2ban+ufw), then apply the mesh bind ordering drop-ins (pi-home/cleanup/mesh-bind-order-fix.sh) and install the watchdog (pi-home/mesh-watchdog/).
  4. Netbird: register as a peer (it is also mesh DNS + nameserver target).
  5. Tunnels: recreate wg-direct server side and wgr-vpsnet client.
  6. Data: restore the userdata tree per restore.md.

vps-net

Deliberate, reviewed, with a store backup first. Full procedure: netbird-down.md for recovery and the pinned-version discipline for the stack. If the control-plane store is lost, peers must be re-enrolled — treat as a last resort.

After any rebuild

  • Fresh backups run and verify on the recovered node.
  • Docs still match reality; fix nodes.md if the rebuilt node disagrees.