Skip to content

Instantly share code, notes, and snippets.

@jmcdice

jmcdice/couch-commander-architecture.md

Created January 3, 2026 23:12
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save jmcdice/8577f10bd56f51aad1d71aed80e73275 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save jmcdice/8577f10bd56f51aad1d71aed80e73275 to your computer and use it in GitHub Desktop.
Download ZIP
Couch Commander - Network Architecture Diagram
Raw
couch-commander-architecture.md

🛋️⚡ Couch Commander - Network Architecture

System Overview

Complete media automation stack running on UGREEN NAS (Linux) with VPN protection for downloads.

graph TB
    subgraph Internet["🌐 Internet"]
        VPN[ProtonVPN<br/>Netherlands/Sweden/US]
        Indexers[Torrent Indexers<br/>via Prowlarr]
        TMDB[The Movie DB<br/>Metadata]
    end
    
    subgraph NAS["UGREEN NAS - /volume1/plex-infra"]
        subgraph Network["Docker Network: media-net (172.18.0.0/16)"]
            
            subgraph VPNContainer["Gluetun VPN Gateway<br/>172.18.0.10"]
                GluetunVPN[VPN Tunnel<br/>ProtonVPN OpenVPN]
                QBT[qBittorrent<br/>:8080]
            end
            
            Prowlarr[Prowlarr<br/>172.18.0.20:9696<br/>Indexer Manager]
            
            Sonarr[Sonarr<br/>172.18.0.30:8989<br/>TV Shows]
            
            Radarr[Radarr<br/>172.18.0.40:7878<br/>Movies]
            
            Jellyseerr[Jellyseerr<br/>172.18.0.50:5055<br/>Request Portal]
            
            Plex[Plex Media Server<br/>:32400<br/>Streaming]
        end
        
        subgraph Storage["📁 Storage Volumes"]
            Downloads[Downloads/<br/>Torrents]
            Movies[Media/Movies/<br/>Final Library]
            TVShows[Media/TV/<br/>Final Library]
            Config[config/<br/>App Data]
        end
    end
    
    subgraph Clients["👥 Clients"]
        WebUI[Web Browser<br/>Access]
        PlexApps[Plex Apps<br/>TV/Mobile/Desktop]
        Users[Family/Friends]
    end
    
    %% Internet Connections
    VPN <-->|Encrypted| GluetunVPN
    Indexers <-->|Search/Download| Prowlarr
    TMDB <-->|Metadata| Radarr
    TMDB <-->|Metadata| Sonarr
    
    %% VPN Container
    GluetunVPN -.->|Network Mode:<br/>container:gluetun| QBT
    
    %% Internal Container Communication
    Prowlarr <-->|Indexer Sync| Sonarr
    Prowlarr <-->|Indexer Sync| Radarr
    Sonarr <-->|Download Request| QBT
    Radarr <-->|Download Request| QBT
    Jellyseerr <-->|TV Requests| Sonarr
    Jellyseerr <-->|Movie Requests| Radarr
    
    %% Storage Access
    QBT -->|Write| Downloads
    Sonarr -->|Move/Rename| TVShows
    Radarr -->|Move/Rename| Movies
    Plex -->|Read| Movies
    Plex -->|Read| TVShows
    
    %% Client Access
    WebUI -->|HTTP| Jellyseerr
    WebUI -->|HTTP| Prowlarr
    WebUI -->|HTTP| Sonarr
    WebUI -->|HTTP| Radarr
    WebUI -->|HTTP| QBT
    PlexApps <-->|HTTPS/HTTP| Plex
    Users -->|Requests| Jellyseerr
    
    %% Styling
    classDef vpnStyle fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
    classDef downloadStyle fill:#e74c3c,stroke:#c0392b,stroke-width:2px,color:#fff
    classDef manageStyle fill:#2ecc71,stroke:#27ae60,stroke-width:2px,color:#fff
    classDef mediaStyle fill:#9b59b6,stroke:#8e44ad,stroke-width:2px,color:#fff
    classDef storageStyle fill:#f39c12,stroke:#d68910,stroke-width:2px,color:#fff
    classDef clientStyle fill:#1abc9c,stroke:#16a085,stroke-width:2px,color:#fff
    
    class GluetunVPN,QBT vpnStyle
    class Prowlarr downloadStyle
    class Sonarr,Radarr,Jellyseerr manageStyle
    class Plex mediaStyle
    class Downloads,Movies,TVShows,Config storageStyle
    class WebUI,PlexApps,Users clientStyle
Loading

🔄 Data Flow: Movie Request to Streaming

