Skip to content

Homelab Improvement Plan - 2026-01-21

Codebase review identified issues in Ansible playbooks, Docker Compose files, and documentation.

Critical Issues

# Issue File Line Status

| 1 | ansible_connection_timeout is not a valid Ansible parameter (should be ansible_connect_timeout) | ansible/inventory.yml | 82 | Fixed | | 2 | Caddy references external networks (headscale-net, monitoring-net) not created by any task | ansible/playbooks/caddy.yml | 178-191 | Fixed | | 3 | Path construction used environment_type instead of host-specific paths, breaking deployments | ansible/playbooks/docker-compose-deploy.yml | 19-42, 66-82 | Fixed | | 4 | Relative path ../../../shared/backup/restic-backup.sh will fail when executed from different directories | docker/fixed/docker-vm/security/docker-compose.yml | 158 | Fixed | | 5 | Undefined variables with inconsistent naming (restic_user, restic_pass, restic_password) | ansible/playbooks/backup.yml | 11-14 | Fixed |

Fixes Applied

  1. inventory.yml: Changed ansible_connection_timeout to ansible_connect_timeout
  2. caddy.yml: Added community.docker.docker_network tasks to create external networks before deployment
  3. docker-compose-deploy.yml: Added stack_paths dictionary mapping host groups to correct directory paths (vps, fixed/docker-vm, fixed/nas, mobile/rpi5). Renamed fixed_stacks to docker_vm_stacks, nas_stacks to storage_stacks.
  4. security/docker-compose.yml: Changed relative path to use ${HOMELAB_ROOT:-/opt/homelab/repo} environment variable
  5. backup.yml: Renamed variables to restic_repo_user, restic_repo_pass, restic_password. Added validation task with clear error message.

High Priority Issues

# Issue File Line Status

| 6 | No .env files present (only .env.example) - fresh deployments will fail | All docker directories | - | N/A (handled by docker-compose-deploy.yml) | | 7 | Pi-hole password defaults to empty string (insecure) | ansible/playbooks/pihole.yml | 22-31 | Fixed | | 8 | NFS export paths hardcoded (/srv/media, /srv/downloads), may not exist | ansible/playbooks/nfs-server.yml | 12-39 | Fixed | | 9 | ignore_errors: true masks firewall rule failures | ansible/playbooks/common.yml | 87-105 | Fixed | | 10 | Missing Headscale playbook for VPS deployment | ansible/playbooks/headscale.yml | - | Fixed |

Fixes Applied

  1. docker-compose-deploy.yml: Already has task to create .env from .env.example if not exists (lines 127-134)
  2. pihole.yml: Added assert task requiring webpassword variable with clear error message
  3. nfs-server.yml: Made paths configurable via nfs_data_root and nfs_purple_root variables (default to /mnt/data and /mnt/purple). Added mount point validation with warning if drives not mounted.
  4. common.yml: Replaced ignore_errors: true with proper conditional check for tailscale0 interface existence
  5. headscale.yml: Created new playbook with full deployment automation (config, docker-compose, backup script, user creation)

Medium Priority Issues

# Issue File Line Status

| 11 | Hardcoded IPs should use environment variables or container names | Multiple docker-compose files | - | Acceptable (defaults with env var override) | | 12 | Dead code: docker_compose_version: "2" variable defined but never used | ansible/inventory.yml | 93 | Fixed | | 13 | Inconsistent Tailscale IP addressing between docs and configs | Multiple files | - | Fixed |

Fixes Applied

  1. Hardcoded IPs: Reviewed - IPs are used as sensible defaults with ${VAR:-default} pattern allowing override via .env files. Acceptable design.
  2. inventory.yml: Removed unused docker_compose_version: "2" variable from docker_hosts group
  3. Tailscale IPs: Fixed Docker VM IP references to 100.68.63.168 in:
    • docker/fixed/docker-vm/networking/pihole/docker-compose.yml (DNS records comments)
    • docker/fixed/docker-vm/networking/caddy/Caddyfile (header comment)

Low Priority Issues

# Issue File Line Status

| 14 | Relative paths in docker-compose assume specific working directories | Multiple files | - | Fixed | | 15 | Session docs in README may reference deleted files | README.md | 85 | Verified OK |

Fixes Applied

  1. Relative paths: Fixed backup script mount in docker/fixed/docker-vm/automation/docker-compose.yml to use ${HOMELAB_ROOT:-/opt/homelab/repo} pattern (same as security stack fix)
  2. README references: Verified all referenced session files exist (2026-01-16.md, improvements-2026-01-16.md)

Summary

All 15 issues have been addressed:

  • 5 Critical: Fixed
  • 5 High Priority: Fixed (1 N/A - already handled)
  • 3 Medium Priority: Fixed (1 acceptable as-is)
  • 2 Low Priority: Fixed (1 verified OK)

Notes

  • All fixes should be tested with ansible-playbook --check (dry-run) before applying
  • Docker Compose changes should be validated with docker compose config
  • Document any breaking changes that require manual intervention