Sanitized mirror from private repository - 2026-03-24 12:49:25 UTC

docs/advanced/ansible/README.md

@@ -0,0 +1,206 @@
+# 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
+```bash
+pip install ansible
+```
+
+### Deploy Everything
+```bash
+cd ansible/homelab
+ansible-playbook site.yml
+```
+
+### Deploy to Specific Host
+```bash
+ansible-playbook site.yml --limit atlantis
+```
+
+### Deploy by Category
+```bash
+# Deploy all Synology hosts
+ansible-playbook site.yml --tags synology
+
+# Deploy all VMs
+ansible-playbook site.yml --tags vms
+```
+
+### Check Mode (Dry Run)
+```bash
+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:
+
+```bash
+# 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:
+
+```yaml
+# 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:
+   ```bash
+   python3 generate_playbooks.py
+   ```
+
+### Method 2: Manual addition
+1. Add service to `host_vars/<host>.yml`:
+   ```yaml
+   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:
+
+```bash
+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
+```bash
+ansible all -m ping
+```
+
+### Test specific host
+```bash
+ansible atlantis -m ping
+```
+
+### Verbose output
+```bash
+ansible-playbook site.yml -vvv
+```
+
+### List tasks without running
+```bash
+ansible-playbook site.yml --list-tasks
+```
+
+## 📚 Resources
+
+- [Ansible Documentation](https://docs.ansible.com/)
+- [Docker Compose Reference](https://docs.docker.com/compose/compose-file/)
+- [Tailscale Documentation](https://tailscale.com/kb/)