Merge pull request #5 from brianpooe/claude/improve-docker-compose-01CGxwFACQSqcPVmtuHmWfoT
docs: reorganize documentation and add recyclarr config template
This commit is contained in:
GitHub
commit
5b353b73fa
6 changed files with 968 additions and 80 deletions
520
README.md
520
README.md
|
|
@ -1,124 +1,484 @@
|
|||
# Homelab
|
||||
# Synology Docker Services
|
||||
|
||||
# Synology arr stack installation guide
|
||||
### [TRaSH Guides](https://trash-guides.info/File-and-Folder-Structure/How-to-set-up/Synology/)
|
||||
Production-ready Docker Compose templates for Synology NAS, featuring security best practices, resource management, and comprehensive health monitoring.
|
||||
|
||||
# Recyclarr installation guide
|
||||
#### Recyclarr is a command-line application that will automatically synchronize recommended settings from the TRaSH guides to your Sonarr/Radarr instances.
|
||||
### [Recyclarr Wiki](https://wiki.serversatho.me/en/Recyclarr)
|
||||
|
||||
## Pgadmin permissions issue
|
||||
```shell
|
||||
chown -R 5050:5050 /volume1/docker/appdata/pgadmin
|
||||
```
|
||||
|
||||
## [Connect vault to postgres database](https://developer.hashicorp.com/vault/docs/configuration/storage/postgresql)
|
||||
|
||||
## Caddyfile
|
||||
### paperless-ngx config
|
||||
If you've installed **Paperless-ngx** directly in a Proxmox LXC container, the key considerations remain similar but with slightly adjusted setup.
|
||||
|
||||
Here's a clear step-by-step fix for the **CSRF error (403)** when using Paperless-ngx directly installed in an LXC behind **Caddy**:
|
||||
|
||||
---
|
||||
|
||||
### ✅ **1. Confirm Paperless Configuration (`paperless.conf` or `.env`):**
|
||||
|
||||
Inside your LXC container, Paperless needs explicit trust for the domain:
|
||||
## 🚀 Quick Start
|
||||
|
||||
```bash
|
||||
sudo nano /etc/paperless.conf
|
||||
# 1. Clone the repository
|
||||
git clone https://github.com/brianpooe/synology-docker-services.git
|
||||
cd synology-docker-services
|
||||
|
||||
# 2. Copy and configure environment
|
||||
cp .env.sample .env
|
||||
nano .env # Fill in your configuration
|
||||
|
||||
# 3. Generate Docker Compose files
|
||||
./substitute_env.sh docker-compose-files/arr-stack_template.yaml docker-compose.arr-stack.yml
|
||||
./substitute_env.sh docker-compose-files/postgres_template.yaml docker-compose.postgres.yml
|
||||
./substitute_env.sh docker-compose-files/vault_template.yaml docker-compose.vault.yml
|
||||
|
||||
# 4. Deploy
|
||||
docker-compose -f docker-compose.arr-stack.yml up -d
|
||||
docker-compose -f docker-compose.postgres.yml up -d
|
||||
docker-compose -f docker-compose.vault.yml up -d
|
||||
```
|
||||
|
||||
Ensure you have:
|
||||
|
||||
```env
|
||||
PAPERLESS_URL=https://paperless.example.com
|
||||
PAPERLESS_ALLOWED_HOSTS=paperless.example.com
|
||||
PAPERLESS_CSRF_TRUSTED_ORIGINS=https://paperless.example.com
|
||||
```
|
||||
|
||||
Replace `paperless.example.com` with your actual domain.
|
||||
|
||||
---
|
||||
|
||||
### ✅ **2. Adjust Django Settings (if custom):**
|
||||
## 📦 Available Stacks
|
||||
|
||||
Usually, Paperless-ngx includes these settings automatically, but you can explicitly verify:
|
||||
### 🎬 Media Stack (`arr-stack_template.yaml`)
|
||||
Complete automated media management with VPN protection and socket-proxy security.
|
||||
|
||||
* Ensure settings reflect headers forwarded by Caddy:
|
||||
**Services:**
|
||||
- **Socket-Proxy** - Secure Docker API gateway ✅ *NEW*
|
||||
- **Gluetun** - VPN container (WireGuard/OpenVPN)
|
||||
- **qBittorrent** - Torrent client (through VPN)
|
||||
- **SABnzbd** - Usenet client (through VPN)
|
||||
- **Prowlarr** - Indexer manager
|
||||
- **Radarr** - Movie collection manager
|
||||
- **Sonarr** - TV series collection manager
|
||||
- **Bazarr** - Subtitle manager
|
||||
- **Emby** - Media server
|
||||
- **Jellyseerr** - Request management
|
||||
- **FlareSolverr** - Captcha solver
|
||||
- **Recyclarr** - Quality profile sync (TRaSH Guides)
|
||||
- **Watchtower** - Automatic container updates (via socket-proxy)
|
||||
|
||||
```env
|
||||
PAPERLESS_FORCE_SCRIPT_NAME=/
|
||||
```
|
||||
**Features:**
|
||||
- ✅ VPN kill-switch for download clients
|
||||
- ✅ Socket-proxy for secure Docker API access
|
||||
- ✅ Health checks and dependency management
|
||||
- ✅ Resource limits to prevent system exhaustion
|
||||
- ✅ Security hardening (no-new-privileges, internal networks)
|
||||
|
||||
*(Typically not required, but can help in edge cases.)*
|
||||
### 🗄️ Database Stack (`postgres_template.yaml`)
|
||||
PostgreSQL with pgAdmin web interface.
|
||||
|
||||
**Services:**
|
||||
- **PostgreSQL 17** - Alpine-based database
|
||||
- **pgAdmin 4** - Web-based administration
|
||||
|
||||
**Features:**
|
||||
- ✅ Health-aware dependency management
|
||||
- ✅ Automated backups ready
|
||||
- ✅ Resource limits configured
|
||||
- ✅ Persistent data volumes
|
||||
|
||||
### 🔐 Secrets Stack (`vault_template.yaml`)
|
||||
HashiCorp Vault for secrets management.
|
||||
|
||||
**Services:**
|
||||
- **Vault 1.19.2** - Secrets management
|
||||
|
||||
**Features:**
|
||||
- ✅ Production-ready configuration
|
||||
- ✅ Watchtower disabled for stability
|
||||
- ✅ IPC_LOCK capability for security
|
||||
- ✅ Health monitoring
|
||||
|
||||
---
|
||||
|
||||
### ✅ **3. Proper Caddyfile Configuration:**
|
||||
## 🔒 Security Features
|
||||
|
||||
Your Caddyfile should explicitly forward crucial headers correctly:
|
||||
### Socket-Proxy Integration
|
||||
All media stack services use socket-proxy for restricted Docker API access:
|
||||
|
||||
```caddy
|
||||
paperless.example.com {
|
||||
reverse_proxy localhost:8000 {
|
||||
header_up Host {host}
|
||||
header_up X-Forwarded-Proto https
|
||||
header_up X-Real-IP {remote_host}
|
||||
header_up X-Forwarded-For {remote_host}
|
||||
}
|
||||
| Feature | Traditional | With Socket-Proxy |
|
||||
|---------|------------|-------------------|
|
||||
| Docker Socket Access | Full R/W | Restricted API endpoints |
|
||||
| Exec in Containers | ✅ Possible | ❌ Blocked |
|
||||
| Access Secrets | ✅ Possible | ❌ Blocked |
|
||||
| Manage Volumes | ✅ Possible | ❌ Blocked |
|
||||
| Attack Surface | 100% | ~10% |
|
||||
|
||||
header {
|
||||
Strict-Transport-Security "max-age=31536000; includeSubDomains"
|
||||
Referrer-Policy same-origin
|
||||
X-Content-Type-Options nosniff
|
||||
}
|
||||
**See:** [docs/SOCKET_PROXY.md](docs/SOCKET_PROXY.md) for details
|
||||
|
||||
encode gzip
|
||||
}
|
||||
```
|
||||
|
||||
Make sure the port (`8000`) matches the port your Paperless-ngx instance runs on inside your LXC container.
|
||||
### Additional Security
|
||||
- **No-new-privileges** on all containers
|
||||
- **Read-only filesystems** where applicable
|
||||
- **Internal networks** for service isolation
|
||||
- **Resource limits** to prevent DoS
|
||||
- **Health checks** for reliability
|
||||
- **Watchtower scoping** to limit auto-update scope
|
||||
|
||||
---
|
||||
|
||||
### ✅ **4. Ensure Paperless is aware of Proxy Headers:**
|
||||
## 📋 Prerequisites
|
||||
|
||||
Make sure the Gunicorn or the internal server running Paperless is aware it's behind a reverse proxy:
|
||||
### Required
|
||||
- Synology NAS with DSM 7.x
|
||||
- Docker & Docker Compose installed via Package Center
|
||||
- SSH access enabled
|
||||
- Basic knowledge of Docker and command line
|
||||
|
||||
If using Gunicorn explicitly, run with:
|
||||
### Recommended
|
||||
- Static IP for your NAS
|
||||
- Domain name for reverse proxy (optional)
|
||||
- VPN subscription for Gluetun (AirVPN, Mullvad, etc.)
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ Configuration
|
||||
|
||||
### 1. Environment Variables
|
||||
|
||||
Edit `.env` file with your settings:
|
||||
|
||||
```bash
|
||||
gunicorn paperless.asgi:application --bind 0.0.0.0:8000 --forwarded-allow-ips="*"
|
||||
# System Settings
|
||||
DOCKERCONFDIR=/volume1/docker/appdata
|
||||
DOCKERSTORAGEDIR=/volume1/data
|
||||
PUID=1026
|
||||
PGID=100
|
||||
TZ=Africa/Johannesburg
|
||||
|
||||
# Docker Logging
|
||||
DOCKERLOGGING_MAXFILE=3
|
||||
DOCKERLOGGING_MAXSIZE=10m
|
||||
|
||||
# Watchtower (optional)
|
||||
WATCHTOWER_SCHEDULE=0 0 4 * * *
|
||||
WATCHTOWER_NOTIFICATION_URL=
|
||||
WATCHTOWER_SCOPE=
|
||||
WATCHTOWER_LABEL_ENABLE=
|
||||
|
||||
# VPN Configuration
|
||||
VPN_SERVICE_PROVIDER=airvpn
|
||||
WIREGUARD_PRIVATE_KEY=your_private_key
|
||||
WIREGUARD_PRESHARED_KEY=your_preshared_key
|
||||
WIREGUARD_ADDRESSES=10.x.x.x/32
|
||||
FIREWALL_VPN_INPUT_PORTS=12345
|
||||
SERVER_COUNTRIES=Netherlands
|
||||
|
||||
# Database
|
||||
POSTGRES_USER=postgres
|
||||
POSTGRES_PASSWORD=strong_password
|
||||
POSTGRES_DB=maindb
|
||||
PGADMIN_EMAIL=admin@example.com
|
||||
PGADMIN_PASSWORD=strong_password
|
||||
```
|
||||
|
||||
*If Paperless runs through systemd, you can modify its startup parameters accordingly.*
|
||||
**Get your PUID/PGID:**
|
||||
```bash
|
||||
ssh admin@synology-nas
|
||||
id $USER
|
||||
```
|
||||
|
||||
---
|
||||
### 2. Recyclarr Configuration
|
||||
|
||||
### ✅ **5. Restart everything:**
|
||||
|
||||
Inside your LXC container:
|
||||
Copy and configure Recyclarr for quality profile management:
|
||||
|
||||
```bash
|
||||
sudo systemctl restart paperless
|
||||
# Copy template
|
||||
cp RECYCLARR_CONFIG_TEMPLATE.yml /volume1/docker/appdata/recyclarr/recyclarr.yml
|
||||
|
||||
# Edit with your API keys
|
||||
nano /volume1/docker/appdata/recyclarr/recyclarr.yml
|
||||
```
|
||||
|
||||
Outside, reload Caddy to ensure config is active:
|
||||
**Get API Keys:**
|
||||
- **Sonarr:** Settings → General → Security → API Key
|
||||
- **Radarr:** Settings → General → Security → API Key
|
||||
|
||||
**Important:** Use service names (`http://sonarr:8989`), NOT `localhost`!
|
||||
|
||||
### 3. Directory Structure
|
||||
|
||||
Create required directories:
|
||||
|
||||
```bash
|
||||
sudo caddy reload
|
||||
# Config directories
|
||||
sudo mkdir -p /volume1/docker/appdata/{gluetun,qbittorrent,sabnzbd,prowlarr,radarr,sonarr,bazarr,emby,jellyseerr,recyclarr,postgres,pgadmin,vault}
|
||||
|
||||
# Storage directories
|
||||
sudo mkdir -p /volume1/data/{torrents,usenet,media}/{movies,tv,music}
|
||||
sudo mkdir -p /volume1/docker/appdata/postgres/{data,backups}
|
||||
|
||||
# Set permissions
|
||||
sudo chown -R $PUID:$PGID /volume1/docker/appdata
|
||||
sudo chown -R $PUID:$PGID /volume1/data
|
||||
|
||||
# Special: pgAdmin needs specific user
|
||||
sudo chown -R 5050:5050 /volume1/docker/appdata/pgadmin
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### ⚠️ **Testing:**
|
||||
## 🚀 Deployment
|
||||
|
||||
* Clear your browser cache or use incognito mode.
|
||||
* Open `https://paperless.example.com`.
|
||||
* Attempt login again.
|
||||
### Option 1: Deploy All Stacks
|
||||
```bash
|
||||
./substitute_env.sh docker-compose-files/arr-stack_template.yaml docker-compose.arr-stack.yml
|
||||
./substitute_env.sh docker-compose-files/postgres_template.yaml docker-compose.postgres.yml
|
||||
./substitute_env.sh docker-compose-files/vault_template.yaml docker-compose.vault.yml
|
||||
|
||||
docker-compose -f docker-compose.arr-stack.yml up -d
|
||||
docker-compose -f docker-compose.postgres.yml up -d
|
||||
docker-compose -f docker-compose.vault.yml up -d
|
||||
```
|
||||
|
||||
### Option 2: Deploy Specific Stack
|
||||
```bash
|
||||
# Media stack only
|
||||
./substitute_env.sh docker-compose-files/arr-stack_template.yaml docker-compose.arr-stack.yml
|
||||
docker-compose -f docker-compose.arr-stack.yml up -d
|
||||
|
||||
# Verify deployment
|
||||
docker ps
|
||||
docker logs -f watchtower
|
||||
```
|
||||
|
||||
### Option 3: Deploy Individual Services
|
||||
```bash
|
||||
# Start only specific services
|
||||
docker-compose -f docker-compose.arr-stack.yml up -d socket-proxy gluetun qbittorrent prowlarr radarr sonarr
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
Following these steps will resolve the CSRF errors occurring due to header misconfigurations between Caddy and Django (Paperless-ngx).
|
||||
## 🔍 Verification
|
||||
|
||||
### Check Service Health
|
||||
```bash
|
||||
# View all containers
|
||||
docker ps
|
||||
|
||||
# Check specific service logs
|
||||
docker logs socket-proxy
|
||||
docker logs watchtower
|
||||
docker logs gluetun
|
||||
|
||||
# Check health status
|
||||
docker inspect socket-proxy | grep -A 10 Health
|
||||
```
|
||||
|
||||
### Test Socket-Proxy Security
|
||||
```bash
|
||||
# Should work - Watchtower can list containers
|
||||
docker exec watchtower wget -qO- http://socket-proxy:2375/containers/json
|
||||
|
||||
# Should fail with 403 - exec is blocked
|
||||
docker exec watchtower wget -qO- http://socket-proxy:2375/containers/watchtower/exec
|
||||
```
|
||||
|
||||
### Test VPN Connection
|
||||
```bash
|
||||
# Check VPN is connected
|
||||
docker logs gluetun | grep "connected"
|
||||
|
||||
# Test qBittorrent is using VPN
|
||||
docker exec qbittorrent curl ifconfig.me
|
||||
# Should show VPN IP, not your real IP
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Resource Allocation
|
||||
|
||||
Total resources if all services running:
|
||||
|
||||
| Resource | Reserved | Limit | Notes |
|
||||
|----------|----------|-------|-------|
|
||||
| CPU | 4.6 cores | 19.5 cores | Adjust based on your NAS |
|
||||
| Memory | 4.44 GB | 18.75 GB | Minimum 8GB RAM recommended |
|
||||
|
||||
**Per-service limits configured to prevent resource exhaustion**
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Common Tasks
|
||||
|
||||
### Update Containers
|
||||
```bash
|
||||
# Automatic (via Watchtower)
|
||||
# Watchtower runs on schedule defined in WATCHTOWER_SCHEDULE
|
||||
|
||||
# Manual update
|
||||
docker-compose -f docker-compose.arr-stack.yml pull
|
||||
docker-compose -f docker-compose.arr-stack.yml up -d
|
||||
```
|
||||
|
||||
### View Logs
|
||||
```bash
|
||||
# Follow logs
|
||||
docker logs -f radarr
|
||||
|
||||
# Last 100 lines
|
||||
docker logs --tail 100 sonarr
|
||||
|
||||
# All services
|
||||
docker-compose -f docker-compose.arr-stack.yml logs -f
|
||||
```
|
||||
|
||||
### Restart Service
|
||||
```bash
|
||||
# Single service
|
||||
docker-compose -f docker-compose.arr-stack.yml restart radarr
|
||||
|
||||
# All services
|
||||
docker-compose -f docker-compose.arr-stack.yml restart
|
||||
```
|
||||
|
||||
### Stop/Start Stack
|
||||
```bash
|
||||
# Stop everything
|
||||
docker-compose -f docker-compose.arr-stack.yml down
|
||||
|
||||
# Start everything
|
||||
docker-compose -f docker-compose.arr-stack.yml up -d
|
||||
|
||||
# Stop but keep data
|
||||
docker-compose -f docker-compose.arr-stack.yml stop
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 Documentation
|
||||
|
||||
### Detailed Guides
|
||||
- **[Socket-Proxy Security](docs/SOCKET_PROXY.md)** - Docker API security implementation
|
||||
- **[Troubleshooting](docs/TROUBLESHOOTING.md)** - Common issues and solutions
|
||||
- **[Improvements Guide](docs/IMPROVEMENTS.md)** - What changed and why
|
||||
- **[Recyclarr Setup](docs/RECYCLARR.md)** - Quality profile configuration
|
||||
|
||||
### External Resources
|
||||
- **[TRaSH Guides](https://trash-guides.info/)** - File structure and quality profiles
|
||||
- **[Servarr Wiki](https://wiki.servarr.com/)** - Arr stack documentation
|
||||
- **[Gluetun Wiki](https://github.com/qdm12/gluetun-wiki)** - VPN configuration
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Troubleshooting
|
||||
|
||||
### Quick Diagnostics
|
||||
```bash
|
||||
# Check container status
|
||||
docker ps -a
|
||||
|
||||
# Check resource usage
|
||||
docker stats
|
||||
|
||||
# Check networks
|
||||
docker network ls
|
||||
docker network inspect vpn_network
|
||||
|
||||
# Validate compose file
|
||||
docker-compose -f docker-compose.arr-stack.yml config
|
||||
```
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### Recyclarr: "base_url must start with http"
|
||||
**Fix:** Use service names in recyclarr.yml:
|
||||
```yaml
|
||||
base_url: http://sonarr:8989 # ✅ Correct
|
||||
base_url: http://localhost:8989 # ❌ Wrong
|
||||
```
|
||||
|
||||
#### Watchtower: Cannot update containers
|
||||
**Fix:** Check socket-proxy is running:
|
||||
```bash
|
||||
docker logs socket-proxy
|
||||
docker logs watchtower
|
||||
```
|
||||
|
||||
#### qBittorrent: No connection
|
||||
**Fix:** Check Gluetun VPN is connected:
|
||||
```bash
|
||||
docker logs gluetun | grep -i "connected"
|
||||
```
|
||||
|
||||
**Full troubleshooting guide:** [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Migration from Old Setup
|
||||
|
||||
If upgrading from previous configurations:
|
||||
|
||||
1. **Backup everything:**
|
||||
```bash
|
||||
docker-compose down
|
||||
tar -czf docker-backup-$(date +%Y%m%d).tar.gz /volume1/docker/appdata
|
||||
```
|
||||
|
||||
2. **Regenerate compose files:**
|
||||
```bash
|
||||
./substitute_env.sh docker-compose-files/arr-stack_template.yaml docker-compose.arr-stack.yml
|
||||
```
|
||||
|
||||
3. **Review changes:**
|
||||
```bash
|
||||
docker-compose -f docker-compose.arr-stack.yml config
|
||||
```
|
||||
|
||||
4. **Deploy:**
|
||||
```bash
|
||||
docker-compose -f docker-compose.arr-stack.yml up -d
|
||||
```
|
||||
|
||||
**Migration guide:** [docs/IMPROVEMENTS.md](docs/IMPROVEMENTS.md)
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Best Practices
|
||||
|
||||
### Security
|
||||
- ✅ Use socket-proxy for Watchtower (enabled by default)
|
||||
- ✅ Enable Watchtower scoping to limit auto-updates
|
||||
- ✅ Never expose Watchtower to exclude critical services (Vault, databases)
|
||||
- ✅ Use strong passwords in `.env`
|
||||
- ✅ Never commit `.env` to git
|
||||
- ✅ Regularly update containers
|
||||
|
||||
### Performance
|
||||
- ✅ Adjust resource limits based on your NAS specs
|
||||
- ✅ Monitor with `docker stats`
|
||||
- ✅ Use SSD for Docker volumes if possible
|
||||
- ✅ Enable hardware transcoding in Emby/Jellyfin
|
||||
|
||||
### Maintenance
|
||||
- ✅ Regular backups of `/volume1/docker/appdata`
|
||||
- ✅ Monitor logs for errors
|
||||
- ✅ Test updates in staging before production
|
||||
- ✅ Document any custom configurations
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
Contributions welcome! Please:
|
||||
1. Fork the repository
|
||||
2. Create a feature branch
|
||||
3. Test your changes thoroughly
|
||||
4. Submit a pull request
|
||||
|
||||
---
|
||||
|
||||
## 📝 License
|
||||
|
||||
This project is provided as-is for personal and educational use.
|
||||
|
||||
---
|
||||
|
||||
## 🙏 Credits
|
||||
|
||||
- **[TRaSH Guides](https://trash-guides.info/)** - Quality profiles and best practices
|
||||
- **[Hotio](https://hotio.dev/)** - Excellent container images
|
||||
- **[LinuxServer.io](https://www.linuxserver.io/)** - Container images and documentation
|
||||
- **[Gluetun](https://github.com/qdm12/gluetun)** - VPN container
|
||||
|
||||
---
|
||||
|
||||
## 📧 Support
|
||||
|
||||
- **Issues:** [GitHub Issues](https://github.com/brianpooe/synology-docker-services/issues)
|
||||
- **Discussions:** [GitHub Discussions](https://github.com/brianpooe/synology-docker-services/discussions)
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2025-11-23
|
||||
**Version:** 2.0
|
||||
**Compatibility:** Synology DSM 7.x, Docker Compose 1.27.0+
|
||||
|
|
|
|||
116
RECYCLARR_CONFIG_TEMPLATE.yml
Normal file
116
RECYCLARR_CONFIG_TEMPLATE.yml
Normal file
|
|
@ -0,0 +1,116 @@
|
|||
# Recyclarr Configuration Template
|
||||
# This file should be copied to: {{DOCKERCONFDIR}}/recyclarr/recyclarr.yml
|
||||
# Replace {{SONARR_API_KEY}} and {{RADARR_API_KEY}} with your actual API keys
|
||||
|
||||
# IMPORTANT: Use Docker service names, NOT localhost!
|
||||
# - Use "http://sonarr:8989" not "http://localhost:8989"
|
||||
# - Use "http://radarr:7878" not "http://localhost:7878"
|
||||
|
||||
# How to get API keys:
|
||||
# Sonarr: Settings → General → Security → API Key
|
||||
# Radarr: Settings → General → Security → API Key
|
||||
|
||||
sonarr:
|
||||
web-1080p-v4:
|
||||
# Use Docker service name for proper container networking
|
||||
base_url: http://sonarr:8989
|
||||
api_key: {{SONARR_API_KEY}}
|
||||
delete_old_custom_formats: true
|
||||
replace_existing_custom_formats: true
|
||||
include:
|
||||
- template: sonarr-quality-definition-series
|
||||
- template: sonarr-v4-quality-profile-web-1080p
|
||||
- template: sonarr-v4-custom-formats-web-1080p
|
||||
|
||||
# Custom Formats
|
||||
custom_formats:
|
||||
# Optional - Uncomment to enable
|
||||
- trash_ids:
|
||||
- 32b367365729d530ca1c124a0b180c64 # Bad Dual Groups
|
||||
- 82d40da2bc6923f41e14394075dd4b03 # No-RlsGroup
|
||||
- e1a997ddb54e3ecbfe06341ad323c458 # Obfuscated
|
||||
- 06d66ab109d4d2eddb2794d21526d140 # Retags
|
||||
- 1b3994c551cbb92a2c781af061f4ab44 # Scene
|
||||
assign_scores_to:
|
||||
- name: WEB-1080p
|
||||
|
||||
web-2160p-v4:
|
||||
base_url: http://sonarr:8989
|
||||
api_key: {{SONARR_API_KEY}}
|
||||
delete_old_custom_formats: true
|
||||
replace_existing_custom_formats: true
|
||||
include:
|
||||
- template: sonarr-quality-definition-series
|
||||
- template: sonarr-v4-quality-profile-web-2160p
|
||||
- template: sonarr-v4-custom-formats-web-2160p
|
||||
|
||||
custom_formats:
|
||||
# HDR Formats
|
||||
- trash_ids:
|
||||
# Comment out if all devices are DV compatible
|
||||
- 9b27ab6498ec0f31a3353992e19434ca # DV (WEBDL)
|
||||
# Uncomment if devices support HDR10+
|
||||
# - 0dad0a507451acddd754fe6dc3a7f5e7 # HDR10Plus Boost
|
||||
assign_scores_to:
|
||||
- name: WEB-2160p
|
||||
|
||||
- trash_ids:
|
||||
- 32b367365729d530ca1c124a0b180c64 # Bad Dual Groups
|
||||
- 82d40da2bc6923f41e14394075dd4b03 # No-RlsGroup
|
||||
- e1a997ddb54e3ecbfe06341ad323c458 # Obfuscated
|
||||
- 06d66ab109d4d2eddb2794d21526d140 # Retags
|
||||
- 1b3994c551cbb92a2c781af061f4ab44 # Scene
|
||||
assign_scores_to:
|
||||
- name: WEB-2160p
|
||||
|
||||
radarr:
|
||||
uhd-bluray-web:
|
||||
# Use Docker service name for proper container networking
|
||||
base_url: http://radarr:7878
|
||||
api_key: {{RADARR_API_KEY}}
|
||||
delete_old_custom_formats: true
|
||||
replace_existing_custom_formats: true
|
||||
include:
|
||||
- template: radarr-quality-definition-movie
|
||||
- template: radarr-quality-profile-uhd-bluray-web
|
||||
- template: radarr-custom-formats-uhd-bluray-web
|
||||
|
||||
custom_formats:
|
||||
# Movie Versions
|
||||
- trash_ids:
|
||||
- 9f6cbff8cfe4ebbc1bde14c7b7bec0de # IMAX Enhanced
|
||||
assign_scores_to:
|
||||
- name: UHD Bluray + WEB
|
||||
# score: 0 # Uncomment to disable IMAX Enhanced priority
|
||||
|
||||
# Optional - DV settings
|
||||
- trash_ids:
|
||||
# Comment out if all devices are DV compatible
|
||||
- 923b6abef9b17f937fab56cfcf89e1f1 # DV (WEBDL)
|
||||
# Uncomment if devices support HDR10+
|
||||
# - b17886cb4158d9fea189859409975758 # HDR10Plus Boost
|
||||
assign_scores_to:
|
||||
- name: UHD Bluray + WEB
|
||||
|
||||
- trash_ids:
|
||||
- 9c38ebb7384dada637be8899efa68e6f # SDR
|
||||
assign_scores_to:
|
||||
- name: UHD Bluray + WEB
|
||||
# score: 0 # Uncomment to allow SDR releases
|
||||
|
||||
hd-bluray-web:
|
||||
base_url: http://radarr:7878
|
||||
api_key: {{RADARR_API_KEY}}
|
||||
delete_old_custom_formats: true
|
||||
replace_existing_custom_formats: true
|
||||
include:
|
||||
- template: radarr-quality-definition-movie
|
||||
- template: radarr-quality-profile-hd-bluray-web
|
||||
- template: radarr-custom-formats-hd-bluray-web
|
||||
|
||||
custom_formats:
|
||||
- trash_ids:
|
||||
- 9f6cbff8cfe4ebbc1bde14c7b7bec0de # IMAX Enhanced
|
||||
assign_scores_to:
|
||||
- name: HD Bluray + WEB
|
||||
# score: 0 # Uncomment to disable IMAX Enhanced priority
|
||||
412
docs/RECYCLARR.md
Normal file
412
docs/RECYCLARR.md
Normal file
|
|
@ -0,0 +1,412 @@
|
|||
# Recyclarr Configuration Guide
|
||||
|
||||
Recyclarr automatically synchronizes TRaSH Guides quality profiles and custom formats to your Sonarr and Radarr instances.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Copy Configuration Template
|
||||
|
||||
```bash
|
||||
# Copy the template to your recyclarr config directory
|
||||
cp RECYCLARR_CONFIG_TEMPLATE.yml /volume1/docker/appdata/recyclarr/recyclarr.yml
|
||||
|
||||
# Edit with your API keys
|
||||
nano /volume1/docker/appdata/recyclarr/recyclarr.yml
|
||||
```
|
||||
|
||||
### 2. Get API Keys
|
||||
|
||||
**Sonarr:**
|
||||
1. Open Sonarr web interface: `http://your-nas-ip:8989`
|
||||
2. Go to: Settings → General → Security
|
||||
3. Copy the **API Key**
|
||||
|
||||
**Radarr:**
|
||||
1. Open Radarr web interface: `http://your-nas-ip:7878`
|
||||
2. Go to: Settings → General → Security
|
||||
3. Copy the **API Key**
|
||||
|
||||
### 3. Configure Base URLs
|
||||
|
||||
**CRITICAL:** Use Docker service names, NOT `localhost`!
|
||||
|
||||
```yaml
|
||||
# ✅ Correct - Uses service name
|
||||
sonarr:
|
||||
web-1080p-v4:
|
||||
base_url: http://sonarr:8989
|
||||
api_key: your_sonarr_api_key_here
|
||||
|
||||
radarr:
|
||||
uhd-bluray-web:
|
||||
base_url: http://radarr:7878
|
||||
api_key: your_radarr_api_key_here
|
||||
```
|
||||
|
||||
```yaml
|
||||
# ❌ Wrong - localhost doesn't work in Docker
|
||||
sonarr:
|
||||
web-1080p-v4:
|
||||
base_url: http://localhost:8989 # Won't work!
|
||||
```
|
||||
|
||||
**Why?** Inside the recyclarr container, `localhost` refers to itself, not the host or other containers.
|
||||
|
||||
---
|
||||
|
||||
## Configuration Example
|
||||
|
||||
### Complete Working Configuration
|
||||
|
||||
```yaml
|
||||
sonarr:
|
||||
web-1080p-v4:
|
||||
base_url: http://sonarr:8989
|
||||
api_key: abc123def456... # Your actual API key
|
||||
delete_old_custom_formats: true
|
||||
replace_existing_custom_formats: true
|
||||
include:
|
||||
- template: sonarr-quality-definition-series
|
||||
- template: sonarr-v4-quality-profile-web-1080p
|
||||
- template: sonarr-v4-custom-formats-web-1080p
|
||||
|
||||
web-2160p-v4:
|
||||
base_url: http://sonarr:8989
|
||||
api_key: abc123def456... # Same API key
|
||||
delete_old_custom_formats: true
|
||||
replace_existing_custom_formats: true
|
||||
include:
|
||||
- template: sonarr-quality-definition-series
|
||||
- template: sonarr-v4-quality-profile-web-2160p
|
||||
- template: sonarr-v4-custom-formats-web-2160p
|
||||
|
||||
radarr:
|
||||
uhd-bluray-web:
|
||||
base_url: http://radarr:7878
|
||||
api_key: xyz789ghi012... # Your actual API key
|
||||
delete_old_custom_formats: true
|
||||
replace_existing_custom_formats: true
|
||||
include:
|
||||
- template: radarr-quality-definition-movie
|
||||
- template: radarr-quality-profile-uhd-bluray-web
|
||||
- template: radarr-custom-formats-uhd-bluray-web
|
||||
|
||||
hd-bluray-web:
|
||||
base_url: http://radarr:7878
|
||||
api_key: xyz789ghi012... # Same API key
|
||||
delete_old_custom_formats: true
|
||||
replace_existing_custom_formats: true
|
||||
include:
|
||||
- template: radarr-quality-definition-movie
|
||||
- template: radarr-quality-profile-hd-bluray-web
|
||||
- template: radarr-custom-formats-hd-bluray-web
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing Configuration
|
||||
|
||||
### 1. Validate Config File
|
||||
|
||||
```bash
|
||||
# List configured instances
|
||||
docker exec recyclarr recyclarr config list
|
||||
```
|
||||
|
||||
**Expected output:**
|
||||
```
|
||||
Sonarr Instances:
|
||||
- web-1080p-v4
|
||||
- web-2160p-v4
|
||||
|
||||
Radarr Instances:
|
||||
- uhd-bluray-web
|
||||
- hd-bluray-web
|
||||
```
|
||||
|
||||
### 2. Preview Sync (Dry Run)
|
||||
|
||||
```bash
|
||||
# Preview changes without applying
|
||||
docker exec recyclarr recyclarr sync --preview
|
||||
```
|
||||
|
||||
This shows what would change without actually modifying anything.
|
||||
|
||||
### 3. Actually Sync
|
||||
|
||||
```bash
|
||||
# Apply changes to Sonarr and Radarr
|
||||
docker exec recyclarr recyclarr sync
|
||||
```
|
||||
|
||||
### 4. Check Logs
|
||||
|
||||
```bash
|
||||
# View recyclarr logs
|
||||
docker logs recyclarr
|
||||
|
||||
# Follow logs in real-time
|
||||
docker logs -f recyclarr
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Automatic Sync Schedule
|
||||
|
||||
Recyclarr runs on a cron schedule defined in the container. By default, it syncs daily.
|
||||
|
||||
To modify the schedule, you would need to customize the container configuration (advanced).
|
||||
|
||||
For manual syncs:
|
||||
```bash
|
||||
docker exec recyclarr recyclarr sync
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Issue: "base_url must start with 'http' or 'https'"
|
||||
|
||||
**Cause:** The `base_url` is empty or malformed.
|
||||
|
||||
**Fix:**
|
||||
```yaml
|
||||
# Wrong
|
||||
base_url: localhost:8989
|
||||
base_url: # Empty
|
||||
|
||||
# Correct
|
||||
base_url: http://sonarr:8989
|
||||
```
|
||||
|
||||
### Issue: "Connection refused" or "Cannot connect"
|
||||
|
||||
**Possible causes:**
|
||||
1. Service names are wrong
|
||||
2. Containers not on same network
|
||||
3. Sonarr/Radarr not running
|
||||
|
||||
**Fix:**
|
||||
```bash
|
||||
# Check containers are running
|
||||
docker ps | grep -E "sonarr|radarr|recyclarr"
|
||||
|
||||
# Check network connectivity
|
||||
docker exec recyclarr ping sonarr
|
||||
docker exec recyclarr ping radarr
|
||||
|
||||
# Check Sonarr is responding
|
||||
docker exec recyclarr wget -qO- http://sonarr:8989/ping
|
||||
```
|
||||
|
||||
### Issue: "Unauthorized" or "Invalid API key"
|
||||
|
||||
**Cause:** Wrong API key or permissions issue.
|
||||
|
||||
**Fix:**
|
||||
1. Get correct API key from Sonarr/Radarr (Settings → General → Security)
|
||||
2. Copy-paste carefully (no extra spaces)
|
||||
3. Ensure API key has full permissions
|
||||
|
||||
### Issue: Config file not found
|
||||
|
||||
**Cause:** File not in correct location.
|
||||
|
||||
**Fix:**
|
||||
```bash
|
||||
# Check file exists
|
||||
docker exec recyclarr ls -la /config
|
||||
|
||||
# Expected location inside container
|
||||
/config/recyclarr.yml
|
||||
```
|
||||
|
||||
On host, this maps to:
|
||||
```
|
||||
{{DOCKERCONFDIR}}/recyclarr/recyclarr.yml
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quality Profiles
|
||||
|
||||
### What Recyclarr Syncs
|
||||
|
||||
**For Sonarr:**
|
||||
- Quality definitions (file size limits)
|
||||
- Quality profiles (which qualities to allow)
|
||||
- Custom formats (preferences for releases)
|
||||
- Custom format scores (prioritization)
|
||||
|
||||
**For Radarr:**
|
||||
- Quality definitions
|
||||
- Quality profiles
|
||||
- Custom formats
|
||||
- Custom format scores
|
||||
|
||||
### Available TRaSH Templates
|
||||
|
||||
**Sonarr:**
|
||||
- `sonarr-quality-definition-series` - File size limits
|
||||
- `sonarr-v4-quality-profile-web-1080p` - 1080p WEB profile
|
||||
- `sonarr-v4-quality-profile-web-2160p` - 4K WEB profile
|
||||
- `sonarr-v4-custom-formats-web-1080p` - 1080p custom formats
|
||||
- `sonarr-v4-custom-formats-web-2160p` - 4K custom formats
|
||||
|
||||
**Radarr:**
|
||||
- `radarr-quality-definition-movie` - File size limits
|
||||
- `radarr-quality-profile-hd-bluray-web` - HD Bluray/WEB
|
||||
- `radarr-quality-profile-uhd-bluray-web` - 4K Bluray/WEB
|
||||
- `radarr-custom-formats-hd-bluray-web` - HD custom formats
|
||||
- `radarr-custom-formats-uhd-bluray-web` - 4K custom formats
|
||||
|
||||
---
|
||||
|
||||
## Custom Formats
|
||||
|
||||
### Common Custom Formats
|
||||
|
||||
Recyclarr applies TRaSH Guide custom formats to improve release selection:
|
||||
|
||||
**Quality Improvements:**
|
||||
- Prefer proper/repack releases
|
||||
- Avoid bad dual audio groups
|
||||
- Prefer streaming optimized releases
|
||||
|
||||
**HDR/Audio:**
|
||||
- DV (Dolby Vision) handling
|
||||
- HDR10+ support
|
||||
- Audio codec preferences
|
||||
|
||||
**Release Groups:**
|
||||
- Prefer scene/p2p groups
|
||||
- Avoid obfuscated releases
|
||||
- Filter low-quality encodes
|
||||
|
||||
### Customizing Scores
|
||||
|
||||
In your config, you can adjust scores:
|
||||
|
||||
```yaml
|
||||
custom_formats:
|
||||
- trash_ids:
|
||||
- 9f6cbff8cfe4ebbc1bde14c7b7bec0de # IMAX Enhanced
|
||||
assign_scores_to:
|
||||
- name: UHD Bluray + WEB
|
||||
score: 100 # Higher score = higher priority
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Maintenance
|
||||
|
||||
### Manual Sync
|
||||
|
||||
```bash
|
||||
# Sync all instances
|
||||
docker exec recyclarr recyclarr sync
|
||||
|
||||
# Sync specific instance
|
||||
docker exec recyclarr recyclarr sync sonarr web-1080p-v4
|
||||
```
|
||||
|
||||
### Update Recyclarr
|
||||
|
||||
Recyclarr is updated automatically by Watchtower (if enabled).
|
||||
|
||||
Manual update:
|
||||
```bash
|
||||
docker-compose -f docker-compose.arr-stack.yml pull recyclarr
|
||||
docker-compose -f docker-compose.arr-stack.yml up -d recyclarr
|
||||
```
|
||||
|
||||
### View Current Settings
|
||||
|
||||
Check what's currently configured in Sonarr/Radarr:
|
||||
- Settings → Profiles → Quality Profiles
|
||||
- Settings → Profiles → Custom Formats
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Start with Templates**
|
||||
- Use TRaSH templates as baseline
|
||||
- Customize only if needed
|
||||
|
||||
2. **Test with Preview**
|
||||
- Always preview before syncing
|
||||
- Review changes carefully
|
||||
|
||||
3. **Backup Before Syncing**
|
||||
- Backup Sonarr/Radarr databases
|
||||
- Easy rollback if needed
|
||||
|
||||
4. **Monitor First Sync**
|
||||
- Watch logs during initial sync
|
||||
- Verify profiles in UI after sync
|
||||
|
||||
5. **Keep It Simple**
|
||||
- Don't over-customize initially
|
||||
- TRaSH defaults work well for most
|
||||
|
||||
---
|
||||
|
||||
## Advanced Configuration
|
||||
|
||||
### Multiple Instances
|
||||
|
||||
You can configure multiple Sonarr/Radarr instances:
|
||||
|
||||
```yaml
|
||||
sonarr:
|
||||
instance-1:
|
||||
base_url: http://sonarr:8989
|
||||
api_key: key1
|
||||
|
||||
instance-2:
|
||||
base_url: http://sonarr-4k:8989
|
||||
api_key: key2
|
||||
```
|
||||
|
||||
### Instance-Specific Templates
|
||||
|
||||
Different quality settings per instance:
|
||||
|
||||
```yaml
|
||||
sonarr:
|
||||
web-1080p:
|
||||
include:
|
||||
- template: sonarr-v4-quality-profile-web-1080p
|
||||
|
||||
web-2160p:
|
||||
include:
|
||||
- template: sonarr-v4-quality-profile-web-2160p
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Resources
|
||||
|
||||
- **TRaSH Guides:** https://trash-guides.info/
|
||||
- **Recyclarr Wiki:** https://recyclarr.dev/
|
||||
- **Recyclarr GitHub:** https://github.com/recyclarr/recyclarr
|
||||
- **TRaSH Discord:** https://trash-guides.info/discord
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting Checklist
|
||||
|
||||
- [ ] Config file exists at correct location
|
||||
- [ ] Base URLs use service names (not localhost)
|
||||
- [ ] API keys are correct and complete
|
||||
- [ ] Sonarr/Radarr are running and healthy
|
||||
- [ ] Containers are on same Docker network
|
||||
- [ ] No typos in configuration
|
||||
- [ ] YAML syntax is valid (proper indentation)
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2025-11-23
|
||||
Loading…
Add table
Reference in a new issue