chrisx8/infra

This is an Ansible monorepo for my homelab Linux environment.

Usage

Install dependencies

Install the following packages:

• Python 3.14
• prek
• uv

Set up repo environment

Install repo dependencies, including Ansible, Ansible collections, ansible-lint, pre-commit hooks, and other Python packages:

source ./activate -u

After initial setup, simply activate the virtualenv when working in this repo:

source ./activate

Update environment

Re-running the repo setup will update Python packages and Ansible collections:

source ./activate -u

Inventory

Ansible inventory lives in a separate repo, chrisx8/infra-inventory. source ./activate -u clones it into inventory/ on first run, and pulls it on subsequent runs. The inventory/ directory is .gitignored in this repo.

Run playbooks

Activate the virtualenv first, then run a playbook from plays/:

ansible-playbook plays/<playbook>.yml

Playbook	Purpose
deploy_os.yml	Base OS config for EL and Proxmox VE hosts
deploy_host_<service>.yml	Deploy host-level service (admin, container_runtime, k3s, pihole, postgresql, tailscale)
deploy_network.yml	Configure network devices (FortiGate)
deploy_app.yml	Deploy container and k8s apps, with optional PostgreSQL database
decom_app.yml	Remove container and k8s apps
upgrade_os.yml	OS package upgrades
validate.yml	Inventory validation (also runs as a pre-commit hook)

Lint

Run all pre-commit hooks (hygiene checks, yamllint, ansible-lint, and inventory validation):

prek run --all-files

Dependencies

Dependencies are declared in various places:

• Python dependencies are pinned by minor versions, declared in pyproject.toml
  • Re-run setup after updating dependency pins
• Pre-commit hooks are pinned by exact versions, declared in .pre-commit-config.yaml
  • Update by running prek autoupdate
• Ansible collections are pinned by minor versions, declared in requirements.yml
  • Re-run setup after updating dependency pins

License

GNU GPLv3

Copyright (c) 2021-2026 Chris Xiao