homelab-optimized/ansible/homelab/README.md

Homelab Ansible Playbooks

Automated deployment and management of all homelab services across all hosts.

📁 Directory Structure

ansible/homelab/
├── ansible.cfg           # Ansible configuration
├── inventory.yml         # All hosts inventory
├── site.yml              # Master playbook
├── generate_playbooks.py # Script to regenerate playbooks from compose files
├── group_vars/           # Variables by group
│   ├── all.yml           # Global variables
│   ├── synology.yml      # Synology NAS specific
│   └── vms.yml           # Virtual machines specific
├── host_vars/            # Variables per host (auto-generated)
│   ├── atlantis.yml      # 53 services
│   ├── calypso.yml       # 24 services
│   ├── homelab_vm.yml    # 33 services
│   └── ...
├── playbooks/            # Individual playbooks
│   ├── common/           # Shared playbooks
│   │   ├── install_docker.yml
│   │   └── setup_directories.yml
│   ├── deploy_atlantis.yml
│   ├── deploy_calypso.yml
│   └── ...
└── roles/                # Reusable roles
    ├── docker_stack/     # Deploy docker-compose stacks
    └── directory_setup/  # Create directory structures

🚀 Quick Start

Prerequisites

• Ansible 2.12+
• SSH access to all hosts (via Tailscale)
• Python 3.8+

Installation

pip install ansible

Deploy Everything

cd ansible/homelab
ansible-playbook site.yml

Deploy to Specific Host

ansible-playbook site.yml --limit atlantis

Deploy by Category

# Deploy all Synology hosts
ansible-playbook site.yml --tags synology

# Deploy all VMs
ansible-playbook site.yml --tags vms

Check Mode (Dry Run)

ansible-playbook site.yml --check --diff

📋 Host Inventory

Host	Category	Services	Description
atlantis	synology	53	Primary NAS (DS1823xs+)
calypso	synology	24	Secondary NAS (DS920+)
setillo	synology	2	Remote NAS
guava	physical	8	TrueNAS Scale
concord_nuc	physical	11	Intel NUC
homelab_vm	vms	33	Primary VM
rpi5_vish	edge	3	Raspberry Pi 5

🔧 Configuration

Vault Secrets

Sensitive data should be stored in Ansible Vault:

# Create vault password file (DO NOT commit this)
echo "your-vault-password" > .vault_pass

# Encrypt a variable
ansible-vault encrypt_string 'my-secret' --name 'api_key'

# Run playbook with vault
ansible-playbook site.yml --vault-password-file .vault_pass

Environment Variables

Create a .env file for each service or use host_vars:

# host_vars/atlantis.yml
vault_plex_claim_token: !vault |
  $ANSIBLE_VAULT;1.1;AES256
  ...

📝 Adding New Services

Method 1: Add docker-compose file

1. Add your docker-compose.yml to hosts/<category>/<host>/<service>/
2. Run the generator:

   python3 generate_playbooks.py
   

Method 2: Manual addition

1. Add service to host_vars/<host>.yml:

   host_services:
     - name: my_service
       stack_dir: my_service
       compose_file: hosts/synology/atlantis/my_service.yaml
       enabled: true
   

🏷️ Tags

Tag	Description
synology	All Synology NAS hosts
vms	All virtual machines
physical	Physical servers
edge	Edge devices (RPi, etc.)
arr-suite	Media management (Sonarr, Radarr, etc.)
monitoring	Prometheus, Grafana, etc.

📊 Service Categories

Media & Entertainment

• Plex, Jellyfin, Tautulli
• Sonarr, Radarr, Lidarr, Prowlarr
• Jellyseerr, Overseerr

Productivity

• Paperless-ngx, Stirling PDF
• Joplin, Dokuwiki
• Syncthing

Infrastructure

• Nginx Proxy Manager
• Traefik, Cloudflare Tunnel
• AdGuard Home, Pi-hole

Monitoring

• Prometheus, Grafana
• Uptime Kuma, Dozzle
• Node Exporter

Security

• Vaultwarden
• Authentik
• Headscale

🔄 Regenerating Playbooks

If you modify docker-compose files directly:

python3 generate_playbooks.py

This will:

1. Scan all hosts/ directories for compose files
2. Update host_vars/ with service lists
3. Regenerate individual host playbooks
4. Update the master site.yml

🐛 Troubleshooting

Test connectivity

ansible all -m ping

Test specific host

ansible atlantis -m ping

Verbose output

ansible-playbook site.yml -vvv

List tasks without running

ansible-playbook site.yml --list-tasks

📚 Resources

• Ansible Documentation
• Docker Compose Reference
• Tailscale Documentation