arr-suite-template-bootstrap/TEMPLATE_SETUP.md

# 🎯 Template Setup Guide

> **Complete setup instructions for the ARR Suite Template Bootstrap**

This guide will walk you through customizing and deploying this template for your own VPS.

## 🚀 **Quick Setup (5 Minutes)**

### **Step 1: Clone and Prepare**
```bash
git clone <your-repo-url> my-arr-suite
cd my-arr-suite
```

### **Step 2: Configure Your VPS**
Edit `inventory/production.yml`:
```yaml
all:
  children:
    arrs_servers:
      hosts:
        your-vps:
          ansible_host: YOUR_VPS_IP_ADDRESS        # ← Your VPS IP
          ansible_user: root                       # ← Your SSH user
          ansible_ssh_private_key_file: ~/.ssh/your_private_key  # ← Your SSH key
          ansible_ssh_common_args: '-o StrictHostKeyChecking=no'
          tailscale_ip: YOUR_TAILSCALE_IP_ADDRESS  # ← Optional: Tailscale IP
```

### **Step 3: Set Up Secrets**
```bash
# Copy the vault template
cp group_vars/all/vault.yml.example group_vars/all/vault.yml

# Encrypt it (you'll set a password)
ansible-vault encrypt group_vars/all/vault.yml

# Edit your secrets
ansible-vault edit group_vars/all/vault.yml
```

**Required secrets to configure:**
```yaml
# VPN Credentials (REQUIRED)
vault_vpn_provider: "nordvpn"           # Your VPN provider
vault_vpn_username: "your_username"     # Your VPN username  
vault_vpn_password: "your_password"     # Your VPN password

# Optional: Indexer credentials
vault_nzbgeek_api_key: "your_api_key"
vault_nzbgeek_username: "your_username"

# Optional: Usenet provider
vault_usenet_provider_host: "news.your-provider.com"
vault_usenet_provider_username: "your_username"
vault_usenet_provider_password: "your_password"
```

### **Step 4: Deploy**
```bash
# Deploy everything
ansible-playbook -i inventory/production.yml ansible-deployment.yml

# Or use the helper script
./deploy.sh
```

## 🔧 **Detailed Configuration**

### **VPN Provider Setup**

#### **NordVPN**
```yaml
vault_vpn_provider: "nordvpn"
vault_vpn_username: "your_nordvpn_email"
vault_vpn_password: "your_nordvpn_password"
```

#### **Surfshark**
```yaml
vault_vpn_provider: "surfshark"
vault_vpn_username: "your_surfshark_username"
vault_vpn_password: "your_surfshark_password"
```

#### **ExpressVPN**
```yaml
vault_vpn_provider: "expressvpn"
vault_vpn_username: "your_expressvpn_username"
vault_vpn_password: "your_expressvpn_password"
```

### **Optional Services Configuration**

Edit `ansible-deployment.yml` to enable/disable services:

```yaml
# Service toggles
enable_whisparr: false          # Adult content automation
enable_tailscale: true          # Secure remote access
enable_plex_claim: false        # Auto Plex setup
enable_backup_system: true     # Automated backups
enable_monitoring: true        # Health monitoring
```

### **Resource Customization**

Adjust resource limits in `ansible-deployment.yml`:

```yaml
# Docker resource limits
docker_memory_limit: "2g"       # Per container memory limit
docker_cpu_limit: "1.0"        # Per container CPU limit

# Storage paths
media_root: "/home/docker/media"
downloads_root: "/home/docker/downloads"
config_root: "/home/docker"
```

## 🌐 **Domain & SSL Setup (Optional)**

### **Custom Domain Configuration**
```yaml
# In vault.yml
vault_domain: "yourdomain.com"
vault_ssl_email: "you@yourdomain.com"
vault_cloudflare_api_token: "your_cloudflare_token"  # If using Cloudflare
```

### **Reverse Proxy Setup**
The template includes Traefik configuration for SSL:
```yaml
# Enable reverse proxy
enable_traefik: true
enable_ssl: true
```

## 🔐 **Security Customization**

### **SSH Key Setup**
```bash
# Generate SSH key if you don't have one
ssh-keygen -t ed25519 -f ~/.ssh/arr_suite_key -C "arr-suite-deployment"

# Copy to your VPS
ssh-copy-id -i ~/.ssh/arr_suite_key.pub root@YOUR_VPS_IP

# Update inventory with key path
ansible_ssh_private_key_file: ~/.ssh/arr_suite_key
```

