Ansible

All Ansible commands run from the ansible/ directory, with credentials loaded from .env into the shell:

cd ansible
export $(cat .env | grep -v '^#' | xargs)

Two inventories

Inventory	Use
`inventory/proxmox.proxmox.yml`	Dynamic — every VM and LXC, discovered from the Proxmox API
`inventory/hosts.ini`	Static localhost, for playbooks that run on the controller

Guests are grouped by Proxmox node and by Proxmox tag, so a guest tagged docker lands in tag_docker. The Docker playbooks target tag_docker:&proxmox_all_running — tagged and currently running.

Full detail: Inventory.

Playbooks

Playbook	What it does
`restart-docker-stacks.yml`	Restarts every running Compose stack with BWS secrets injected
`setup_new_machine.yml`	Baseline configuration for a freshly created guest
`setup-step-ca-client.yml`	Trusts the internal CA on a host
`distribute-bws-token.yml`	Installs `/etc/bws/token` so `bws` works on the host
`system-update.yml`	Package updates across the fleet
`prune-docker-images.yml`	Reclaims disk from unused images
`configure-lxc-mounts.yml`	Applies LXC bind-mount configuration
`clear-bash-history.yml`	Clears shell history on target hosts
`test-playbook.yml` / `test-proxmox-hosts.yml`	Connectivity and inventory checks

Per-playbook variables, host patterns and the traps worth knowing before a fleet-wide run: Playbooks.

# Fleet-wide
ansible-playbook -i inventory/proxmox.proxmox.yml playbooks/<playbook>.yml

# Scoped
ansible-playbook -i inventory/proxmox.proxmox.yml playbooks/<playbook>.yml --limit arcane
ansible-playbook -i inventory/proxmox.proxmox.yml playbooks/<playbook>.yml --limit 'arcane,traefik'

# Dry run
ansible-playbook -i inventory/proxmox.proxmox.yml playbooks/<playbook>.yml --check --diff

Restarting Docker stacks

This is the playbook that matters most day to day, because it is the supported way to apply secrets:

ansible-playbook -i inventory/proxmox.proxmox.yml playbooks/restart-docker-stacks.yml

# One host, no secret injection
ansible-playbook -i inventory/proxmox.proxmox.yml playbooks/restart-docker-stacks.yml \
  --limit traefik -e bws_inject_secrets=false

Variables and behaviour: Playbooks.

Roles

Six custom roles in playbooks/roles/, all idempotent and safe to re-run. setup_new_machine.yml applies all six in this order:

Role	What it does
`step_ca_client`	Internal CA trust — `step` CLI, bootstrap, system cert
`custom_apt_repo`	Nexus APT source and GPG key
`bitwarden`	`bw` and `bws` CLIs, architecture-aware
`lazygit`	Pinned lazygit binary from its GitHub release
`cli_tools`	zellij, zoxide, yq, dust, delta, helix, netwatch, plus `fzf`/`jq`/`ncdu` from APT
`mise`	`mise` from its official APT repository, plus system-wide shell activation

All but lazygit and cli_tools have their own README; those two are documented by their defaults/main.yml, which is also where the pinned versions live — bump the version variable there to upgrade a tool across the fleet.

Defaults worth knowing

From ansible/ansible.cfg: remote user is unknown224, become is off by default (pass --become or set become: true in the play), facts are cached as JSON in /tmp/ansible_facts for one hour, and logs are written to ansible/ansible.log.