Initial template repository
🎬 ARR Suite Template Bootstrap - Complete Media Automation Stack Features: - 16 production services (Prowlarr, Sonarr, Radarr, Plex, etc.) - One-command Ansible deployment - VPN-protected downloads via Gluetun - Tailscale secure access - Production-ready security (UFW, Fail2Ban) - Automated backups and monitoring - Comprehensive documentation Ready for customization and deployment to any VPS. Co-authored-by: openhands <openhands@all-hands.dev>
This commit is contained in:
openhands
311
TEMPLATE_SETUP.md
Normal file
311
TEMPLATE_SETUP.md
Normal file
@@ -0,0 +1,311 @@
|
||||
# 🎯 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!**
|
||||
Reference in New Issue
Block a user