This project is contains the automation for my personal homelab.
This is primarily built as a personal setup and not necessarily meant to be a reusable project for others, though I do try my best to make the roles as reusable for a few different setups as I can. Feel free to borrow from it. If you want to run it yourself, you'll need to write your own playbooks for the apps you want, set the variables in your own inventory, and create the secrets those variables reference (see Secrets).
- Hosts run Fedora Server, installed unattended from a generated kickstart file.
- Apps run as Podman Quadlet units, so systemd manages each container, network and volume. Each app is an Ansible role in the in-tree collection
jaredhocutt.homelab, and each one gets its own isolated network. - Traefik routes every app by hostname. Authentik provides SSO, either through each app's native OIDC support or as Traefik forward-auth.
- Pangolin runs on a DigitalOcean droplet (
edge). Each app that's public gets an outboundnewttunnel to it, so publishing an app doesn't mean opening a port at home. - Secrets live in Bitwarden Secrets Manager and are fetched at runtime. Nothing secret is committed, apart from a few Ansible Vault files whose password is also in Bitwarden.
playbooks/ one playbook per host: apps, pta, edge, router, kickstart
inventory/ hosts.yml, group_vars/, and host_vars/<host>/<role>.yml
collections/ansible_collections/jaredhocutt/homelab/
roles/ one role per app, plus server_setup, podman, common, ...
plugins/lookup/ bws, container_config, traefik_labels
extensions/molecule/ one test scenario per role
scripts/ helpers run through `uv run task ...`
You'll need a macOS or Linux control node. On Windows, use WSL2, and keep the repo inside the Linux filesystem, not under /mnt/c. Install these tools:
- uv
- the
bwsCLI andjq, which fetch the vault password skopeo, for checking image tagspodman, for running molecule tests- GNU sed (
brew install gnu-sedon macOS)
uv sync
uv run ansible-galaxy collection install -r collections/requirements.ymluv sync installs the pinned ansible-core plus the dev tools (ansible-lint, molecule, taskipy). Run everything through uv run so those pinned versions are used.
Two environment variables must be set in your shell:
| Variable | Used by |
|---|---|
BWS_ACCESS_TOKEN |
the bws CLI and the bws lookup plugin |
BWS_ORGANIZATION_ID |
the bws lookup plugin |
How you set them is up to you. I load them with a bws-env shell function from my dotfiles.
There are two ways secrets are used:
-
Lookups. Inventory and roles fetch secrets by name, e.g.
"{{ lookup('jaredhocutt.homelab.bws', 'karakeep_nextauth_secret') }}". Names follow these patterns:<role>_<thing>for app secretsnewt_<role>_*for an app's Pangolin tunnelansible_host_<host>for host addresseshomelab_smtp_*for the shared mail settings
To list the secrets an app needs, pull the lookup names out of its inventory file:
grep -oE "bws', '[^']+'" inventory/host_vars/apps/karakeep.yml | cut -d"'" -f3 | sort -u
-
Ansible Vault.
vault/vault-open.shfetches the vault password from the secret namedansible_vault_password. SetANSIBLE_VAULT_PASSWORDto skip the lookup, orANSIBLE_VAULT_SECRET_NAMEto use a different secret name.
To check that secrets and SSH are working, ping a host:
uv run ansible apps -m ansible.builtin.pingEach host has its own playbook, which sets up the server and then deploys its apps:
uv run ansible-playbook playbooks/apps.yml| Playbook | What it does |
|---|---|
apps.yml, pta.yml |
Runs base server setup, then Traefik (plus Authentik on apps), then the apps |
edge.yml |
Creates the DigitalOcean droplet if it's missing, keeps its firewalls and wildcard DNS in sync, then sets up the droplet and deploys Pangolin |
router.yml |
Manages the pfSense DNS resolver entries |
kickstart.yml |
Renders a host's kickstart file; see Installing a new host |
Every role is tagged with its name, so you can deploy one app on its own:
uv run ansible-playbook -v playbooks/apps.yml --tags karakeep-
Fill in
inventory/host_vars/<host>/kickstart.ymlwith the host's hostname, network interfaces, disks and users. Copy an existing host's file as a starting point. -
Render the kickstart file to
/tmp/ks.cfg. Every host writes to the same path, so the playbook refuses to run unless--limitpicks exactly one host:uv run ansible-playbook playbooks/kickstart.yml --limit <host>
-
Write it to a USB drive.
scripts/oemdrv.sh(macOS only) partitions the drive with anOEMDRVvolume and copiesks.cfgonto it. -
Boot the Fedora Server installer with the USB drive plugged in. The installer finds the kickstart file on the
OEMDRVvolume and installs unattended. -
Add the host's address to Bitwarden as
ansible_host_<host>, then run the host's playbook. For a host that's new to this repo rather than a reinstall, first add it toinventory/hosts.ymland give it a playbook.
edge doesn't use kickstart, because edge.yml creates its droplet.
| Task | Command |
|---|---|
| Check for newer image tags | uv run task check-image-tags inventory/host_vars/apps |
| Edit a vault file | uv run task vault-edit <path> |
| Lint | uv run ansible-lint |
| Test one role | uv run task molecule test -s <role> |
Each image tag in the inventory has a comment containing the skopeo command that lists its upstream tags, and check-image-tags runs those commands. A tag can be held back with a # hold: marker, and CLAUDE.md explains how.
With Claude Code, /update-image-tags <host> applies the updates and writes out the deploy and commit commands.
- With Claude Code: run
/new-role <app> [compose URL]. It researches the app, builds the role from the closest existing one, wires up the inventory, playbook and tests, and lists any places it would deviate from the upstream compose file so you can decide on each. - By hand:
uv run task duplicate-role <existing_role> <new_role>copies a role and renames its variables. CLAUDE.md documents the conventions a role should follow.