VPN Integration

Integrating Dispatcharr with a VPN container routes all stream traffic through the VPN, enabling access to geo-blocked content without requiring individual client VPN connections. This centralizes VPN management and reduces bandwidth overhead.

Why Use VPN with Dispatcharr?

Access Geo-Blocked Content

Route streams through a VPN exit point in a different region to access region-locked channels and content.

Centralized VPN Management

Instead of configuring VPN on each client device (TV, phone, tablet), route all traffic through Dispatcharr’s VPN container once.

Reduce Bandwidth Overhead

VPN encryption happens once at the server level, not on every client connection.

Protect Provider Traffic

Mask your IPTV provider connections from your ISP or network administrators.

Gluetun Integration (Recommended)

Gluetun is a lightweight VPN client container that supports multiple VPN providers. It acts as a network gateway for other containers.

Docker Compose Setup

Add Gluetun service

Create or modify your docker-compose.yml:

docker-compose.yml

services:
  # Gluetun VPN container
  gluetun:
    image: qmcgaw/gluetun:latest
    container_name: gluetun
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
    ports:
      - 9191:9191  # Dispatcharr web UI
    environment:
      # VPN Provider configuration
      - VPN_SERVICE_PROVIDER=nordvpn  # or mullvad, expressvpn, etc.
      - VPN_TYPE=openvpn              # or wireguard
      - OPENVPN_USER=your_username
      - OPENVPN_PASSWORD=your_password
      - SERVER_REGIONS=United States  # or specific server
      
      # Network configuration
      - FIREWALL_OUTBOUND_SUBNETS=192.168.1.0/24  # Allow local network
      - TZ=America/New_York
    volumes:
      - gluetun_config:/gluetun
    restart: unless-stopped

  # Dispatcharr using Gluetun's network
  dispatcharr:
    image: ghcr.io/dispatcharr/dispatcharr:latest
    container_name: dispatcharr
    network_mode: "service:gluetun"  # Use Gluetun's network
    depends_on:
      - gluetun
    volumes:
      - dispatcharr_data:/data
    restart: unless-stopped

volumes:
  gluetun_config:
  dispatcharr_data:

Configure provider credentials

Update the environment variables for your VPN provider:

NordVPN: OPENVPN_USER, OPENVPN_PASSWORD
Mullvad: WIREGUARD_PRIVATE_KEY, WIREGUARD_ADDRESSES
ExpressVPN: OPENVPN_USER, OPENVPN_PASSWORD

See Gluetun documentation for provider-specific settings.

Start containers

docker-compose up -d

Dispatcharr will now route all traffic through Gluetun’s VPN tunnel.

Verify VPN connection

Check Gluetun logs:

docker logs gluetun

Look for: [INFO] Public IP address: <VPN_IP>

Network Mode Explanation

network_mode: "service:gluetun"

This configuration makes Dispatcharr use Gluetun’s network stack. All traffic (inbound and outbound) flows through the VPN.

Port Mapping: When using network_mode: "service:gluetun", ports must be mapped on the Gluetun container, not on Dispatcharr.

Provider-Specific Configurations

NordVPN

environment:
  - VPN_SERVICE_PROVIDER=nordvpn
  - VPN_TYPE=openvpn
  - [email protected]
  - OPENVPN_PASSWORD=your_password
  - SERVER_REGIONS=United States
  # Optional: Specific server
  - SERVER_HOSTNAMES=us1234.nordvpn.com

Mullvad (WireGuard)

environment:
  - VPN_SERVICE_PROVIDER=mullvad
  - VPN_TYPE=wireguard
  - WIREGUARD_PRIVATE_KEY=your_private_key
  - WIREGUARD_ADDRESSES=10.64.0.1/32
  - SERVER_CITIES=New York

WireGuard is faster and more efficient than OpenVPN for live streaming.

ExpressVPN

environment:
  - VPN_SERVICE_PROVIDER=expressvpn
  - VPN_TYPE=openvpn
  - OPENVPN_USER=your_activation_code
  - OPENVPN_PASSWORD=not_used  # ExpressVPN doesn't use password
  - SERVER_REGIONS=usa

