← All projects

xbxd/homelab

Homelab Playbooks

Ansible playbooks for keeping my homelab up to date and getting new machines configured. I use them to make the routine jobs repeatable instead of relying on notes and memory.

  • ansible
  • automation

Project details

Primary language: Python

Last commit:

Language mix

  • Python 85%
  • Jinja 11%
  • Shell 4%

Weekly commits

Commit counts by UTC week start for the last 52 weeks.

375 commits total; busiest week: 2026-08-02 (63 commits).

README

homelab

Ansible updates, provisioning, and configuration for Brendan's homelab. Work and production infrastructure live in separate repositories.

Setup

ansible-galaxy collection install -r requirements.yml -p collections/

Rerun this after changing the pin in requirements.yml; updating that file does not refresh an already-installed collection.

Normal runs need the local, gitignored inventory/hosts, matching SSH aliases, and any required vault variables. pass.sh reads the vault password from the macOS keychain. inventory/hermes.ini is the tracked inventory for focused Hermes operations.

Playbooks

Playbook Purpose
update-servers.yml OS, package, dotfile, Komodo and Duplicacy Web updates
provision-servers.yml Initial Kubernetes-node OS provisioning
config.yml Docker daemon options, application-log rotation and daily host-config backups to PBS
infisical.yml Install the pinned Infisical CLI and distribute Docker-node client IDs
firecrawl-mcp.yml Manage the separate Firecrawl MCP service, weekly updater, and narrow proxy route
hermes-agent.yml Hermes accounts and sudo on target hosts, and checks on excluded hosts
hermes-services.yml Hermes service checks, with an optional pull, restart or recreate
hermes-profile.yml Copy profile secrets during a container outage, or delete a profile; automatic creation is blocked
infisical-agent.yml Render Hermes secrets with the Infisical Agent and promote them

Updates

update.sh updates this Mac with Homebrew, then runs update-servers.yml. Homebrew goes first so it can upgrade Ansible before Ansible starts. Run it from a terminal, because cask upgrades may ask for your password.

./update.sh                                      # Homebrew, then the servers
./update.sh brew                                 # Homebrew only
./update.sh servers --limit servarr --check --diff  # Ansible only, options pass through
./update.sh --check                              # Preview both

A failed step stops the run. Check mode is a preview, not proof of deployment.

Infisical client IDs

The infisical.yml playbook distributes nonsecret per-node Universal Auth client IDs to ~/.config/infisical/client-id on Docker hosts. Configure the mapping and follow the client-ID runbook; client secrets remain outside Ansible.

Infisical structure

Validate the nonsecret rollout manifest without contacting Infisical:

python3 scripts/infisical_scaffold.py --validate

Authenticated reconciliation defaults to a read-only plan. --apply changes only nonsecret structure and access policy for the selected project:

python3 scripts/infisical_scaffold.py --project traefik-proxy
python3 scripts/infisical_scaffold.py --project traefik-proxy --apply

See ADR 0006 for boundaries.

Operator references

Keep secrets out of Git. requirements.yml, inventory, role defaults, and tasks are authoritative for exact configuration; Git history retains completed plans.