Application Deployer

Ansible playbooks that deploy and configure the home-lab's self-hosted services across a cluster of Linux servers: media servers, file sync, VPN, encrypted storage, NFS, and Restic backups. Every secret comes from the Vault KV store over mTLS.

The playbooks run Ansible (pinned in pyproject.toml) under Python managed by uv, with this repo's own plugins and modules in filter_plugins/, lookup_plugins/, action_plugins/, and library/. Most services run as Docker containers, managed over each host's Docker TLS socket; Nextcloud's web stack, Samba, WireGuard, and NordVPN run directly on the host. Storage is LUKS-encrypted disks, NFS, and MinIO S3.

Quick start

# Set required environment variables
export CS_PROJECT_CODE="<project-code>"
export DEVOPS_SERVER_INVENTORY_HOSTNAME="<devops-server-inventory-hostname>"
export VAULT_API_ENDPOINT="https://<host>:8083"
export VAULT_API_KEY="<api-key>"
export VAULT_CA_CERT_BASE64="<base64-encoded-ca-cert>"
export VAULT_CLIENT_CERT_BASE64="<base64-encoded-client-cert>"
export VAULT_CLIENT_KEY_BASE64="<base64-encoded-client-key>"

# Install dependencies
uv sync --all-extras --all-packages --no-progress
uv --offline run --no-sync --no-progress ansible-galaxy install -r requirements.yml

# Run a deployment (example: deploy Nextcloud).
uv --offline run --no-sync --no-progress ansible-playbook playbook.yml --tags nextcloud

Ordered services

Suggested deployment order; later rows may depend on earlier ones (e.g. nextcloud on postgres).

Service	Group	Description
Prerequisites	-	Set up the servers
Patching	patchservers	System updates, Docker, NFS, LUKS, SSH hardening (incl. Vault data source)
NordVPN	all:!localhost:!wireguard	VPN client with Meshnet networking (excluded from wireguard hosts)
MinIO S3	minio_community	Single-node object storage
Restic	restic	Backup repository, SFTP backend
Reverse Proxy	reverse_proxy	Caddy or Nginx Proxy Manager, selected by cs_rp_which_one
Wireguard	wireguard	VPN server
Samba	samba	SMB/CIFS file sharing
PostgreSQL	postgres	Database server (v18)
Nextcloud	nextcloud	File sync, office suite, media, collaboration
Emby	emby	Media server
Jellyfin	jellyfin	Media server
Navidrome	navidrome	Music server
qBittorrent Nox	qbittorrent_nox	Headless torrent client
Code Server	code_server	Browser-based VS Code
Vikunja	vikunja	Task management

Project structure

application-deployer/
├── playbook.yml                      # Main Ansible playbook
├── inventory.yml                     # Host inventory and variables
├── ansible.cfg                       # Ansible configuration
├── requirements.yml                  # Ansible collection dependencies
├── group_vars/                       # Per-group variable definitions
├── host_vars/                        # Per-host variable overrides
├── tasks/                            # Ansible task files per service
├── files/                            # Static files for deployment
├── templates/                        # Jinja2 templates
├── library/                          # Custom Ansible modules
├── filter_plugins/                   # Custom Ansible filter plugins
├── lookup_plugins/                   # Custom Ansible lookup plugins
├── action_plugins/                   # Custom Ansible action plugins
├── doc_fragments/                    # Shared Ansible documentation fragments
├── scripts/                          # Utility scripts
├── src/                              # Python package imported by the lookup and action plugins
├── .gitea/workflows/                 # CI workflows
└── docs/                             # Per-service documentation

Development

See DEVELOPMENT.md for installing dependencies, the git hook, and linting.