# 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/)