sequenceDiagram
    participant User
    participant Jellyseerr
    participant Radarr
    participant Prowlarr
    participant qBittorrent
    participant Gluetun
    participant Indexers
    participant Storage
    participant Plex
    
    User->>Jellyseerr: Request Movie
    Jellyseerr->>Radarr: Create Movie Entry
    Radarr->>Prowlarr: Search for Release
    Prowlarr->>Indexers: Query Indexers
    Indexers-->>Prowlarr: Return Results
    Prowlarr-->>Radarr: Return Releases
    Radarr->>Radarr: Filter by Quality Profile
    Radarr->>qBittorrent: Send Torrent
    qBittorrent->>Gluetun: Route via VPN
    Gluetun->>Indexers: Download (Encrypted)
    qBittorrent->>Storage: Save to Downloads/
    qBittorrent-->>Radarr: Download Complete
    Radarr->>Storage: Move to Media/Movies/
    Radarr->>Storage: Rename per Format
    Radarr-->>Jellyseerr: Update Status
    Plex->>Storage: Auto-Scan Library
    Plex->>Plex: Match Metadata
    User->>Plex: Stream Movie
Loading

🌐 Network Configuration

Docker Network: media-net

  • Subnet: 172.18.0.0/16
  • Bridge: br-media
  • Purpose: Isolated network for all media services

Container IP Assignments

Service IP Address Ports (Host) Access
Gluetun VPN 172.18.0.10 8080, 6881 qBittorrent Web UI
Prowlarr 172.18.0.20 9696 Indexer Manager
Sonarr 172.18.0.30 8989 TV Show Manager
Radarr 172.18.0.40 7878 Movie Manager
Jellyseerr 172.18.0.50 5055 User Requests
Plex Host Network 32400 Media Streaming

VPN Configuration

  • Provider: ProtonVPN
  • Protocol: OpenVPN
  • Kill Switch: Yes (via Gluetun firewall)
  • Allowed Subnets: 192.168.1.0/24, 172.18.0.0/16
  • Protected Services: qBittorrent (shares VPN network)

📦 Volume Mounts

Host Path                                Container Path
├── /volume1/plex-infra/                → /data/
│   ├── Downloads/                      → /data/Downloads/
│   ├── Media/Movies/                   → /data/Media/Movies/
│   ├── Media/TV/                       → /data/Media/TV/
│   └── Personal/                       → /data/Personal/
└── ./config/{service}/                 → /config/

🔐 Security Features

  1. VPN Isolation

    • All torrent traffic routed through ProtonVPN
    • Kill switch prevents leaks
    • qBittorrent uses network_mode: container:gluetun

  2. Network Segmentation

    • Dedicated Docker network (172.18.0.0/16)
    • Firewall rules limit outbound traffic
    • Services only expose necessary ports

  3. Access Control

    • Services bound to 0.0.0.0 (local network access)
    • API keys required for inter-service communication
    • User permissions: PUID=1000, PGID=10

🎯 Service Dependencies

graph TD
    Gluetun[Gluetun VPN]
    QBT[qBittorrent]
    Prowlarr
    Sonarr
    Radarr
    Jellyseerr
    
    Gluetun -->|healthy| QBT
    Gluetun -->|healthy| Sonarr
    Gluetun -->|healthy| Radarr
    Prowlarr -->|healthy| Sonarr
    Prowlarr -->|healthy| Radarr
    Sonarr -->|healthy| Jellyseerr
    Radarr -->|healthy| Jellyseerr
    
    classDef criticalDep fill:#e74c3c,stroke:#c0392b,stroke-width:2px,color:#fff
    class Gluetun criticalDep
Loading

📊 Resource Limits

Service CPU Limit Memory Limit Purpose
Gluetun 0.5 cores 1 GB VPN Gateway
qBittorrent 2.0 cores 4 GB Download Client
Prowlarr 1.0 cores 1 GB Indexer Manager
Sonarr 1.5 cores 2 GB TV Automation
Radarr 1.5 cores 2 GB Movie Automation
Jellyseerr 1.0 cores 1 GB Request Portal
Plex Unlimited Unlimited Media Streaming

Total Reserved: 7.5 CPU cores, 12 GB RAM

🚦 Health Checks

All services include health checks for monitoring:

  • Gluetun: VPN connectivity to 1.1.1.1
  • qBittorrent: Web UI accessible on :8080
  • Prowlarr/Sonarr/Radarr: API /ping endpoint
  • Jellyseerr: Web server on :5055

🔧 Management Scripts

Located in /home/joey/couch-commander/:

  • manage-stack.sh - Main stack management
  • check-plex-recent.sh - View recently added media
  • check-plex-sessions.sh - Active streaming sessions
  • healthcheck-services.sh - Service health status
  • cleanup-failed-torrents.sh - Clean failed downloads

Generated: 2026-01-03
Stack Version: Couch Commander (UGREEN NAS Linux)
Platform: Docker Compose on UGREEN NAS

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment