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.
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 bothA 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 --validateAuthenticated 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 --applySee ADR 0006 for boundaries.
Operator references
- Agent skills for Firecrawl, routine updates and Hermes secrets
- Backups and restores
- Hermes operations
- Firecrawl MCP companion
- Infisical Agent and profile secret workflow
- Kubernetes-node installation
- Shared collection maintenance
- GitHub token rotation
- Development and verification
- Decisions
Keep secrets out of Git. requirements.yml, inventory, role defaults, and tasks
are authoritative for exact configuration; Git history retains completed plans.