### **Tailscale Setup (Recommended)**
```bash
# Install Tailscale on your local machine
curl -fsSL https://tailscale.com/install.sh | sh

# Get your Tailscale auth key
tailscale up
# Visit the URL to authenticate

# Add auth key to vault.yml
vault_tailscale_auth_key: "tskey-auth-your-key-here"
```

## 📊 **Post-Deployment Configuration**

### **1. Access Your Services**
After deployment, services will be available at:
```
http://YOUR_VPS_IP:9696  - Prowlarr
http://YOUR_VPS_IP:8989  - Sonarr  
http://YOUR_VPS_IP:7878  - Radarr
http://YOUR_VPS_IP:8686  - Lidarr
http://YOUR_VPS_IP:6767  - Bazarr
http://YOUR_VPS_IP:5055  - Jellyseerr
http://YOUR_VPS_IP:8080  - SABnzbd
http://YOUR_VPS_IP:8112  - Deluge
http://YOUR_VPS_IP:32400 - Plex
http://YOUR_VPS_IP:8181  - Tautulli
```

### **2. Configure Indexers in Prowlarr**
1. Access Prowlarr at `http://YOUR_VPS_IP:9696`
2. Go to Settings → Indexers
3. Add your indexers (NZBgeek, NZBHydra2, etc.)
4. Test connections

### **3. Connect Applications**
1. In Prowlarr → Settings → Apps
2. Add each application:
   - **Sonarr**: `http://sonarr:8989`
   - **Radarr**: `http://radarr:7878`
   - **Lidarr**: `http://lidarr:8686`
   - **Bazarr**: `http://bazarr:6767`

### **4. Setup Download Clients**
In each *arr application:
1. Go to Settings → Download Clients
2. Add SABnzbd: `http://gluetun:8080`
3. Add Deluge: `http://gluetun:8112`

### **5. Configure Plex**
1. Access Plex at `http://YOUR_VPS_IP:32400`
2. Complete initial setup
3. Add libraries:
   - Movies: `/media/movies`
   - TV Shows: `/media/tv`
   - Music: `/media/music`

## 🛠️ **Customization Examples**

### **Add Custom Service**
1. Create `compose/my-service.yml`:
```yaml
services:
  my-service:
    image: my-service:latest
    container_name: my-service
    ports:
      - "8090:8090"
    volumes:
      - ./my-service:/config
    restart: unless-stopped
```

2. Add to `ansible-deployment.yml`:
```yaml
- name: Deploy my custom service
  docker_compose:
    project_src: "{{ docker_dir }}/compose"
    files:
      - docker-compose-vpn.yml
      - my-service.yml
```

### **Custom Backup Schedule**
```yaml
# In ansible-deployment.yml
backup_schedule: "0 2 * * *"  # Daily at 2 AM
backup_retention_days: 30     # Keep 30 days of backups
backup_encryption: true       # Encrypt backups
```

## 🔧 **Troubleshooting**

### **Common Issues**

#### **Ansible Connection Failed**
```bash
# Test SSH connection
ssh -i ~/.ssh/your_key root@YOUR_VPS_IP

# Check inventory syntax
ansible-inventory -i inventory/production.yml --list
```

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

# Test VPN connection
docker exec gluetun curl -s ifconfig.me
```

#### **Services Not Accessible**
```bash
# Check container status
docker ps

# Check firewall
sudo ufw status

# Check service logs
docker logs prowlarr
```

### **Useful Commands**
```bash
# Check deployment status
ansible-playbook -i inventory/production.yml ansible-deployment.yml --check

# Run specific tasks
ansible-playbook -i inventory/production.yml ansible-deployment.yml --tags "docker"

# View vault contents
ansible-vault view group_vars/all/vault.yml

# Edit vault
ansible-vault edit group_vars/all/vault.yml
```

## 📚 **Next Steps**

1. **Read the full documentation**: [ANSIBLE_DEPLOYMENT.md](ANSIBLE_DEPLOYMENT.md)
2. **Configure your indexers**: Add your favorite indexers to Prowlarr
3. **Set up automation**: Configure quality profiles and release profiles
4. **Add media**: Start adding movies and TV shows to your libraries
5. **Monitor performance**: Use Tautulli to monitor your Plex usage

## 🆘 **Getting Help**

- **Documentation**: Check the `docs/` directory
- **Troubleshooting**: See [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)
- **Community**: Join the discussion forums
- **Issues**: Report bugs in the issue tracker

---

**🎉 You're ready to deploy your own media automation empire!**