Skip to content

Homelab Improvement Plan - 2026-02-04

Code review findings from deep analysis of docker/, ansible/, and docs/ directories.

Critical Issues (Deploy-Blocking)

# Issue File Line Status
1 VPS Restic IP mismatch (100.64.0.20 vs 100.64.0.100) docker/vps/backup/README.md 21, 40, 46 Fixed
2 Mobile Pi-hole IP mismatch (.5 vs .10) docker/mobile/rpi5/.env.example 14, 18 Fixed
3 Missing mosquitto.conf file docker/fixed/docker-vm/automation/ - N/A (exists)
4 Missing/incomplete frigate.yml config docker/fixed/docker-vm/security/ - N/A (exists)
5 HOMELAB_ROOT not documented in .env files multiple .env.example files - Fixed

High Priority Issues

# Issue File Line Status
6 Stack dependency not documented (automation → security) docker/fixed/docker-vm/security/docker-compose.yml 193 N/A (exists)
7 NFS mount IP hardcoded in playbook warning ansible/playbooks/docker-compose-deploy.yml 144-145 Fixed
8 Camera RTSP credentials in plaintext docker/fixed/docker-vm/security/frigate.yml 101-104 Fixed
9 Restic password var inconsistency (PASSWORD vs PASSWORD_FILE) multiple docker-compose files - Fixed
10 NAS download path symlink not in nfs-server playbook ansible/playbooks/nfs-server.yml 39 Fixed

Medium Priority Issues

# Issue File Line Status
11 Proxmox vs OPNsense IP ambiguity (.10 vs .14) docker/vps/monitoring/monitors.md 31 Fixed
12 Missing certificate renewal cron example docker/fixed/docker-vm/networking/caddy/Caddyfile 110 Fixed
13 Docker image version not pinned (watchtower:latest) docker/fixed/docker-vm/maintenance/docker-compose.yml 11 Fixed
14 Caddy loose version (2.8 vs specific) multiple Caddyfiles - Fixed
15 Vaultwarden signups default could be clearer docker/fixed/docker-vm/security/docker-compose.yml 61 Fixed
16 NFS media export missing no_root_squash ansible/playbooks/nfs-server.yml 33 Fixed
17 Samba credentials visible in docker inspect docker/fixed/nas/storage/docker-compose.yml 42 Fixed
18 OpenClaw VM local IP comment missing ansible/inventory.yml 50 N/A (exists)

Low Priority Issues

# Issue File Line Status
19 Mobile Pi-hole uses port 8080 vs 8053 (inconsistent) docker/mobile/rpi5/networking/pihole/docker-compose.yml 32 Fixed
20 Backup volume path naming (BACKUP_DATA vs BACKUP_PATH) multiple - Fixed
21 Jellyfin cache not on tmpfs (slow transcoding) docker/fixed/docker-vm/media/docker-compose.yml 37 Fixed
22 Network topology doc incomplete docs/network-topology.md 82+ N/A (complete)

Fixes Applied

Critical

  1. VPS Restic IP: Changed all references from 100.64.0.x to actual IP 100.77.172.46
  2. Mobile Pi-hole IP: Changed HOST_IP from 192.168.8.10 to 192.168.8.5, updated Tailscale IP references
  3. mosquitto.conf: Already exists with complete configuration (false positive)
  4. frigate.yml: Already exists with complete configuration (false positive)
  5. HOMELAB_ROOT: Added to security and automation .env.example files

High Priority

  1. Stack dependency: Documentation already exists at lines 195-203 (false positive)
  2. NFS IP configurable: Added nas_ip variable to docker-compose-deploy.yml playbook
  3. Camera credentials: Changed from placeholder syntax to proper env vars (FRIGATE_REOLINK_, FRIGATE_TAPO_)
  4. Restic password: Documented consistency requirement - both stacks must use same password
  5. NFS symlinks: Added symlink creation tasks to nfs-server.yml (media, downloads, backup, frigate)

Medium Priority

  1. OPNsense IP: Fixed monitors.md from 100.64.0.14 to 100.79.230.235 (actual Tailscale IP)
  2. Certificate renewal: Updated Caddyfile to note Headscale limitation
  3. Version pinning: Pinned watchtower:1.7.1, alpine:3.19 for backup sidecars, documented changedetection:latest rationale
  4. Caddy version: Pinned to 2.8.4 (fixed) and 2.8.4-alpine (VPS)
  5. Vaultwarden signups: Added security comment explaining default=false
  6. NFS no_root_squash: Added comment explaining why media export doesn't need it (read-only)
  7. Samba credentials: Enhanced warning with mitigations and alternative image suggestion
  8. OpenClaw local IP: Already had comment (false positive)

Low Priority

  1. Mobile Pi-hole port: Added comment explaining 8080 vs 8053 difference (intentional)
  2. Backup naming convention: Documented BACKUP_PATH (source) vs BACKUP_DATA (destination) in restic-backup.sh
  3. Jellyfin cache: Added commented tmpfs option for faster transcoding
  4. Network topology: Already complete (487 lines, all sections present)

Action Plan

Phase 1: Critical Fixes (Today)

  1. Fix VPS Restic IP references
  2. Fix Mobile Pi-hole IP references
  3. Create mosquitto.conf from template
  4. Create/complete frigate.yml base config
  5. Document HOMELAB_ROOT in all .env.example files

Phase 2: High Priority (Today if time permits)

  1. Add stack dependency documentation
  2. Make NFS IP configurable in playbook
  3. Move camera credentials to environment variables
  4. Standardize Restic password variable naming
  5. Add downloads symlink to nfs-server playbook

Phase 3: Medium Priority (Later)

  1. Pin all Docker image versions
  2. Add certificate renewal documentation
  3. Improve Vaultwarden defaults
  4. Fix NFS export options consistency

Phase 4: Low Priority (Backlog)

  1. Documentation cleanup
  2. Performance optimizations
  3. Naming consistency

Created: 2026-02-04 Last updated: 2026-02-04