Merge pull request #5 from efigueroa/claude/centralized-logging-011CUqEzDETA2BqAzYUcXtjt
Claude/centralized logging 011 c uq ez deta2 bq az y uc xtjt
This commit is contained in:
GitHub
commit
0798e54ba0
14 changed files with 1871 additions and 5 deletions
21
README.md
21
README.md
|
|
@ -30,12 +30,16 @@ compose/
|
|||
│ ├── sonarr/ # TV show management
|
||||
│ ├── radarr/ # Movie management
|
||||
│ ├── sabnzbd/ # Usenet downloader
|
||||
│ └── qbittorrent/# Torrent client
|
||||
│ ├── qbittorrent/# Torrent client
|
||||
│ ├── recyclarr/ # TRaSH Guides sync
|
||||
│ └── profilarr/ # Profile manager (profilarr.fig.systems)
|
||||
├── monitoring/ # Monitoring & logging
|
||||
│ └── logging/ # Centralized logging stack
|
||||
│ ├── loki/ # Log aggregation (loki.fig.systems)
|
||||
│ ├── promtail/ # Log collection agent
|
||||
│ └── grafana/ # Log visualization (logs.fig.systems)
|
||||
│ ├── logging/ # Centralized logging stack
|
||||
│ │ ├── loki/ # Log aggregation (loki.fig.systems)
|
||||
│ │ ├── promtail/ # Log collection agent
|
||||
│ │ └── grafana/ # Log visualization (logs.fig.systems)
|
||||
│ └── uptime/ # Uptime monitoring
|
||||
│ └── uptime-kuma/ # Status & uptime monitoring (status.fig.systems)
|
||||
└── services/ # Utility services
|
||||
├── homarr/ # Dashboard (home.fig.systems)
|
||||
├── backrest/ # Backup manager (backup.fig.systems)
|
||||
|
|
@ -66,6 +70,7 @@ All services are accessible via:
|
|||
| **Monitoring** | | |
|
||||
| Grafana (Logs) | logs.fig.systems | ❌* |
|
||||
| Loki (API) | loki.fig.systems | ✅ |
|
||||
| Uptime Kuma (Status) | status.fig.systems | ❌* |
|
||||
| **Dashboard & Management** | | |
|
||||
| Homarr | home.fig.systems | ✅ |
|
||||
| Backrest | backup.fig.systems | ✅ |
|
||||
|
|
@ -76,6 +81,7 @@ All services are accessible via:
|
|||
| Radarr | radarr.fig.systems | ✅ |
|
||||
| SABnzbd | sabnzbd.fig.systems | ✅ |
|
||||
| qBittorrent | qbt.fig.systems | ✅ |
|
||||
| Profilarr | profilarr.fig.systems | ✅ |
|
||||
| Linkwarden | links.fig.systems | ✅ |
|
||||
| Vikunja | tasks.fig.systems | ✅ |
|
||||
| LubeLogger | garage.fig.systems | ✅ |
|
||||
|
|
@ -153,6 +159,10 @@ cd compose/media/automation/radarr && docker compose up -d
|
|||
cd compose/media/automation/sabnzbd && docker compose up -d
|
||||
cd compose/media/automation/qbittorrent && docker compose up -d
|
||||
|
||||
# Quality management (optional but recommended)
|
||||
cd compose/media/automation/recyclarr && docker compose up -d
|
||||
cd compose/media/automation/profilarr && docker compose up -d
|
||||
|
||||
# Utility services
|
||||
cd compose/services/linkwarden && docker compose up -d
|
||||
cd compose/services/vikunja && docker compose up -d
|
||||
|
|
@ -161,6 +171,7 @@ cd compose/services/backrest && docker compose up -d
|
|||
|
||||
# Monitoring (optional but recommended)
|
||||
cd compose/monitoring/logging && docker compose up -d
|
||||
cd compose/monitoring/uptime && docker compose up -d
|
||||
cd compose/services/lubelogger && docker compose up -d
|
||||
cd compose/services/calibre-web && docker compose up -d
|
||||
cd compose/services/booklore && docker compose up -d
|
||||
|
|
|
|||
7
compose/media/automation/profilarr/.env
Normal file
7
compose/media/automation/profilarr/.env
Normal file
|
|
@ -0,0 +1,7 @@
|
|||
# Profilarr Configuration
|
||||
|
||||
# Timezone
|
||||
TZ=America/Los_Angeles
|
||||
|
||||
# Port (exposed internally to Traefik)
|
||||
PORT=6868
|
||||
5
compose/media/automation/profilarr/.gitignore
vendored
Normal file
5
compose/media/automation/profilarr/.gitignore
vendored
Normal file
|
|
@ -0,0 +1,5 @@
|
|||
# Profilarr data
|
||||
data/
|
||||
|
||||
# Keep .env.example if created
|
||||
!.env.example
|
||||
489
compose/media/automation/profilarr/README.md
Normal file
489
compose/media/automation/profilarr/README.md
Normal file
|
|
@ -0,0 +1,489 @@
|
|||
# Profilarr - Profile & Format Manager
|
||||
|
||||
Web-based management for Radarr/Sonarr custom formats and quality profiles with Git version control.
|
||||
|
||||
## Overview
|
||||
|
||||
**Profilarr** provides a user-friendly interface to manage your Radarr and Sonarr configurations:
|
||||
|
||||
- ✅ **Web UI**: Easy-to-use interface (no YAML editing)
|
||||
- ✅ **Custom Formats**: Import and manage custom formats
|
||||
- ✅ **Quality Profiles**: Create and sync quality profiles
|
||||
- ✅ **Version Control**: Git-based configuration tracking
|
||||
- ✅ **Community Configs**: Import from community databases
|
||||
- ✅ **Conflict Resolution**: Handles configuration clashes
|
||||
- ✅ **Multi-Instance**: Manage multiple Radarr/Sonarr instances
|
||||
- ✅ **Local Preservation**: Keeps your custom changes during updates
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Deploy
|
||||
|
||||
```bash
|
||||
cd ~/homelab/compose/media/automation/profilarr
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### 2. Access Web UI
|
||||
|
||||
Go to: **https://profilarr.fig.systems**
|
||||
|
||||
### 3. Initial Setup
|
||||
|
||||
On first visit, you'll configure Profilarr:
|
||||
|
||||
**Add Radarr Instance:**
|
||||
1. Click **Add Instance**
|
||||
2. **Type**: Radarr
|
||||
3. **Name**: Radarr Main
|
||||
4. **URL**: `http://radarr:7878`
|
||||
5. **API Key**: (from Radarr → Settings → General → API Key)
|
||||
6. Click **Save**
|
||||
|
||||
**Add Sonarr Instance:**
|
||||
1. Click **Add Instance**
|
||||
2. **Type**: Sonarr
|
||||
3. **Name**: Sonarr Main
|
||||
4. **URL**: `http://sonarr:8989`
|
||||
5. **API Key**: (from Sonarr → Settings → General → API Key)
|
||||
6. Click **Save**
|
||||
|
||||
### 4. Import Custom Formats
|
||||
|
||||
**From Community Database:**
|
||||
1. Click **Custom Formats**
|
||||
2. Click **Import from Database**
|
||||
3. Select formats you want (e.g., "Web Tier 01", "Bluray Tier 01")
|
||||
4. Click **Import Selected**
|
||||
5. Click **Sync to Radarr/Sonarr**
|
||||
|
||||
**From TRaSH Guides:**
|
||||
1. Click **Custom Formats**
|
||||
2. Click **Import from TRaSH**
|
||||
3. Browse available formats
|
||||
4. Select and import
|
||||
5. Sync to your instances
|
||||
|
||||
## Features
|
||||
|
||||
### Custom Format Management
|
||||
|
||||
**What are Custom Formats?**
|
||||
|
||||
Custom formats score releases based on:
|
||||
- Release group quality
|
||||
- Source (Bluray, WEB, HDTV, etc.)
|
||||
- Resolution
|
||||
- Codecs
|
||||
- Special editions
|
||||
|
||||
**Example scores:**
|
||||
- **+10000**: Top-tier release groups (e.g., "FraMeSToR", "EPSiLON")
|
||||
- **+5000**: High-quality groups
|
||||
- **-10000**: Unwanted (BR-DISK, CAMs, low quality)
|
||||
|
||||
**Create Custom Format:**
|
||||
1. Custom Formats → Create New
|
||||
2. **Name**: `My Custom Format`
|
||||
3. **Add Conditions**:
|
||||
- Release Group: `FraMeSToR|EPSiLON`
|
||||
- Source: `Bluray`
|
||||
4. **Score**: 10000
|
||||
5. Save and sync
|
||||
|
||||
### Quality Profile Management
|
||||
|
||||
**Create Quality Profile:**
|
||||
1. Quality Profiles → Create New
|
||||
2. **Name**: `HD Bluray + WEB`
|
||||
3. **Add Qualities**:
|
||||
- Bluray-1080p (priority 1)
|
||||
- WEB 1080p (priority 2)
|
||||
- Bluray-720p (priority 3)
|
||||
4. **Cutoff**: Bluray-1080p
|
||||
5. **Custom Format Scoring**:
|
||||
- Enable custom format scores
|
||||
- Set minimum score: 0
|
||||
- Set upgrade until score: 10000
|
||||
6. Save and sync
|
||||
|
||||
### Version Control
|
||||
|
||||
**Every change is tracked:**
|
||||
- Automatic Git commits
|
||||
- View change history
|
||||
- Rollback to previous versions
|
||||
- Compare configurations
|
||||
|
||||
**View History:**
|
||||
1. Click **History** tab
|
||||
2. See all changes with timestamps
|
||||
3. Click any commit to view details
|
||||
4. Click **Rollback** to restore
|
||||
|
||||
**Manual Commit:**
|
||||
1. Make changes
|
||||
2. Click **Commit Changes**
|
||||
3. Add commit message
|
||||
4. Save
|
||||
|
||||
### Sync to Instances
|
||||
|
||||
**Push to Radarr/Sonarr:**
|
||||
1. Make changes in Profilarr
|
||||
2. Click **Sync** button
|
||||
3. Select instances to sync
|
||||
4. Review changes preview
|
||||
5. Click **Apply**
|
||||
|
||||
**Auto-sync:**
|
||||
- Enable in Settings → Sync
|
||||
- Choose sync interval
|
||||
- Changes automatically push to instances
|
||||
|
||||
### Import/Export
|
||||
|
||||
**Export Configuration:**
|
||||
1. Settings → Export
|
||||
2. Download JSON
|
||||
3. Store backup safely
|
||||
|
||||
**Import Configuration:**
|
||||
1. Settings → Import
|
||||
2. Upload JSON file
|
||||
3. Review changes
|
||||
4. Apply
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### 1. Set Up HD Quality Profiles
|
||||
|
||||
**Radarr - HD Bluray + WEB:**
|
||||
|
||||
1. Quality Profiles → Create New
|
||||
2. Name: `HD Bluray + WEB`
|
||||
3. Add qualities:
|
||||
- Bluray-1080p
|
||||
- WEB 1080p (WEBDL-1080p, WEBRip-1080p)
|
||||
- Bluray-720p
|
||||
- WEB 720p
|
||||
4. Cutoff: Bluray-1080p
|
||||
5. Upgrade until score: 10000
|
||||
|
||||
**Add custom formats:**
|
||||
- Import: "Remux Tier 01" (+10000)
|
||||
- Import: "Remux Tier 02" (+9000)
|
||||
- Import: "WEB Tier 01" (+8000)
|
||||
- Import: "BR-DISK" (-10000)
|
||||
- Import: "LQ" (-10000)
|
||||
|
||||
6. Sync to Radarr
|
||||
|
||||
**Sonarr - WEB-1080p:**
|
||||
|
||||
Same process:
|
||||
- WEB 1080p preferred
|
||||
- HDTV-1080p fallback
|
||||
- Import WEB tier custom formats
|
||||
- Sync to Sonarr
|
||||
|
||||
### 2. Manage Multiple Instances
|
||||
|
||||
**Scenario:** Separate 1080p and 4K Radarr instances
|
||||
|
||||
**Setup:**
|
||||
1. Add both instances:
|
||||
- Radarr 1080p (http://radarr:7878)
|
||||
- Radarr 4K (http://radarr-4k:7878)
|
||||
|
||||
2. Create separate profiles:
|
||||
- Profile 1: `HD Bluray + WEB` → Sync to Radarr 1080p
|
||||
- Profile 2: `UHD Bluray + WEB` → Sync to Radarr 4K
|
||||
|
||||
3. Import different custom formats for each
|
||||
|
||||
### 3. Import Community Configurations
|
||||
|
||||
**Popular community configs:**
|
||||
|
||||
1. Custom Formats → Community
|
||||
2. Browse available configs:
|
||||
- **TRaSH Recommended**: Full TRaSH Guides setup
|
||||
- **Anime Optimized**: For anime content
|
||||
- **Remux Preferred**: Maximum quality
|
||||
- **Size Optimized**: Smaller file sizes
|
||||
|
||||
3. Click **Import**
|
||||
4. Review settings
|
||||
5. Sync to your instances
|
||||
|
||||
### 4. Create Anime Profile
|
||||
|
||||
**Sonarr Anime:**
|
||||
|
||||
1. Add custom formats:
|
||||
- "Anime Tier 01" (+10000)
|
||||
- "Anime Tier 02" (+9000)
|
||||
- "Uncensored" (+5000)
|
||||
- "Dual Audio" (+3000)
|
||||
|
||||
2. Create quality profile:
|
||||
- Name: `Anime`
|
||||
- Qualities: Bluray-1080p, WEB 1080p
|
||||
- Enable custom format scoring
|
||||
|
||||
3. Sync to Sonarr
|
||||
|
||||
## Integration with Recyclarr
|
||||
|
||||
**Use both together for best results:**
|
||||
|
||||
### Recyclarr
|
||||
- **Automated** TRaSH Guides sync
|
||||
- **Scheduled** updates (every 6 hours)
|
||||
- **YAML** configuration
|
||||
- **Set and forget**
|
||||
|
||||
### Profilarr
|
||||
- **Manual** custom configurations
|
||||
- **Web UI** for easy changes
|
||||
- **Version control** for tracking
|
||||
- **Quick tweaks** without editing files
|
||||
|
||||
### Workflow
|
||||
|
||||
1. **Recyclarr**: Base configuration from TRaSH Guides
|
||||
2. **Profilarr**: Fine-tune and customize
|
||||
3. **Sync**: Both can coexist (Profilarr takes precedence on conflicts)
|
||||
|
||||
**Example:**
|
||||
- Recyclarr syncs TRaSH quality profiles every 6 hours
|
||||
- You use Profilarr to add custom formats for your favorite release groups
|
||||
- Both stay in sync; Profilarr preserves your customizations
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### Conflict Resolution
|
||||
|
||||
**What are conflicts?**
|
||||
|
||||
When Profilarr and Radarr/Sonarr have different configurations.
|
||||
|
||||
**Resolve conflicts:**
|
||||
1. Conflicts tab shows all conflicts
|
||||
2. Choose resolution:
|
||||
- **Use Profilarr**: Override Radarr/Sonarr
|
||||
- **Use Instance**: Keep Radarr/Sonarr config
|
||||
- **Merge**: Combine both
|
||||
3. Click **Resolve**
|
||||
|
||||
### Scheduling
|
||||
|
||||
**Automatic sync schedule:**
|
||||
|
||||
1. Settings → Sync
|
||||
2. Enable **Auto-sync**
|
||||
3. Set interval:
|
||||
- Every hour
|
||||
- Every 6 hours
|
||||
- Daily
|
||||
4. Save
|
||||
|
||||
**One-way vs Two-way:**
|
||||
- **One-way**: Profilarr → Instance (recommended)
|
||||
- **Two-way**: Sync both directions (can cause conflicts)
|
||||
|
||||
### Webhooks
|
||||
|
||||
**Notify on changes:**
|
||||
|
||||
1. Settings → Webhooks
|
||||
2. Add webhook URL (Discord, Slack, etc.)
|
||||
3. Choose events:
|
||||
- Configuration changed
|
||||
- Sync completed
|
||||
- Conflict detected
|
||||
4. Save
|
||||
|
||||
### API Access
|
||||
|
||||
Profilarr has an API for automation:
|
||||
|
||||
**Get API key:**
|
||||
1. Settings → API
|
||||
2. Generate API Key
|
||||
3. Use in scripts/automation
|
||||
|
||||
**Example API calls:**
|
||||
```bash
|
||||
# List instances
|
||||
curl http://profilarr.fig.systems/api/instances
|
||||
|
||||
# Trigger sync
|
||||
curl -X POST http://profilarr.fig.systems/api/sync \
|
||||
-H "X-API-Key: your-api-key"
|
||||
|
||||
# Get custom formats
|
||||
curl http://profilarr.fig.systems/api/custom-formats
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Can't connect to Radarr/Sonarr
|
||||
|
||||
**Check network:**
|
||||
```bash
|
||||
# Test from Profilarr container
|
||||
docker exec profilarr curl http://radarr:7878
|
||||
docker exec profilarr curl http://sonarr:8989
|
||||
```
|
||||
|
||||
**Verify:**
|
||||
- Containers on same `homelab` network
|
||||
- API keys are correct
|
||||
- URLs use container names (not localhost)
|
||||
|
||||
### Changes not syncing
|
||||
|
||||
**Force sync:**
|
||||
1. Click instance name
|
||||
2. Click **Force Full Sync**
|
||||
3. Check sync logs
|
||||
|
||||
**Check:**
|
||||
- Instance is reachable
|
||||
- API key has write permissions
|
||||
- No conflicts blocking sync
|
||||
|
||||
### "Profile already exists"
|
||||
|
||||
**Conflict resolution:**
|
||||
1. Go to Conflicts tab
|
||||
2. Find the profile conflict
|
||||
3. Choose resolution:
|
||||
- Merge with existing
|
||||
- Replace existing
|
||||
- Rename new profile
|
||||
|
||||
### Database locked
|
||||
|
||||
If you see "database is locked" errors:
|
||||
|
||||
**On Windows:**
|
||||
- Don't use Windows filesystem for data volume
|
||||
- Use Docker volume or WSL2 filesystem
|
||||
|
||||
**Fix:**
|
||||
```bash
|
||||
# Stop container
|
||||
docker compose down
|
||||
|
||||
# Move data to Docker volume
|
||||
docker volume create profilarr-data
|
||||
|
||||
# Update compose.yaml to use volume instead of bind mount
|
||||
```
|
||||
|
||||
### UI not loading
|
||||
|
||||
**Check logs:**
|
||||
```bash
|
||||
docker logs profilarr
|
||||
```
|
||||
|
||||
**Verify:**
|
||||
- Container is running: `docker ps | grep profilarr`
|
||||
- Traefik routing: `docker logs traefik | grep profilarr`
|
||||
- Port 6868 accessible
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Configuration Management
|
||||
|
||||
**Organize by purpose:**
|
||||
- Create separate profiles for different quality tiers
|
||||
- Use descriptive names (e.g., "HD Bluray Preferred", "4K Remux Only")
|
||||
- Document custom formats with notes
|
||||
|
||||
### Version Control
|
||||
|
||||
**Commit regularly:**
|
||||
- After major changes
|
||||
- Before experimenting
|
||||
- Use descriptive commit messages
|
||||
- Tag stable configurations
|
||||
|
||||
### Backup
|
||||
|
||||
**Export regularly:**
|
||||
```bash
|
||||
# Export via UI
|
||||
Settings → Export → Download
|
||||
|
||||
# Or backup data directory
|
||||
cd ~/homelab/compose/media/automation/profilarr
|
||||
tar czf profilarr-backup-$(date +%Y%m%d).tar.gz ./data
|
||||
```
|
||||
|
||||
### Sync Strategy
|
||||
|
||||
**Recommended:**
|
||||
- **Manual sync** for testing changes
|
||||
- **Auto-sync** once you're confident
|
||||
- **Preview** before applying large changes
|
||||
|
||||
### Instance Organization
|
||||
|
||||
**Name instances clearly:**
|
||||
- `Radarr - 1080p`
|
||||
- `Radarr - 4K`
|
||||
- `Sonarr - TV Shows`
|
||||
- `Sonarr - Anime`
|
||||
|
||||
## Getting API Keys
|
||||
|
||||
### Radarr API Key
|
||||
|
||||
1. Go to https://radarr.fig.systems
|
||||
2. Settings → General
|
||||
3. Security section
|
||||
4. Copy **API Key**
|
||||
|
||||
### Sonarr API Key
|
||||
|
||||
1. Go to https://sonarr.fig.systems
|
||||
2. Settings → General
|
||||
3. Security section
|
||||
4. Copy **API Key**
|
||||
|
||||
## Resource Usage
|
||||
|
||||
**Typical usage:**
|
||||
- **RAM**: 100-200MB
|
||||
- **CPU**: Low (spikes during sync)
|
||||
- **Disk**: <500MB
|
||||
- **Network**: Minimal
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. ✅ Deploy Profilarr
|
||||
2. ✅ Add Radarr/Sonarr instances
|
||||
3. ✅ Import custom formats
|
||||
4. ✅ Create quality profiles
|
||||
5. ✅ Sync to instances
|
||||
6. ✅ Test download quality
|
||||
7. ⬜ Set up auto-sync
|
||||
8. ⬜ Configure version control
|
||||
9. ⬜ Export backup configuration
|
||||
|
||||
## Resources
|
||||
|
||||
- [Profilarr Website](https://dictionarry.dev)
|
||||
- [Profilarr GitHub](https://github.com/Dictionarry-Hub/profilarr)
|
||||
- [TRaSH Guides](https://trash-guides.info)
|
||||
- [Radarr Wiki](https://wiki.servarr.com/radarr)
|
||||
- [Sonarr Wiki](https://wiki.servarr.com/sonarr)
|
||||
|
||||
---
|
||||
|
||||
**Manage profiles with ease!** 🎛️
|
||||
40
compose/media/automation/profilarr/compose.yaml
Normal file
40
compose/media/automation/profilarr/compose.yaml
Normal file
|
|
@ -0,0 +1,40 @@
|
|||
# Profilarr - Custom Format & Quality Profile Manager
|
||||
# Docs: https://dictionarry.dev
|
||||
|
||||
services:
|
||||
profilarr:
|
||||
container_name: profilarr
|
||||
image: santiagosayshey/profilarr:latest
|
||||
restart: unless-stopped
|
||||
|
||||
env_file:
|
||||
- .env
|
||||
|
||||
volumes:
|
||||
- ./data:/app/data
|
||||
|
||||
networks:
|
||||
- homelab
|
||||
|
||||
labels:
|
||||
# Traefik
|
||||
traefik.enable: true
|
||||
traefik.docker.network: homelab
|
||||
|
||||
# Web UI
|
||||
traefik.http.routers.profilarr.rule: Host(`profilarr.fig.systems`) || Host(`profilarr.edfig.dev`)
|
||||
traefik.http.routers.profilarr.entrypoints: websecure
|
||||
traefik.http.routers.profilarr.tls.certresolver: letsencrypt
|
||||
traefik.http.services.profilarr.loadbalancer.server.port: 6868
|
||||
|
||||
# SSO Protection
|
||||
traefik.http.routers.profilarr.middlewares: tinyauth
|
||||
|
||||
# Homarr Discovery
|
||||
homarr.name: Profilarr (Profiles)
|
||||
homarr.group: Automation
|
||||
homarr.icon: mdi:cog-sync
|
||||
|
||||
networks:
|
||||
homelab:
|
||||
external: true
|
||||
12
compose/media/automation/recyclarr/.env
Normal file
12
compose/media/automation/recyclarr/.env
Normal file
|
|
@ -0,0 +1,12 @@
|
|||
# Recyclarr Configuration
|
||||
|
||||
# Timezone
|
||||
TZ=America/Los_Angeles
|
||||
|
||||
# Sync schedule (cron format)
|
||||
# Default: Every 6 hours
|
||||
# Example: "0 2 * * *" = Daily at 2 AM
|
||||
CRON_SCHEDULE=0 */6 * * *
|
||||
|
||||
# Log level (Debug, Information, Warning, Error)
|
||||
LOG_LEVEL=Information
|
||||
5
compose/media/automation/recyclarr/.gitignore
vendored
Normal file
5
compose/media/automation/recyclarr/.gitignore
vendored
Normal file
|
|
@ -0,0 +1,5 @@
|
|||
# Recyclarr config and data
|
||||
config/
|
||||
|
||||
# Keep .env.example if created
|
||||
!.env.example
|
||||
490
compose/media/automation/recyclarr/README.md
Normal file
490
compose/media/automation/recyclarr/README.md
Normal file
|
|
@ -0,0 +1,490 @@
|
|||
# Recyclarr - TRaSH Guides Sync
|
||||
|
||||
Automatically sync TRaSH Guides recommendations to your Radarr and Sonarr instances.
|
||||
|
||||
## Overview
|
||||
|
||||
**Recyclarr** keeps your Radarr and Sonarr configurations in sync with [TRaSH Guides](https://trash-guides.info) best practices:
|
||||
|
||||
- ✅ **Quality Profiles**: Optimal quality settings
|
||||
- ✅ **Custom Formats**: Release group scoring
|
||||
- ✅ **Quality Definitions**: File size recommendations
|
||||
- ✅ **Naming Formats**: Consistent file naming
|
||||
- ✅ **Automated Sync**: Runs on schedule (every 6 hours by default)
|
||||
- ✅ **Multi-Instance**: Support multiple Radarr/Sonarr instances
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Get API Keys
|
||||
|
||||
**Radarr API Key:**
|
||||
```bash
|
||||
# Visit https://radarr.fig.systems
|
||||
# Settings → General → Security → API Key
|
||||
```
|
||||
|
||||
**Sonarr API Key:**
|
||||
```bash
|
||||
# Visit https://sonarr.fig.systems
|
||||
# Settings → General → Security → API Key
|
||||
```
|
||||
|
||||
### 2. Create Configuration
|
||||
|
||||
```bash
|
||||
cd ~/homelab/compose/media/automation/recyclarr
|
||||
|
||||
# Create config directory
|
||||
mkdir -p config
|
||||
|
||||
# Copy example config
|
||||
cp recyclarr.yml.example config/recyclarr.yml
|
||||
|
||||
# Edit with your API keys
|
||||
nano config/recyclarr.yml
|
||||
```
|
||||
|
||||
**Update these values:**
|
||||
```yaml
|
||||
radarr:
|
||||
radarr-main:
|
||||
api_key: YOUR_RADARR_API_KEY_HERE # <- Replace this
|
||||
|
||||
sonarr:
|
||||
sonarr-main:
|
||||
api_key: YOUR_SONARR_API_KEY_HERE # <- Replace this
|
||||
```
|
||||
|
||||
### 3. Deploy
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### 4. Verify
|
||||
|
||||
Check the logs to see sync results:
|
||||
```bash
|
||||
docker logs recyclarr
|
||||
```
|
||||
|
||||
You should see:
|
||||
```
|
||||
Processing configuration...
|
||||
Syncing Radarr: radarr-main
|
||||
Syncing Sonarr: sonarr-main
|
||||
Sync completed successfully
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Basic Configuration
|
||||
|
||||
The `config/recyclarr.yml` file controls what gets synced.
|
||||
|
||||
**Minimal example:**
|
||||
```yaml
|
||||
radarr:
|
||||
radarr-main:
|
||||
base_url: http://radarr:7878
|
||||
api_key: abc123...
|
||||
|
||||
sonarr:
|
||||
sonarr-main:
|
||||
base_url: http://sonarr:8989
|
||||
api_key: xyz789...
|
||||
```
|
||||
|
||||
### Quality Profiles
|
||||
|
||||
**Radarr - HD Bluray + WEB:**
|
||||
```yaml
|
||||
radarr:
|
||||
radarr-main:
|
||||
quality_profiles:
|
||||
- name: HD Bluray + WEB
|
||||
upgrade:
|
||||
allowed: true
|
||||
until_quality: Bluray-1080p
|
||||
qualities:
|
||||
- name: Bluray-1080p
|
||||
- name: WEB 1080p
|
||||
- name: Bluray-720p
|
||||
- name: WEB 720p
|
||||
```
|
||||
|
||||
**Sonarr - WEB-1080p:**
|
||||
```yaml
|
||||
sonarr:
|
||||
sonarr-main:
|
||||
quality_profiles:
|
||||
- name: WEB-1080p
|
||||
upgrade:
|
||||
allowed: true
|
||||
until_quality: WEB 1080p
|
||||
qualities:
|
||||
- name: WEB 1080p
|
||||
- name: HDTV-1080p
|
||||
- name: WEB 720p
|
||||
```
|
||||
|
||||
### Custom Formats
|
||||
|
||||
Custom formats score releases based on quality, source, and release group.
|
||||
|
||||
**High-quality release groups (+10000 points):**
|
||||
```yaml
|
||||
custom_formats:
|
||||
- trash_ids:
|
||||
- 3a3ff47579026e76d6504ebea39390de # Remux Tier 01
|
||||
- 9f98181fe5a3fbeb0cc29340da2a468a # Remux Tier 02
|
||||
quality_profiles:
|
||||
- name: HD Bluray + WEB
|
||||
score: 10000
|
||||
```
|
||||
|
||||
**Unwanted formats (-10000 points):**
|
||||
```yaml
|
||||
custom_formats:
|
||||
- trash_ids:
|
||||
- ed38b889b31be83ffc192888e2286d83 # BR-DISK
|
||||
- 90a6f9a284dff5103f6346090e6280c8 # LQ
|
||||
- b8cd450cbfa689c0259a01d9e29ba3d6 # 3D
|
||||
quality_profiles:
|
||||
- name: HD Bluray + WEB
|
||||
score: -10000
|
||||
```
|
||||
|
||||
**Find trash_ids:**
|
||||
- [TRaSH Radarr Custom Formats](https://trash-guides.info/Radarr/Radarr-collection-of-custom-formats/)
|
||||
- [TRaSH Sonarr Custom Formats](https://trash-guides.info/Sonarr/sonarr-collection-of-custom-formats/)
|
||||
|
||||
### Sync Schedule
|
||||
|
||||
**Change sync frequency:**
|
||||
|
||||
Edit `.env`:
|
||||
```env
|
||||
# Every 6 hours (default)
|
||||
CRON_SCHEDULE=0 */6 * * *
|
||||
|
||||
# Daily at 3 AM
|
||||
CRON_SCHEDULE=0 3 * * *
|
||||
|
||||
# Every 12 hours
|
||||
CRON_SCHEDULE=0 */12 * * *
|
||||
|
||||
# Every hour
|
||||
CRON_SCHEDULE=0 * * * *
|
||||
```
|
||||
|
||||
**Manual sync:**
|
||||
```bash
|
||||
docker exec recyclarr recyclarr sync
|
||||
```
|
||||
|
||||
## Common Configurations
|
||||
|
||||
### 1. HD Quality (1080p)
|
||||
|
||||
Good balance of quality and file size.
|
||||
|
||||
**Radarr:**
|
||||
- Bluray-1080p preferred
|
||||
- WEB-1080p as fallback
|
||||
- Scores high-quality release groups
|
||||
|
||||
**Sonarr:**
|
||||
- WEB-1080p preferred
|
||||
- HDTV-1080p as fallback
|
||||
|
||||
### 2. Maximum Quality (Remux)
|
||||
|
||||
Best possible quality, large file sizes.
|
||||
|
||||
```yaml
|
||||
radarr:
|
||||
radarr-main:
|
||||
quality_profiles:
|
||||
- name: Remux-1080p
|
||||
upgrade:
|
||||
allowed: true
|
||||
until_quality: Remux-1080p
|
||||
qualities:
|
||||
- name: Remux-1080p
|
||||
- name: Bluray-1080p
|
||||
```
|
||||
|
||||
### 3. 4K / UHD
|
||||
|
||||
For 4K content:
|
||||
|
||||
```yaml
|
||||
radarr:
|
||||
radarr-4k:
|
||||
base_url: http://radarr:7878
|
||||
api_key: abc123...
|
||||
quality_profiles:
|
||||
- name: UHD Bluray + WEB
|
||||
upgrade:
|
||||
until_quality: Remux-2160p
|
||||
qualities:
|
||||
- name: Remux-2160p
|
||||
- name: Bluray-2160p
|
||||
- name: WEB 2160p
|
||||
```
|
||||
|
||||
### 4. Anime
|
||||
|
||||
Special settings for anime:
|
||||
|
||||
```yaml
|
||||
sonarr:
|
||||
sonarr-anime:
|
||||
base_url: http://sonarr:8989
|
||||
api_key: xyz789...
|
||||
quality_profiles:
|
||||
- name: Anime
|
||||
qualities:
|
||||
- name: Bluray-1080p
|
||||
- name: WEB 1080p
|
||||
custom_formats:
|
||||
- trash_ids:
|
||||
- 064af5f084a0a24458cc8ecd3220f93f # Uncensored
|
||||
quality_profiles:
|
||||
- name: Anime
|
||||
score: 10000
|
||||
```
|
||||
|
||||
## Integration with Radarr/Sonarr
|
||||
|
||||
### How It Works
|
||||
|
||||
1. **Recyclarr reads** your `recyclarr.yml` configuration
|
||||
2. **Connects to** Radarr/Sonarr via API
|
||||
3. **Syncs settings:**
|
||||
- Creates/updates quality profiles
|
||||
- Adds custom formats with scores
|
||||
- Sets quality definitions
|
||||
- Configures naming formats
|
||||
4. **Your instances** now use TRaSH Guides best practices
|
||||
|
||||
### What Gets Changed
|
||||
|
||||
**Recyclarr modifies:**
|
||||
- Quality profile settings
|
||||
- Custom format definitions
|
||||
- Quality definitions (file sizes)
|
||||
- Naming formats (if configured)
|
||||
|
||||
**Recyclarr does NOT touch:**
|
||||
- Your media files
|
||||
- Download client settings
|
||||
- Indexer configurations
|
||||
- Root folder locations
|
||||
- Existing downloads/monitoring
|
||||
|
||||
### Multiple Instances
|
||||
|
||||
Run separate Radarr/Sonarr instances for different purposes:
|
||||
|
||||
```yaml
|
||||
radarr:
|
||||
radarr-1080p:
|
||||
base_url: http://radarr:7878
|
||||
api_key: abc123...
|
||||
|
||||
radarr-4k:
|
||||
base_url: http://radarr-4k:7878
|
||||
api_key: def456...
|
||||
|
||||
sonarr:
|
||||
sonarr-shows:
|
||||
base_url: http://sonarr:8989
|
||||
api_key: ghi789...
|
||||
|
||||
sonarr-anime:
|
||||
base_url: http://sonarr-anime:8989
|
||||
api_key: jkl012...
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Recyclarr won't start
|
||||
|
||||
**Check logs:**
|
||||
```bash
|
||||
docker logs recyclarr
|
||||
```
|
||||
|
||||
**Common issues:**
|
||||
- Missing API keys in `config/recyclarr.yml`
|
||||
- Radarr/Sonarr not accessible at `base_url`
|
||||
- Invalid YAML syntax
|
||||
|
||||
### "Unable to connect to Radarr/Sonarr"
|
||||
|
||||
**Verify connectivity:**
|
||||
```bash
|
||||
# From recyclarr container
|
||||
docker exec recyclarr curl http://radarr:7878
|
||||
docker exec recyclarr curl http://sonarr:8989
|
||||
```
|
||||
|
||||
**Check:**
|
||||
- Radarr/Sonarr containers are running
|
||||
- Both on `homelab` network
|
||||
- API keys are correct
|
||||
|
||||
### "Profile not found"
|
||||
|
||||
The quality profile name in `recyclarr.yml` must match exactly.
|
||||
|
||||
**Check existing profiles:**
|
||||
1. Go to Radarr → Settings → Profiles
|
||||
2. Note the exact profile name
|
||||
3. Use that name in `recyclarr.yml`
|
||||
|
||||
Or let Recyclarr create the profile (it will if it doesn't exist).
|
||||
|
||||
### Changes not appearing
|
||||
|
||||
**Force a sync:**
|
||||
```bash
|
||||
docker exec recyclarr recyclarr sync --preview
|
||||
docker exec recyclarr recyclarr sync
|
||||
```
|
||||
|
||||
**Check:**
|
||||
- Look for errors in logs
|
||||
- Verify API key has write permissions
|
||||
- Check Radarr/Sonarr system logs
|
||||
|
||||
### Invalid trash_id
|
||||
|
||||
If you see "invalid trash_id" errors:
|
||||
|
||||
1. Visit [TRaSH Guides](https://trash-guides.info)
|
||||
2. Find the custom format you want
|
||||
3. Copy the exact trash_id from the guide
|
||||
4. Update `recyclarr.yml`
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### Preview Mode
|
||||
|
||||
See what would change without applying:
|
||||
|
||||
```bash
|
||||
docker exec recyclarr recyclarr sync --preview
|
||||
```
|
||||
|
||||
### Sync Specific Instance
|
||||
|
||||
```bash
|
||||
# Sync only Radarr
|
||||
docker exec recyclarr recyclarr sync radarr
|
||||
|
||||
# Sync only Sonarr
|
||||
docker exec recyclarr recyclarr sync sonarr
|
||||
|
||||
# Sync specific instance
|
||||
docker exec recyclarr recyclarr sync radarr-main
|
||||
```
|
||||
|
||||
### Validate Configuration
|
||||
|
||||
```bash
|
||||
docker exec recyclarr recyclarr config list
|
||||
docker exec recyclarr recyclarr config check
|
||||
```
|
||||
|
||||
### Debug Mode
|
||||
|
||||
Enable debug logging in `.env`:
|
||||
```env
|
||||
LOG_LEVEL=Debug
|
||||
```
|
||||
|
||||
Then restart:
|
||||
```bash
|
||||
docker compose restart
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Start Simple
|
||||
|
||||
1. **First sync:** Use default quality profiles
|
||||
2. **Test:** Download a movie/show
|
||||
3. **Verify:** Check quality and file size
|
||||
4. **Adjust:** Modify scores and profiles as needed
|
||||
|
||||
### Quality Profile Strategy
|
||||
|
||||
**For most users:**
|
||||
- Radarr: HD Bluray + WEB (1080p)
|
||||
- Sonarr: WEB-1080p
|
||||
|
||||
**For quality enthusiasts:**
|
||||
- Radarr: Remux-1080p or UHD Bluray + WEB
|
||||
- Sonarr: Bluray-1080p
|
||||
|
||||
**For storage-conscious:**
|
||||
- Lower minimum quality
|
||||
- Add file size limits
|
||||
- Score smaller releases higher
|
||||
|
||||
### Custom Format Scores
|
||||
|
||||
**Scoring guide:**
|
||||
- **+10000**: Highest priority (preferred release groups)
|
||||
- **+5000**: High priority (good quality)
|
||||
- **+1000**: Moderate preference
|
||||
- **-10000**: Never download (BR-DISK, CAM, etc.)
|
||||
- **-5000**: Avoid unless no alternative
|
||||
|
||||
### Sync Frequency
|
||||
|
||||
**Recommended schedules:**
|
||||
- **Every 6 hours**: Default, good balance
|
||||
- **Daily**: If you rarely update settings
|
||||
- **Every hour**: If actively tuning configurations
|
||||
|
||||
## TRaSH Guides Resources
|
||||
|
||||
- [TRaSH Guides Home](https://trash-guides.info)
|
||||
- [Radarr Custom Formats](https://trash-guides.info/Radarr/)
|
||||
- [Sonarr Custom Formats](https://trash-guides.info/Sonarr/)
|
||||
- [Recyclarr Documentation](https://recyclarr.dev)
|
||||
|
||||
## Comparison: Recyclarr vs Profilarr
|
||||
|
||||
| Feature | Recyclarr | Profilarr |
|
||||
|---------|-----------|-----------|
|
||||
| **Interface** | CLI / Automated | Web UI |
|
||||
| **Configuration** | YAML file | Web interface |
|
||||
| **Source** | TRaSH Guides | Custom + Community |
|
||||
| **Automation** | Scheduled sync | Manual/scheduled |
|
||||
| **Version Control** | Via Git (manual) | Built-in |
|
||||
| **Learning Curve** | Moderate | Easy |
|
||||
| **Best For** | Set-and-forget | Active management |
|
||||
|
||||
**Use both together:**
|
||||
- Recyclarr for automated TRaSH sync
|
||||
- Profilarr for custom tweaks and management
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. ✅ Deploy Recyclarr
|
||||
2. ✅ Configure API keys
|
||||
3. ✅ Run first sync
|
||||
4. ✅ Check Radarr/Sonarr profiles
|
||||
5. ✅ Test download quality
|
||||
6. ⬜ Fine-tune custom format scores
|
||||
7. ⬜ Set up Profilarr for additional management
|
||||
8. ⬜ Monitor sync logs periodically
|
||||
|
||||
---
|
||||
|
||||
**Automate quality, maintain consistency!** 🎬
|
||||
32
compose/media/automation/recyclarr/compose.yaml
Normal file
32
compose/media/automation/recyclarr/compose.yaml
Normal file
|
|
@ -0,0 +1,32 @@
|
|||
# Recyclarr - Sync TRaSH Guides to Radarr/Sonarr
|
||||
# Docs: https://recyclarr.dev
|
||||
|
||||
services:
|
||||
recyclarr:
|
||||
container_name: recyclarr
|
||||
image: ghcr.io/recyclarr/recyclarr:latest
|
||||
restart: unless-stopped
|
||||
|
||||
env_file:
|
||||
- .env
|
||||
|
||||
volumes:
|
||||
- ./config:/config
|
||||
|
||||
networks:
|
||||
- homelab
|
||||
|
||||
# Run sync on startup and every 6 hours
|
||||
# Use cron schedule: "0 */6 * * *" for every 6 hours
|
||||
environment:
|
||||
- CRON_SCHEDULE=0 */6 * * *
|
||||
|
||||
labels:
|
||||
# Homarr Discovery
|
||||
homarr.name: Recyclarr (Quality Sync)
|
||||
homarr.group: Automation
|
||||
homarr.icon: mdi:recycle
|
||||
|
||||
networks:
|
||||
homelab:
|
||||
external: true
|
||||
131
compose/media/automation/recyclarr/recyclarr.yml.example
Normal file
131
compose/media/automation/recyclarr/recyclarr.yml.example
Normal file
|
|
@ -0,0 +1,131 @@
|
|||
# Recyclarr Configuration
|
||||
# Copy this file to ./config/recyclarr.yml and update with your API keys
|
||||
# Docs: https://recyclarr.dev/wiki/yaml/config-reference/
|
||||
|
||||
# Radarr Configuration
|
||||
radarr:
|
||||
radarr-main:
|
||||
base_url: http://radarr:7878
|
||||
api_key: YOUR_RADARR_API_KEY_HERE
|
||||
|
||||
# Quality Definitions
|
||||
quality_definition:
|
||||
type: movie
|
||||
preferred_ratio: 0.5
|
||||
|
||||
# Quality Profiles
|
||||
quality_profiles:
|
||||
# HD Bluray + WEB profile
|
||||
- name: HD Bluray + WEB
|
||||
reset_unmatched_scores:
|
||||
enabled: true
|
||||
upgrade:
|
||||
allowed: true
|
||||
until_quality: Bluray-1080p
|
||||
until_score: 10000
|
||||
min_format_score: 0
|
||||
quality_sort: top
|
||||
qualities:
|
||||
- name: Bluray-1080p
|
||||
- name: WEB 1080p
|
||||
qualities:
|
||||
- WEBDL-1080p
|
||||
- WEBRip-1080p
|
||||
- name: Bluray-720p
|
||||
- name: WEB 720p
|
||||
qualities:
|
||||
- WEBDL-720p
|
||||
- WEBRip-720p
|
||||
|
||||
# Custom Formats from TRaSH Guides
|
||||
custom_formats:
|
||||
# Movie Versions
|
||||
- trash_ids:
|
||||
- 0f12c086e289cf966fa5948eac571f44 # Hybrid
|
||||
- 570bc9ebecd92723d2d21500f4be314c # Remaster
|
||||
- eca37840c13c6ef2dd0262b141a5482f # 4K Remaster
|
||||
- e0c07d59beb37348e975a930d5e50319 # Criterion Collection
|
||||
- 9d27d9d2181838f76dee150882bdc58c # Masters of Cinema
|
||||
- db9b4c4b53d312a3ca5f1378f6440fc9 # Vinegar Syndrome
|
||||
quality_profiles:
|
||||
- name: HD Bluray + WEB
|
||||
|
||||
# HQ Release Groups
|
||||
- trash_ids:
|
||||
- 3a3ff47579026e76d6504ebea39390de # Remux Tier 01
|
||||
- 9f98181fe5a3fbeb0cc29340da2a468a # Remux Tier 02
|
||||
- 8baaf0b3142bf4d94c42a724f034e27a # Remux Tier 03
|
||||
quality_profiles:
|
||||
- name: HD Bluray + WEB
|
||||
score: 10000
|
||||
|
||||
# Unwanted formats
|
||||
- trash_ids:
|
||||
- ed38b889b31be83ffc192888e2286d83 # BR-DISK
|
||||
- 90a6f9a284dff5103f6346090e6280c8 # LQ
|
||||
- b8cd450cbfa689c0259a01d9e29ba3d6 # 3D
|
||||
- 7357cf5161efbf8c4d5d0c30b4815ee2 # Obfuscated
|
||||
- ae9b7c9ebde1f3bd336a8cbd1ec4c5e5 # No-RlsGroup
|
||||
- dc98083864ea246d05a42df0d05f81cc # x265 (HD)
|
||||
quality_profiles:
|
||||
- name: HD Bluray + WEB
|
||||
score: -10000
|
||||
|
||||
# Sonarr Configuration
|
||||
sonarr:
|
||||
sonarr-main:
|
||||
base_url: http://sonarr:8989
|
||||
api_key: YOUR_SONARR_API_KEY_HERE
|
||||
|
||||
# Quality Definitions
|
||||
quality_definition:
|
||||
type: series
|
||||
preferred_ratio: 0.5
|
||||
|
||||
# Release Profiles (v3)
|
||||
# For Sonarr v4, use custom_formats instead
|
||||
|
||||
# Quality Profiles
|
||||
quality_profiles:
|
||||
# WEB-1080p profile
|
||||
- name: WEB-1080p
|
||||
reset_unmatched_scores:
|
||||
enabled: true
|
||||
upgrade:
|
||||
allowed: true
|
||||
until_quality: WEB 1080p
|
||||
until_score: 10000
|
||||
min_format_score: 0
|
||||
quality_sort: top
|
||||
qualities:
|
||||
- name: WEB 1080p
|
||||
qualities:
|
||||
- WEBDL-1080p
|
||||
- WEBRip-1080p
|
||||
- name: HDTV-1080p
|
||||
- name: WEB 720p
|
||||
qualities:
|
||||
- WEBDL-720p
|
||||
- WEBRip-720p
|
||||
- name: HDTV-720p
|
||||
|
||||
# Custom Formats from TRaSH Guides
|
||||
custom_formats:
|
||||
# HQ Release Groups
|
||||
- trash_ids:
|
||||
- d6819cba26b1a6508138d25fb5e32293 # WEB Tier 01
|
||||
- 2016d1676f5ee13a5b7257ff86ac9a93 # WEB Tier 02
|
||||
- 7221e47c5ae4e0b3eb0c01c5b6e5c31e # WEB Tier 03
|
||||
quality_profiles:
|
||||
- name: WEB-1080p
|
||||
score: 10000
|
||||
|
||||
# Unwanted formats
|
||||
- trash_ids:
|
||||
- 85c61753df5da1fb2aab6f2a47426b09 # BR-DISK
|
||||
- 9c11cd3f07101cdba90a2d81cf0e56b4 # LQ
|
||||
- 47435ece6b99a0b477caf360e79ba0bb # x265 (HD)
|
||||
- fbcb31d8dabd2a319072b84fc0b7249c # Extras
|
||||
quality_profiles:
|
||||
- name: WEB-1080p
|
||||
score: -10000
|
||||
10
compose/monitoring/uptime/.env
Normal file
10
compose/monitoring/uptime/.env
Normal file
|
|
@ -0,0 +1,10 @@
|
|||
# Uptime Kuma Configuration
|
||||
|
||||
# Timezone
|
||||
TZ=America/Los_Angeles
|
||||
|
||||
# Port (default: 3001, but we use Traefik so this doesn't matter)
|
||||
# UPTIME_KUMA_PORT=3001
|
||||
|
||||
# Disable auto-update check (optional)
|
||||
# UPTIME_KUMA_DISABLE_FRAME_SAMEORIGIN=false
|
||||
5
compose/monitoring/uptime/.gitignore
vendored
Normal file
5
compose/monitoring/uptime/.gitignore
vendored
Normal file
|
|
@ -0,0 +1,5 @@
|
|||
# Uptime Kuma data
|
||||
data/
|
||||
|
||||
# Keep .env.example if created
|
||||
!.env.example
|
||||
581
compose/monitoring/uptime/README.md
Normal file
581
compose/monitoring/uptime/README.md
Normal file
|
|
@ -0,0 +1,581 @@
|
|||
# Uptime Kuma - Status & Uptime Monitoring
|
||||
|
||||
Beautiful uptime monitoring and alerting for all your homelab services.
|
||||
|
||||
## Overview
|
||||
|
||||
**Uptime Kuma** monitors the health and uptime of your services:
|
||||
|
||||
- ✅ **HTTP(s) Monitoring**: Check if web services are responding
|
||||
- ✅ **TCP Port Monitoring**: Check if services are listening on ports
|
||||
- ✅ **Docker Container Monitoring**: Check container status
|
||||
- ✅ **Response Time**: Measure how fast services respond
|
||||
- ✅ **SSL Certificate Monitoring**: Alert before certificates expire
|
||||
- ✅ **Status Pages**: Public or private status pages
|
||||
- ✅ **Notifications**: Email, Discord, Slack, Pushover, and 90+ more
|
||||
- ✅ **Beautiful UI**: Clean, modern interface
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Deploy
|
||||
|
||||
```bash
|
||||
cd ~/homelab/compose/monitoring/uptime
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### 2. Access Web UI
|
||||
|
||||
Go to: **https://status.fig.systems**
|
||||
|
||||
### 3. Create Admin Account
|
||||
|
||||
On first visit, you'll be prompted to create an admin account:
|
||||
- Username: `admin` (or your choice)
|
||||
- Password: Strong password
|
||||
- Click "Create"
|
||||
|
||||
### 4. Add Your First Monitor
|
||||
|
||||
Click **"Add New Monitor"**
|
||||
|
||||
**Example: Monitor Jellyfin**
|
||||
- Monitor Type: `HTTP(s)`
|
||||
- Friendly Name: `Jellyfin`
|
||||
- URL: `https://flix.fig.systems`
|
||||
- Heartbeat Interval: `60` seconds
|
||||
- Retries: `3`
|
||||
- Click **Save**
|
||||
|
||||
Uptime Kuma will now check Jellyfin every 60 seconds!
|
||||
|
||||
## Monitoring Your Services
|
||||
|
||||
### Quick Setup All Services
|
||||
|
||||
Here's a template for all your homelab services:
|
||||
|
||||
**Core Services:**
|
||||
```
|
||||
Name: Traefik Dashboard
|
||||
Type: HTTP(s)
|
||||
URL: https://traefik.fig.systems
|
||||
Interval: 60s
|
||||
|
||||
Name: LLDAP
|
||||
Type: HTTP(s)
|
||||
URL: https://lldap.fig.systems
|
||||
Interval: 60s
|
||||
|
||||
Name: Grafana Logs
|
||||
Type: HTTP(s)
|
||||
URL: https://logs.fig.systems
|
||||
Interval: 60s
|
||||
```
|
||||
|
||||
**Media Services:**
|
||||
```
|
||||
Name: Jellyfin
|
||||
Type: HTTP(s)
|
||||
URL: https://flix.fig.systems
|
||||
Interval: 60s
|
||||
|
||||
Name: Immich
|
||||
Type: HTTP(s)
|
||||
URL: https://photos.fig.systems
|
||||
Interval: 60s
|
||||
|
||||
Name: Jellyseerr
|
||||
Type: HTTP(s)
|
||||
URL: https://requests.fig.systems
|
||||
Interval: 60s
|
||||
|
||||
Name: Sonarr
|
||||
Type: HTTP(s)
|
||||
URL: https://sonarr.fig.systems
|
||||
Interval: 60s
|
||||
|
||||
Name: Radarr
|
||||
Type: HTTP(s)
|
||||
URL: https://radarr.fig.systems
|
||||
Interval: 60s
|
||||
```
|
||||
|
||||
**Utility Services:**
|
||||
```
|
||||
Name: Homarr Dashboard
|
||||
Type: HTTP(s)
|
||||
URL: https://home.fig.systems
|
||||
Interval: 60s
|
||||
|
||||
Name: Backrest
|
||||
Type: HTTP(s)
|
||||
URL: https://backup.fig.systems
|
||||
Interval: 60s
|
||||
|
||||
Name: Linkwarden
|
||||
Type: HTTP(s)
|
||||
URL: https://links.fig.systems
|
||||
Interval: 60s
|
||||
|
||||
Name: Vikunja
|
||||
Type: HTTP(s)
|
||||
URL: https://tasks.fig.systems
|
||||
Interval: 60s
|
||||
```
|
||||
|
||||
### Advanced Monitoring Options
|
||||
|
||||
#### Monitor Docker Containers Directly
|
||||
|
||||
**Setup:**
|
||||
1. Add New Monitor
|
||||
2. Type: **Docker Container**
|
||||
3. Docker Daemon: `unix:///var/run/docker.sock`
|
||||
4. Container Name: `jellyfin`
|
||||
5. Click Save
|
||||
|
||||
**Benefits:**
|
||||
- Checks if container is running
|
||||
- Monitors container restarts
|
||||
- No network requests needed
|
||||
|
||||
**Note**: Requires mounting Docker socket (already configured).
|
||||
|
||||
#### Monitor TCP Ports
|
||||
|
||||
**Example: Monitor PostgreSQL**
|
||||
```
|
||||
Type: TCP Port
|
||||
Hostname: linkwarden-postgres
|
||||
Port: 5432
|
||||
Interval: 60s
|
||||
```
|
||||
|
||||
#### Check SSL Certificates
|
||||
|
||||
**Automatic**: When using HTTP(s) monitors, Uptime Kuma automatically:
|
||||
- Checks SSL certificate validity
|
||||
- Alerts when certificate expires soon (7 days default)
|
||||
- Shows certificate expiry date
|
||||
|
||||
#### Keyword Monitoring
|
||||
|
||||
Check if a page contains specific text:
|
||||
|
||||
```
|
||||
Type: HTTP(s) - Keyword
|
||||
URL: https://home.fig.systems
|
||||
Keyword: "Homarr" # Check page contains "Homarr"
|
||||
```
|
||||
|
||||
## Notifications
|
||||
|
||||
### Setup Alerts
|
||||
|
||||
1. Click **Settings** (gear icon)
|
||||
2. Click **Notifications**
|
||||
3. Click **Setup Notification**
|
||||
|
||||
### Popular Options
|
||||
|
||||
#### Email
|
||||
```
|
||||
Type: Email (SMTP)
|
||||
Host: smtp.gmail.com
|
||||
Port: 587
|
||||
Security: TLS
|
||||
Username: your-email@gmail.com
|
||||
Password: your-app-password
|
||||
From: alerts@yourdomain.com
|
||||
To: you@email.com
|
||||
```
|
||||
|
||||
#### Discord
|
||||
```
|
||||
Type: Discord
|
||||
Webhook URL: https://discord.com/api/webhooks/...
|
||||
(Get from Discord Server Settings → Integrations → Webhooks)
|
||||
```
|
||||
|
||||
#### Slack
|
||||
```
|
||||
Type: Slack
|
||||
Webhook URL: https://hooks.slack.com/services/...
|
||||
(Get from Slack App → Incoming Webhooks)
|
||||
```
|
||||
|
||||
#### Pushover (Mobile)
|
||||
```
|
||||
Type: Pushover
|
||||
User Key: (from Pushover account)
|
||||
App Token: (create app in Pushover)
|
||||
Priority: Normal
|
||||
```
|
||||
|
||||
#### Gotify (Self-hosted)
|
||||
```
|
||||
Type: Gotify
|
||||
Server URL: https://gotify.yourdomain.com
|
||||
App Token: (from Gotify)
|
||||
Priority: 5
|
||||
```
|
||||
|
||||
### Apply to Monitors
|
||||
|
||||
After setting up notification:
|
||||
1. Edit a monitor
|
||||
2. Scroll to **Notifications**
|
||||
3. Select your notification method
|
||||
4. Click **Save**
|
||||
|
||||
Or apply to all monitors:
|
||||
1. Settings → Notifications
|
||||
2. Click **Apply on all existing monitors**
|
||||
|
||||
## Status Pages
|
||||
|
||||
### Create Public Status Page
|
||||
|
||||
Perfect for showing service status to family/friends!
|
||||
|
||||
**Setup:**
|
||||
1. Click **Status Pages**
|
||||
2. Click **Add New Status Page**
|
||||
3. **Slug**: `homelab` (creates /status/homelab)
|
||||
4. **Title**: `Homelab Status`
|
||||
5. **Description**: `Status of all homelab services`
|
||||
6. Click **Next**
|
||||
|
||||
**Add Services:**
|
||||
1. Drag monitors into "Public" or "Groups"
|
||||
2. Organize by category (Core, Media, Utilities)
|
||||
3. Click **Save**
|
||||
|
||||
**Access:**
|
||||
- Private: https://status.fig.systems/status/homelab
|
||||
- Or make public (no login required)
|
||||
|
||||
**Share with family:**
|
||||
```
|
||||
https://status.fig.systems/status/homelab
|
||||
```
|
||||
|
||||
### Customize Status Page
|
||||
|
||||
**Options:**
|
||||
- Show/hide uptime percentage
|
||||
- Show/hide response time
|
||||
- Custom domain
|
||||
- Theme (light/dark/auto)
|
||||
- Custom CSS
|
||||
- Password protection
|
||||
|
||||
## Tags and Groups
|
||||
|
||||
### Organize Monitors with Tags
|
||||
|
||||
**Create Tags:**
|
||||
1. Click **Manage Tags**
|
||||
2. Add tags like:
|
||||
- `core`
|
||||
- `media`
|
||||
- `critical`
|
||||
- `production`
|
||||
|
||||
**Apply to Monitors:**
|
||||
1. Edit monitor
|
||||
2. Scroll to **Tags**
|
||||
3. Select tags
|
||||
4. Save
|
||||
|
||||
**Filter by Tag:**
|
||||
- Click tag name to show only those monitors
|
||||
|
||||
### Create Monitor Groups
|
||||
|
||||
**Group by service type:**
|
||||
1. Settings → Groups
|
||||
2. Create groups:
|
||||
- Core Infrastructure
|
||||
- Media Services
|
||||
- Productivity
|
||||
- Monitoring
|
||||
|
||||
Drag monitors into groups for organization.
|
||||
|
||||
## Maintenance Windows
|
||||
|
||||
### Schedule Maintenance
|
||||
|
||||
Pause notifications during planned downtime:
|
||||
|
||||
1. Edit monitor
|
||||
2. Click **Maintenance**
|
||||
3. **Add Maintenance**
|
||||
4. Set start/end time
|
||||
5. Select monitors
|
||||
6. Save
|
||||
|
||||
During maintenance:
|
||||
- Monitor still checks but doesn't alert
|
||||
- Status page shows "In Maintenance"
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Monitor Configuration
|
||||
|
||||
**Heartbeat Interval:**
|
||||
- Critical services: 30-60 seconds
|
||||
- Normal services: 60-120 seconds
|
||||
- Background jobs: 300-600 seconds
|
||||
|
||||
**Retries:**
|
||||
- Set to 2-3 to avoid false positives
|
||||
- Service must fail 2-3 times before alerting
|
||||
|
||||
**Timeout:**
|
||||
- Web services: 10-30 seconds
|
||||
- APIs: 5-10 seconds
|
||||
- Slow services: 30-60 seconds
|
||||
|
||||
### What to Monitor
|
||||
|
||||
**Critical (Monitor these!):**
|
||||
- ✅ Traefik (if this is down, everything is down)
|
||||
- ✅ LLDAP (SSO depends on this)
|
||||
- ✅ Core services users depend on
|
||||
|
||||
**Important:**
|
||||
- ✅ Jellyfin, Immich (main media services)
|
||||
- ✅ Sonarr, Radarr (automation)
|
||||
- ✅ Backrest (backups)
|
||||
|
||||
**Nice to have:**
|
||||
- ⬜ Utility services
|
||||
- ⬜ Less critical services
|
||||
|
||||
**Don't over-monitor:**
|
||||
- Internal components (databases, redis, etc.)
|
||||
- These should be monitored via main service health
|
||||
|
||||
### Notification Strategy
|
||||
|
||||
**Alert fatigue is real!**
|
||||
|
||||
**Good approach:**
|
||||
- Critical services → Immediate push notification
|
||||
- Important services → Email
|
||||
- Nice-to-have → Email digest
|
||||
|
||||
**Don't:**
|
||||
- Alert on every blip
|
||||
- Send all alerts to mobile push
|
||||
- Alert on expected downtime
|
||||
|
||||
## Integration with Loki
|
||||
|
||||
Uptime Kuma and Loki complement each other:
|
||||
|
||||
**Uptime Kuma:**
|
||||
- ✅ Is the service UP or DOWN?
|
||||
- ✅ How long was it down?
|
||||
- ✅ Response time trends
|
||||
|
||||
**Loki:**
|
||||
- ✅ WHY did it go down?
|
||||
- ✅ What errors happened?
|
||||
- ✅ Historical log analysis
|
||||
|
||||
**Workflow:**
|
||||
1. Uptime Kuma alerts you: "Jellyfin is down!"
|
||||
2. Go to Grafana/Loki
|
||||
3. Query: `{container="jellyfin"} | __timestamp__ >= now() - 15m`
|
||||
4. See what went wrong
|
||||
|
||||
## Metrics and Graphs
|
||||
|
||||
### Built-in Metrics
|
||||
|
||||
Uptime Kuma tracks:
|
||||
- **Uptime %**: 99.9%, 99.5%, etc.
|
||||
- **Response Time**: Average, min, max
|
||||
- **Ping**: Latency to service
|
||||
- **Certificate Expiry**: Days until SSL expires
|
||||
|
||||
### Response Time Graph
|
||||
|
||||
Click any monitor to see:
|
||||
- 24-hour response time graph
|
||||
- Uptime/downtime periods
|
||||
- Recent incidents
|
||||
|
||||
### Export Data
|
||||
|
||||
Export uptime data:
|
||||
1. Settings → Backup
|
||||
2. Export JSON (includes all monitors and data)
|
||||
3. Store backup safely
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Monitor Shows Down But Service Works
|
||||
|
||||
**Check:**
|
||||
1. **SSL Certificate**: Is it valid?
|
||||
2. **SSO**: Does monitor need to login first?
|
||||
3. **Timeout**: Is timeout too short?
|
||||
4. **Network**: Can Uptime Kuma reach the service?
|
||||
|
||||
**Solutions:**
|
||||
- Increase timeout
|
||||
- Check accepted status codes (200-299)
|
||||
- Verify URL is correct
|
||||
- Check Uptime Kuma logs: `docker logs uptime-kuma`
|
||||
|
||||
### Docker Container Monitor Not Working
|
||||
|
||||
**Requirements:**
|
||||
- Docker socket must be mounted (✅ already configured)
|
||||
- Container name must be exact
|
||||
|
||||
**Test:**
|
||||
```bash
|
||||
docker exec uptime-kuma ls /var/run/docker.sock
|
||||
# Should show the socket file
|
||||
```
|
||||
|
||||
### Notifications Not Sending
|
||||
|
||||
**Check:**
|
||||
1. Test notification in Settings → Notifications
|
||||
2. Check Uptime Kuma logs
|
||||
3. Verify notification service credentials
|
||||
4. Check if notification is enabled on monitor
|
||||
|
||||
### Can't Access Web UI
|
||||
|
||||
**Check:**
|
||||
```bash
|
||||
# Container running?
|
||||
docker ps | grep uptime-kuma
|
||||
|
||||
# Logs
|
||||
docker logs uptime-kuma
|
||||
|
||||
# Traefik routing
|
||||
docker logs traefik | grep uptime
|
||||
```
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### API Access
|
||||
|
||||
Uptime Kuma has a WebSocket API:
|
||||
|
||||
**Get API Key:**
|
||||
1. Settings → API Keys
|
||||
2. Generate new key
|
||||
3. Use with monitoring tools
|
||||
|
||||
### Docker Socket Monitoring
|
||||
|
||||
Already configured! You can monitor:
|
||||
- Container status (running/stopped)
|
||||
- Container restarts
|
||||
- Resource usage (via Docker stats)
|
||||
|
||||
### Multiple Status Pages
|
||||
|
||||
Create different status pages:
|
||||
- `/status/public` - For family/friends
|
||||
- `/status/critical` - Only critical services
|
||||
- `/status/media` - Media services only
|
||||
|
||||
### Custom CSS
|
||||
|
||||
Brand your status page:
|
||||
1. Status Page → Edit
|
||||
2. Custom CSS
|
||||
3. Add styling
|
||||
|
||||
**Example:**
|
||||
```css
|
||||
body {
|
||||
background: #1a1a1a;
|
||||
}
|
||||
.title {
|
||||
color: #00ff00;
|
||||
}
|
||||
```
|
||||
|
||||
## Resource Usage
|
||||
|
||||
**Typical usage:**
|
||||
- **RAM**: 50-150MB
|
||||
- **CPU**: Very low (only during checks)
|
||||
- **Disk**: <100MB
|
||||
- **Network**: Minimal (only during checks)
|
||||
|
||||
**Very lightweight!**
|
||||
|
||||
## Backup and Restore
|
||||
|
||||
### Backup
|
||||
|
||||
**Automatic backup:**
|
||||
1. Settings → Backup
|
||||
2. Export
|
||||
|
||||
**Manual backup:**
|
||||
```bash
|
||||
cd ~/homelab/compose/monitoring/uptime
|
||||
tar czf uptime-backup-$(date +%Y%m%d).tar.gz ./data
|
||||
```
|
||||
|
||||
### Restore
|
||||
|
||||
```bash
|
||||
docker compose down
|
||||
tar xzf uptime-backup-YYYYMMDD.tar.gz
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
## Comparison: Uptime Kuma vs Loki
|
||||
|
||||
| Feature | Uptime Kuma | Loki |
|
||||
|---------|-------------|------|
|
||||
| **Purpose** | Uptime monitoring | Log aggregation |
|
||||
| **Checks** | HTTP, TCP, Ping, Docker | Logs only |
|
||||
| **Alerts** | Service down, slow | Log patterns |
|
||||
| **Response Time** | ✅ Yes | ❌ No |
|
||||
| **Uptime %** | ✅ Yes | ❌ No |
|
||||
| **SSL Monitoring** | ✅ Yes | ❌ No |
|
||||
| **Why Service Down** | ❌ No | ✅ Yes (via logs) |
|
||||
| **Historical Logs** | ❌ No | ✅ Yes |
|
||||
| **Status Pages** | ✅ Yes | ❌ No |
|
||||
|
||||
**Use both together!**
|
||||
- Uptime Kuma tells you WHAT is down
|
||||
- Loki tells you WHY it went down
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. ✅ Deploy Uptime Kuma
|
||||
2. ✅ Add monitors for all services
|
||||
3. ✅ Set up notifications (Email, Discord, etc.)
|
||||
4. ✅ Create status page
|
||||
5. ✅ Test alerts by stopping a service
|
||||
6. ⬜ Share status page with family
|
||||
7. ⬜ Set up maintenance windows
|
||||
8. ⬜ Review and tune check intervals
|
||||
|
||||
## Resources
|
||||
|
||||
- [Uptime Kuma GitHub](https://github.com/louislam/uptime-kuma)
|
||||
- [Uptime Kuma Wiki](https://github.com/louislam/uptime-kuma/wiki)
|
||||
- [Notification Services List](https://github.com/louislam/uptime-kuma/wiki/Notification-Services)
|
||||
|
||||
---
|
||||
|
||||
**Know instantly when something goes down!** 🚨
|
||||
48
compose/monitoring/uptime/compose.yaml
Normal file
48
compose/monitoring/uptime/compose.yaml
Normal file
|
|
@ -0,0 +1,48 @@
|
|||
# Uptime Kuma - Status and Uptime Monitoring
|
||||
# Docs: https://github.com/louislam/uptime-kuma
|
||||
|
||||
services:
|
||||
uptime-kuma:
|
||||
container_name: uptime-kuma
|
||||
image: louislam/uptime-kuma:1
|
||||
restart: unless-stopped
|
||||
|
||||
env_file:
|
||||
- .env
|
||||
|
||||
volumes:
|
||||
- ./data:/app/data
|
||||
|
||||
networks:
|
||||
- homelab
|
||||
|
||||
labels:
|
||||
# Traefik
|
||||
traefik.enable: true
|
||||
traefik.docker.network: homelab
|
||||
|
||||
# Web UI
|
||||
traefik.http.routers.uptime-kuma.rule: Host(`status.fig.systems`) || Host(`status.edfig.dev`)
|
||||
traefik.http.routers.uptime-kuma.entrypoints: websecure
|
||||
traefik.http.routers.uptime-kuma.tls.certresolver: letsencrypt
|
||||
traefik.http.services.uptime-kuma.loadbalancer.server.port: 3001
|
||||
|
||||
# SSO Protection (optional - Uptime Kuma has its own auth)
|
||||
# Uncomment to require SSO:
|
||||
# traefik.http.routers.uptime-kuma.middlewares: tinyauth
|
||||
|
||||
# Homarr Discovery
|
||||
homarr.name: Uptime Kuma (Status)
|
||||
homarr.group: Monitoring
|
||||
homarr.icon: mdi:heart-pulse
|
||||
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "node extra/healthcheck.js"]
|
||||
interval: 60s
|
||||
timeout: 10s
|
||||
retries: 3
|
||||
start_period: 60s
|
||||
|
||||
networks:
|
||||
homelab:
|
||||
external: true
|
||||
Loading…
Reference in a new issue