ansible-ctrl

Provision workstations and servers using Ansible.

Requirements

• Ansible >= 2.14.6
• Ubuntu >= 24.04

Initial Setup

Install Ansible on Ubuntu via the Ansible PPA:

sudo add-apt-repository --yes --update ppa:ansible/ansible
sudo apt install ansible

Create a hosts file in the project root (gitignored):

example ansible_connection=local ansible_host=example.com ansible_user=andornaut ansible_python_interpreter=/usr/bin/python3

[workstations]
example

[upgrade]
example

Inventory and host variables

• hosts (gitignored): inventory file
• host_vars/<hostname>.yml (gitignored): per-host variable overrides — feature flags ({role}_install_{component}), Docker image tags, extra volumes, and any host-specific configuration
• Role defaults live in roles/<role>/defaults/main.yml; override them in host_vars/, not in defaults

Secrets

Secrets (API tokens, SMTP passwords, Cloudflare tokens, HA long-lived tokens) are stored in host_vars/ files, which are gitignored. For shared or committed secrets, use ansible-vault:

ansible-vault encrypt host_vars/example.yml
ansible-playbook --ask-vault-pass --ask-become-pass desktop.yml

CI

Pull requests run ansible-lint on the playbooks and roles. Run the same check locally:

python3 -m venv /tmp/ansible-lint-venv && /tmp/ansible-lint-venv/bin/pip install ansible-lint && /tmp/ansible-lint-venv/bin/ansible-lint

Usage

$ make help
Available targets:
  clean                 - Remove temporary role files
  help                  - Show this help message
  requirements          - Install required Ansible roles and collections

Playbook targets:
  ai_maintainer         - Configure automated GitHub repository maintenance
  base                  - Configure base system
  bspwm                 - Configure BSPWM window manager
  desktop               - Configure desktop environment
  dev                   - Configure development tools
  docker                - Configure Docker and Kubernetes
  games                 - Configure gaming packages
  hobbies               - Configure hobby tools (3D printing, electronics, FPV)
  homeautomation        - Configure home automation
  msmtp                 - Configure email forwarding
  nas                   - Configure NAS server
  niri                  - Configure Niri compositor
  rsnapshot             - Configure rsnapshot backup
  upgrade               - Run system upgrades
  webservers            - Configure web servers

# Run specific tasks by tag:
ansible-playbook --ask-become-pass desktop.yml --tags alacritty
ansible-playbook --ask-become-pass hobbies.yml --tags orcaslicer

Roles

Role	Purpose
ai_maintainer	Automated GitHub repo maintenance via AI agent + cron
bspwm	BSPWM window manager
desktop	Desktop environment (display manager, browser, fonts, themes)
dev	Development tools and programming languages
docker	Docker CE, Compose, optional Kubernetes
games	Gaming packages via flatpak
hobbies	3D printing, electronics, FPV tools
homeautomation	Home Assistant + related Docker containers
letsencrypt_nginx	NGINX reverse proxy with Let's Encrypt HTTPS
msmtp	Email forwarding via MSMTP
nas	Encrypted BTRFS RAID arrays (LUKS)
niri	Niri Wayland compositor
rsnapshot	Incremental backups with rsnapshot

Troubleshooting

Upgrade all collections:

ansible-galaxy collection install --upgrade -r requirements.yml