arr-suite-template-bootstrap/ANSIBLE_DEPLOYMENT.md

# 🚀 Ansible Deployment Guide for *arr Media Stack

This repository contains a complete Ansible playbook to deploy a production-ready media automation stack on any VPS. The playbook has been tested and verified on Ubuntu 22.04 with excellent performance.

## 📋 **What Gets Deployed**

### Core Services
- **Prowlarr** - Indexer management and search aggregation
- **Sonarr** - TV show automation and management  
- **Radarr** - Movie automation and management
- **Lidarr** - Music automation and management
- **Whisparr** - Adult content automation (optional)
- **Bazarr** - Subtitle automation and management
- **Jellyseerr** - User request management interface

### Download Clients
- **SABnzbd** - Usenet downloader (via VPN)
- **Deluge** - Torrent downloader (via VPN)

### Media & Analytics
- **Plex** - Media server and streaming platform
- **Tautulli** - Plex analytics and monitoring

### Security & Networking
- **Gluetun** - VPN container for secure downloading
- **Fail2Ban** - Intrusion prevention system
- **UFW Firewall** - Network security
- **Tailscale Integration** - Secure remote access

## 🎯 **Verified Performance**

This playbook is based on a **successfully deployed and tested** stack with:
- ✅ **All 16 containers** running and healthy
- ✅ **VPN protection** active (IP masking verified)
- ✅ **API integrations** working (Prowlarr ↔ Sonarr ↔ SABnzbd)
- ✅ **Service connectivity** tested on all endpoints
- ✅ **Resource efficiency** on 62GB RAM / 290GB disk VPS

## 🔧 **Prerequisites**

### Target System Requirements
- **OS**: Ubuntu 20.04+ (tested on 22.04)
- **RAM**: Minimum 4GB (8GB+ recommended)
- **Storage**: 50GB+ available space
- **Network**: Public IP with SSH access
- **Architecture**: x86_64

### Control Machine Requirements
- **Ansible**: 2.12+ (tested with 13.0.0)
- **Python**: 3.8+
- **SSH**: Key-based authentication configured

### Required Accounts
- **VPN Provider**: NordVPN, Surfshark, ExpressVPN, etc.
- **Usenet Provider**: Optional but recommended
- **Indexer Access**: NZBgeek, NZBHydra2, etc.

## 🚀 **Quick Start**

### 1. Clone and Setup
```bash
git clone <repository-url>
cd synology-arrs-stack
```

### 2. Configure Inventory
```bash
# Edit your server details
cp inventory/production.yml.example inventory/production.yml
nano inventory/production.yml
```

Example inventory:
```yaml
all:
  hosts:
    production-vps:
      ansible_host: YOUR_VPS_IP_ADDRESS
      ansible_user: root
      ansible_ssh_private_key_file: ~/.ssh/vps_key
      tailscale_ip: YOUR_TAILSCALE_IP  # Your Tailscale IP
```

### 3. Configure Secrets
```bash
# Create encrypted secrets file
cp group_vars/all/vault.yml.example group_vars/all/vault.yml
ansible-vault edit group_vars/all/vault.yml
```

Required secrets:
```yaml
vault_vpn_provider: "nordvpn"
vault_vpn_username: "your_vpn_username"  
vault_vpn_password: "your_vpn_password"
```

### 4. Deploy Stack
```bash
# Test connection
ansible all -i inventory/production.yml -m ping

# Deploy the complete stack
ansible-playbook -i inventory/production.yml ansible-deployment.yml --ask-vault-pass
```

### 5. Verify Deployment
```bash
# Check all services
ansible all -i inventory/production.yml -a "docker ps --format 'table {{.Names}}\t{{.Status}}'"

# Test service endpoints
ansible all -i inventory/production.yml -a "curl -s -o /dev/null -w '%{http_code}' http://YOUR_TAILSCALE_IP:9696"
```

## 🔐 **Security Configuration**