Private Internet Access (PIA)

environment:
  - VPN_SERVICE_PROVIDER=private internet access
  - VPN_TYPE=openvpn
  - OPENVPN_USER=your_username
  - OPENVPN_PASSWORD=your_password
  - SERVER_REGIONS=US New York

Surfshark

environment:
  - VPN_SERVICE_PROVIDER=surfshark
  - VPN_TYPE=openvpn
  - OPENVPN_USER=your_email
  - OPENVPN_PASSWORD=your_password
  - SERVER_COUNTRIES=United States

Modular Deployment with VPN

For modular deployments (separate web/celery/db containers), route only the web service through VPN:

docker-compose.yml

services:
  gluetun:
    image: qmcgaw/gluetun:latest
    container_name: gluetun
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
    ports:
      - 9191:9191
    environment:
      - VPN_SERVICE_PROVIDER=nordvpn
      - OPENVPN_USER=your_username
      - OPENVPN_PASSWORD=your_password
      - SERVER_REGIONS=United States
      - FIREWALL_OUTBOUND_SUBNETS=172.20.0.0/16  # Docker network
    networks:
      - dispatcharr_network

  web:
    image: ghcr.io/dispatcharr/dispatcharr:latest
    container_name: dispatcharr_web
    network_mode: "service:gluetun"  # Use VPN for web/streaming
    depends_on:
      - gluetun
      - db
      - redis
    volumes:
      - ./data:/data
    environment:
      - DISPATCHARR_ENV=modular
      - POSTGRES_HOST=db
      - REDIS_HOST=redis

  celery:
    image: ghcr.io/dispatcharr/dispatcharr:latest
    container_name: dispatcharr_celery
    entrypoint: ["/app/docker/entrypoint.celery.sh"]
    networks:
      - dispatcharr_network  # Direct network (no VPN)
    depends_on:
      - db
      - redis
    volumes:
      - ./data:/data

  db:
    image: postgres:17
    container_name: dispatcharr_db
    networks:
      - dispatcharr_network

  redis:
    image: redis:latest
    container_name: dispatcharr_redis
    networks:
      - dispatcharr_network

networks:
  dispatcharr_network:
    driver: bridge

Celery, PostgreSQL, and Redis use direct network connections. Only stream traffic flows through VPN.

Local Network Access

Allow clients on your local network to access Dispatcharr through the VPN:

environment:
  - FIREWALL_OUTBOUND_SUBNETS=192.168.1.0/24,10.0.0.0/8,172.16.0.0/12

Common private network ranges:

192.168.0.0/16 - Home networks
10.0.0.0/8 - Large private networks
172.16.0.0/12 - Docker networks

Kill Switch

Gluetun includes a built-in kill switch that blocks all traffic if VPN disconnects:

environment:
  - FIREWALL=on  # Default: enabled
  - FIREWALL_VPN_INPUT_PORTS=9191  # Allow Dispatcharr port

If the VPN connection drops, Dispatcharr becomes unreachable until VPN reconnects.

Health Checks

Monitor VPN status with Gluetun’s built-in health check:

gluetun:
  healthcheck:
    test: ["CMD", "wget", "-qO-", "http://localhost:9091/v1/openvpn/status"]
    interval: 30s
    timeout: 10s
    retries: 3

Access health endpoint:

curl http://localhost:9091/v1/openvpn/status

Port Forwarding

Some VPN providers support port forwarding for external access:

environment:
  - VPN_PORT_FORWARDING=on
  - VPN_PORT_FORWARDING_PROVIDER=pia  # or protonvpn

Gluetun will automatically request and maintain a forwarded port.

Split Tunneling

Route specific traffic outside VPN:

environment:
  - FIREWALL_OUTBOUND_SUBNETS=192.168.1.0/24  # LAN
  - HTTPPROXY=on
  - HTTPPROXY_LOG=on
  - HTTPPROXY_LISTENING_ADDRESS=:8888
  - SHADOWSOCKS=off

