207 lines
4.8 KiB
Markdown
207 lines
4.8 KiB
Markdown
# 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/)
|