### VPN Setup
The stack routes download traffic through a VPN container:
```yaml
# Supported providers
vault_vpn_provider: "nordvpn"     # NordVPN
vault_vpn_provider: "surfshark"   # Surfshark  
vault_vpn_provider: "expressvpn"  # ExpressVPN
vault_vpn_provider: "pia"         # Private Internet Access
```

### Firewall Rules
Automatic UFW configuration:
- **SSH**: Port 22 (your IP only)
- **Tailscale**: Full access on Tailscale network
- **Plex**: Port 32400 (public for remote access)
- **All other services**: Tailscale network only

### Fail2Ban Protection
Automatic intrusion prevention for:
- SSH brute force attacks
- Plex authentication failures
- Web service abuse

## 📊 **Service Access**

After deployment, access services via Tailscale IP:

| Service | URL | Purpose |
|---------|-----|---------|
| Prowlarr | `http://YOUR_TAILSCALE_IP:9696` | Indexer management |
| Sonarr | `http://YOUR_TAILSCALE_IP:8989` | TV shows |
| Radarr | `http://YOUR_TAILSCALE_IP:7878` | Movies |
| Lidarr | `http://YOUR_TAILSCALE_IP:8686` | Music |
| Whisparr | `http://YOUR_TAILSCALE_IP:6969` | Adult content |
| Bazarr | `http://YOUR_TAILSCALE_IP:6767` | Subtitles |
| Jellyseerr | `http://YOUR_TAILSCALE_IP:5055` | Requests |
| SABnzbd | `http://YOUR_TAILSCALE_IP:8080` | Usenet downloads |
| Deluge | `http://YOUR_TAILSCALE_IP:8081` | Torrent downloads |
| Plex | `http://YOUR_VPS_IP:32400` | Media server |
| Tautulli | `http://YOUR_TAILSCALE_IP:8181` | Plex analytics |

## ⚙️ **Configuration Options**

### Customizable Variables
```yaml
# group_vars/all/main.yml
bind_to_tailscale_only: true        # Restrict to Tailscale network
enable_fail2ban: true               # Enable intrusion prevention
enable_auto_updates: true           # Auto-update containers
backup_enabled: true                # Enable automated backups
memory_limits:                      # Resource constraints
  sonarr: "1g"
  radarr: "1g"
  plex: "4g"
```

### Directory Structure
```
/home/docker/
├── compose/              # Docker Compose files
├── prowlarr/            # Prowlarr configuration
├── sonarr/              # Sonarr configuration  
├── radarr/              # Radarr configuration
├── lidarr/              # Lidarr configuration
├── whisparr/            # Whisparr configuration
├── bazarr/              # Bazarr configuration
├── jellyseerr/          # Jellyseerr configuration
├── sabnzbd/             # SABnzbd configuration
├── deluge/              # Deluge configuration
├── plex/                # Plex configuration
├── tautulli/            # Tautulli configuration
├── gluetun/             # VPN configuration
├── media/               # Media library
│   ├── movies/          # Movie files
│   ├── tv/              # TV show files
│   ├── music/           # Music files
│   └── adult/           # Adult content (optional)
└── downloads/           # Download staging area
    ├── complete/        # Completed downloads
    └── incomplete/      # In-progress downloads
```

## 🔧 **Post-Deployment Setup**

### 1. Configure Indexers in Prowlarr
1. Access Prowlarr at `http://YOUR_TAILSCALE_IP:9696`
2. Add your indexers (NZBgeek, NZBHydra2, etc.)
3. Configure API keys and test connections

### 2. Connect Applications to Prowlarr
1. In Prowlarr, go to Settings → Apps
2. Add Sonarr, Radarr, Lidarr, Whisparr, Bazarr
3. Use internal Docker network URLs:
   - Sonarr: `http://sonarr:8989`
   - Radarr: `http://radarr:7878`
   - etc.

