Skip to content

Configuration

Where to change something, by what kind of setting it is.

Layering

Ansible variable precedence applies as normal: role defaults are the fallback, group_vars/all/* applies cluster-wide, group_vars/<group>.yml applies to a group, host_vars/<host>.yml overrides per-host, and -e/--extra-vars on the command line beats everything. In practice, this repository uses that layering as follows.

Kind of setting Lives in Example
Cluster-wide non-secret config (domain, SMTP/MQTT relay, appliance IPs) inventory/group_vars/all/vars.yml base_domain, smtp_host, pihole_vm_ip
Secrets inventory/group_vars/all/vault.yml (Ansible Vault) vault_* — see Vault variables
Manager-node-only config and the vault→app-variable indirection inventory/group_vars/swarm_managers.yml traefik_trusted_proxies, authentik_secret_key: "{{ vault_authentik_secret_key | default('') }}"
Proxmox-cloned-VM-only config inventory/group_vars/proxmox_vms.yml proxmox_vm_validate_certs
Per-host sizing and identity inventory/host_vars/<host>.yml swarm-core.yml: cores, memory, disk, swarm_node_labels
Role behaviour defaults ansible/roles/<role>/defaults/main.yml docker_install_nvidia_toolkit, pihole_upstream_dns
Per-stack deploy wiring (which secrets/extra templates a stack gets) ansible/playbooks/deploy-stacks.yml the stacks list
Per-service runtime config not expressible as an env var Extra templates rendered alongside the stack's compose.yml.j2 Kimai's local.yaml, Matomo's common.config.ini.php, NetBox's oidc.py/proxy.py, Authentik's blueprints

Adding a new stack

  1. Add ansible/stacks/<tier>/<name>/compose.yml.j2 (and any extra template files it needs).
  2. Add an entry to the stacks list in ansible/playbooks/deploy-stacks.yml (name, tier, secrets, extra_templates).
  3. Add any new vault_* variables to vault.yml.example, and the vault-to-plain-var indirection to group_vars/swarm_managers.yml.
  4. Add docs/site/content/services/<tier>/<name>.md — required, or docs/site/tests/test_service_coverage.sh fails the build (see Keeping this site up to date).
  5. Add the new vault_* variables to docs/site/content/vault-variables.md — required, or docs/site/tests/test_vault_variable_coverage.sh fails.

Adding a new VM or role

Add host_vars/<host>.yml for sizing/IP/labels, and a role under ansible/roles/<name>/ if it needs its own configuration beyond the shared common/docker roles. See the appliance VM pages for the pattern the existing appliance VMs follow.

Node placement

Every Swarm service carries a deploy.placement.constraints entry (node.labels.tier == core or == media), applied by the swarm role from swarm_node_labels in each manager/worker's host_vars. A stack's database lives on a local (non-NFS) volume on its node, so a stack does not migrate if its node label changes without also moving its data — see Resources and Backups.