Homelab Ansible Playbooks

This repository contains Ansible playbooks and roles I use to manage my NAS and some VMs 👨‍💻.

This project is designed for personal/familial scale maintenance, if you find this useful for your use, want to share advises or security concerns, feel free to drop me a line.

This is a good playground to learn and I encourage you to adapt these roles to your needs. While they might not be production-ready for all environments, I'm open to adapting them for Ansible Galaxy if there's community interest!

Architecture Overview

Platform Support: Arch Linux, Debian/Ubuntu

Core Design:

• A unique system administrator ({{ ansible_user }})
• Security hardened sshd
• Shared services pattern: Single PostgreSQL and Valkey (Redis) instances serve all services
• Rootless Podman: Containers run as {{ ansible_user }} (daemonless, sudo podman ps shows nothing)
• User systemd services: systemctl --user status <service> with lingering enabled
• Nginx reverse proxy for web services
• IP Freebind when available (e.g. unbound does not wait for wireguard to be up to start resolving DNS)

Available Services:

Service	Description
dns	Unbound caching DNS + Pi-hole ad blocking + VPN resolver
nfs	Network file system server
zfs	ZFS installation and management
uptime-kuma	Uptime monitoring
ntfy	Notification server
gitea	Git server
immich	Photo management
static-web	Static website hosting
vpn	WireGuard server

Requirements

Base tools:

# linux
apt-get install ansible ansible-lint ansible-galaxy
pacman -Syu ansible ansible-lint ansible-galaxy
# macos
brew install ansible ansible-lint ansible-galaxy
# windows
choco install ansible ansible-lint ansible-galaxy

Other roles:

ansible-galaxy collection install -r requirements.yml

Usage

If you have a password on your ssh key --ask-pass is recommended, --ask-become-pass is always asked in these roles, as most tasks require elevated privileges. These are dropped time to time when the default user privilege is enough.

ansible-playbook -i inventory/hosts.yml playbook.yml \
--ask-pass \
--ask-become-pass

You can also call you ssh agent to unlock your key prior to simplify your calls:

ssh-add ~/.ssh/my_key
# unlock it
ansible-playbook -i inventory/hosts.yml playbook.yml \
--ask-become-pass

Target configuration

Requirements:

• sshd up and running
• public key copied:

ssh-copy-id -i ~/.ssh/id_rsa.pub username@remote_host

• python3 installed (pacman -Syu python3)

Developping

Linting:

ansible-lint
npx prettier --write .