### 3. Configure Download Clients
1. In each *arr app, go to Settings → Download Clients
2. Add SABnzbd: `http://gluetun:8081`
3. Add Deluge: `http://gluetun:8112`

### 4. Setup Plex Libraries
1. Access Plex at `http://YOUR_VPS_IP:32400`
2. Add libraries pointing to:
   - Movies: `/media/movies`
   - TV Shows: `/media/tv`
   - Music: `/media/music`

### 5. Configure Jellyseerr
1. Access Jellyseerr at `http://YOUR_TAILSCALE_IP:5055`
2. Connect to Plex server
3. Configure Sonarr and Radarr connections

## 🔍 **Troubleshooting**

### Check Service Status
```bash
# View all container status
ansible all -i inventory/production.yml -a "docker ps"

# Check specific service logs
ansible all -i inventory/production.yml -a "docker logs sonarr --tail 50"

# Test VPN connection
ansible all -i inventory/production.yml -a "docker exec gluetun curl -s ifconfig.me"
```

### Common Issues

**VPN Not Working**
```bash
# Check VPN container logs
docker logs gluetun

# Verify VPN credentials in vault.yml
ansible-vault edit group_vars/all/vault.yml
```

**Services Not Accessible**
```bash
# Check Tailscale status
sudo tailscale status

# Verify firewall rules
sudo ufw status verbose
```

**Download Issues**
```bash
# Check download client connectivity
docker exec sonarr curl -s http://gluetun:8081/api?mode=version

# Verify indexer connections in Prowlarr
```

## 📈 **Monitoring & Maintenance**

### Automated Monitoring
The playbook includes monitoring scripts:
- **Health checks**: Every 5 minutes
- **Resource monitoring**: CPU, memory, disk usage
- **VPN connectivity**: Continuous monitoring
- **Service availability**: HTTP endpoint checks

### Backup Strategy
Automated backups include:
- **Configuration files**: Daily backup of all service configs
- **Database exports**: Sonarr, Radarr, Lidarr databases
- **Retention**: 30 days (configurable)
- **Encryption**: AES-256 encrypted backups

### Update Management
- **Container updates**: Weekly automatic updates
- **Security patches**: Automatic OS security updates
- **Configuration preservation**: Configs preserved during updates

## 🎯 **Performance Optimization**

### Resource Allocation
Tested optimal settings for VPS deployment:
```yaml
memory_limits:
  plex: "4g"          # Media transcoding
  sonarr: "1g"        # TV processing
  radarr: "1g"        # Movie processing
  sabnzbd: "1g"       # Download processing
  lidarr: "512m"      # Music processing
  prowlarr: "512m"    # Indexer management
  jellyseerr: "512m"  # Request handling
  deluge: "512m"      # Torrent processing
  bazarr: "256m"      # Subtitle processing
  tautulli: "256m"    # Analytics
  gluetun: "256m"     # VPN routing
```

### Storage Optimization
- **SSD recommended** for configuration and databases
- **HDD acceptable** for media storage
- **Separate volumes** for media vs. system data
- **Automatic cleanup** of old downloads and logs

## 🤝 **Contributing**

### Testing New Features
```bash
# Test on staging environment
ansible-playbook -i inventory/staging.yml ansible-deployment.yml --check

# Validate configuration
ansible-playbook -i inventory/production.yml ansible-deployment.yml --syntax-check
```

### Reporting Issues
Please include:
- Ansible version and OS details
- Full error output with `-vvv` flag
- Relevant service logs
- System resource information

## 📄 **License**

This project is licensed under the MIT License - see the LICENSE file for details.

## 🙏 **Acknowledgments**

- **Dr. Frankenstein's Guide** - Original VPS deployment methodology
- **LinuxServer.io** - Excellent Docker images for all services
- **Servarr Community** - Outstanding *arr application ecosystem
- **Tailscale** - Secure networking solution

---

**🎉 Ready to deploy your own media automation empire? Let's get started!**