Access Dispatcharr directly on LAN while IPTV streams use VPN.

Troubleshooting

Cannot access Dispatcharr UI

Check port mapping:

gluetun:
  ports:
    - 9191:9191  # Must be on Gluetun, not Dispatcharr

Verify firewall rules:

environment:
  - FIREWALL_OUTBOUND_SUBNETS=192.168.1.0/24

VPN connection fails

Check credentials:

Verify username/password are correct
Some providers use email, others use separate VPN credentials

Review Gluetun logs:

docker logs gluetun | grep ERROR

Check provider status: Some VPN providers have service outages. Try a different server region.

Streams buffer/lag through VPN

Try WireGuard instead of OpenVPN:

environment:
  - VPN_TYPE=wireguard

Choose closer VPN server:

environment:
  - SERVER_REGIONS=Chicago  # Closer to your location

Check VPN load: Some servers are overloaded. Try different cities/regions.

Database/Redis connection fails

Use custom Docker network:

gluetun:
  networks:
    - dispatcharr_network
  environment:
    - FIREWALL_OUTBOUND_SUBNETS=172.20.0.0/16

db:
  networks:
    - dispatcharr_network

Check container communication:

docker exec dispatcharr ping db

VPN disconnects frequently

Enable reconnection:

environment:
  - OPENVPN_KEEP_ALIVE=30

Try different protocol:

UDP is faster but less stable: OPENVPN_PROTOCOL=udp
TCP is slower but more reliable: OPENVPN_PROTOCOL=tcp

Advanced: Custom OpenVPN Config

Use your own OpenVPN config files:

gluetun:
  environment:
    - VPN_SERVICE_PROVIDER=custom
    - VPN_TYPE=openvpn
  volumes:
    - ./vpn-config:/gluetun/custom:ro

Directory structure:

vpn-config/
├── config.ovpn
├── ca.crt
├── client.crt
└── client.key

Reference

Gluetun Wiki: https://github.com/qdm12/gluetun-wiki
Docker Compose: docker/docker-compose.yml:1
README VPN Section: README.md:34

Test VPN setup with a simple curl from inside the container:

docker exec dispatcharr curl https://ipinfo.io

Verify the IP matches your VPN exit point.

Getting Started

Core Features

Integrations

Configuration

Advanced

Deployment

Why Use VPN with Dispatcharr?

Gluetun Integration (Recommended)

Docker Compose Setup

Network Mode Explanation

Provider-Specific Configurations

NordVPN

Mullvad (WireGuard)

ExpressVPN

Private Internet Access (PIA)

Surfshark

Modular Deployment with VPN

Local Network Access

Kill Switch

Health Checks

Port Forwarding

Split Tunneling

Troubleshooting

Advanced: Custom OpenVPN Config

Reference

Build docs developers (and LLMs) love

Getting Started

Core Features

Integrations

Configuration

Advanced

Deployment

​Why Use VPN with Dispatcharr?

​Gluetun Integration (Recommended)

​Docker Compose Setup

​Network Mode Explanation

​Provider-Specific Configurations

​NordVPN

​Mullvad (WireGuard)

​ExpressVPN

​Private Internet Access (PIA)

​Surfshark

​Modular Deployment with VPN

​Local Network Access

​Kill Switch

​Health Checks

​Port Forwarding

​Split Tunneling

​Troubleshooting

​Advanced: Custom OpenVPN Config

​Reference

Build docs developers (and LLMs) love

Why Use VPN with Dispatcharr?

Gluetun Integration (Recommended)

Docker Compose Setup

Network Mode Explanation

Provider-Specific Configurations

NordVPN

Mullvad (WireGuard)

ExpressVPN

Private Internet Access (PIA)

Surfshark

Modular Deployment with VPN

Local Network Access

Kill Switch

Health Checks

Port Forwarding

Split Tunneling

Troubleshooting

Advanced: Custom OpenVPN Config

Reference