magicalyak/nzbgetvpn repository overview

⁠🛡️ NZBGet VPN Docker 🚀

Secure NZBGet downloads with automatic VPN protection. This Docker container combines NZBGet with OpenVPN/WireGuard, ensuring all your downloads are protected by your VPN connection.

🔗 Get it now: docker pull magicalyak/nzbgetvpn:latest

⁠✨ Key Features

• 🔒 Automatic VPN Protection - All NZBGet traffic routed through your VPN
• 🌐 VPN Protocol Support - Both OpenVPN and WireGuard
• 🏗️ Multi-Platform - Works on x86, ARM64 (Raspberry Pi, Apple Silicon)
• ⚙️ Auto-Configuration - Set up your news server via environment variables
• 📊 Built-in Monitoring - Health checks and Prometheus metrics endpoints
• 🔄 Self-Healing - Automatic restart on VPN/service failures
• 🐧 BusyBox Compatible - Works reliably across all Linux distributions

⁠🚀 Quick Start

⁠1. Prepare Your System

Create directories for your data:

# Create data directories
mkdir -p ~/nzbgetvpn/{config/openvpn,downloads}

# Example directory structure:
# ~/nzbgetvpn/
# ├── config/
# │   └── openvpn/          # Put your .ovpn file here
# └── downloads/            # Downloads will go here

⁠2. Get Your VPN Configuration

Download your VPN configuration file from your provider and place it in ~/nzbgetvpn/config/openvpn/:

Popular VPN providers:

• NordVPN OpenVPN configs⁠
• ExpressVPN configs⁠
• Surfshark configs⁠
• Most providers offer OpenVPN config downloads

🔐 VPN Credentials (OpenVPN only):

You have two options for providing VPN credentials:

Option 1: Environment Variables (quick setup)

-e VPN_USER=your_vpn_username \
-e VPN_PASS=your_vpn_password \

Option 2: Credentials File (more secure, recommended)

# Create credentials file (more secure than environment variables)
echo "your_vpn_username" > ~/nzbgetvpn/config/openvpn/credentials.txt
echo "your_vpn_password" >> ~/nzbgetvpn/config/openvpn/credentials.txt

# Don't set VPN_USER/VPN_PASS when using file method

⁠3. Run the Container

Basic OpenVPN example:

docker run -d \
  --name nzbgetvpn \
  --cap-add=NET_ADMIN \
  --device=/dev/net/tun \
  -p 6789:6789 \
  -v ~/nzbgetvpn/config:/config \
  -v ~/nzbgetvpn/downloads:/downloads \
  -e VPN_CLIENT=openvpn \
  -e VPN_CONFIG=/config/openvpn/your-provider.ovpn \
  -e VPN_USER=your_vpn_username \
  -e VPN_PASS=your_vpn_password \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=America/New_York \
  magicalyak/nzbgetvpn:latest

Replace these values:

• your-provider.ovpn → your actual OpenVPN config filename
• your_vpn_username → your VPN username
• your_vpn_password → your VPN password
• America/New_York → your timezone

⁠4. Access NZBGet

1. Open your browser: http://localhost:6789⁠
2. Default login: Username: nzbget, Password: tegbzn6789
3. ⚠️ Important: Change the password immediately in Settings → Security

⁠5. Configure Your News Server

In NZBGet web interface:

1. Go to Settings → News-servers
2. Configure Server1 with your Usenet provider details
3. Test the connection and save

⁠💡 Using Environment File (Recommended)

For easier management, create an .env file:

# Create .env file
cat > ~/nzbgetvpn/.env << 'EOF'
# VPN Settings
VPN_CLIENT=openvpn
VPN_CONFIG=/config/openvpn/your-provider.ovpn
VPN_USER=your_vpn_username
VPN_PASS=your_vpn_password

# System Settings
PUID=1000
PGID=1000
TZ=America/New_York

# Optional: Auto-configure news server
NZBGET_S1_NAME=MyNewsServer
NZBGET_S1_HOST=news.provider.com
NZBGET_S1_PORT=563
NZBGET_S1_USER=news_username
NZBGET_S1_PASS=news_password
NZBGET_S1_CONN=15
NZBGET_S1_SSL=yes
EOF

# Run with environment file
docker run -d \
  --name nzbgetvpn \
  --cap-add=NET_ADMIN \
  --device=/dev/net/tun \
  -p 6789:6789 \
  -v ~/nzbgetvpn/config:/config \
  -v ~/nzbgetvpn/downloads:/downloads \
  --env-file ~/nzbgetvpn/.env \
  magicalyak/nzbgetvpn:latest

⁠🐳 Docker Compose

Create docker-compose.yml:

version: "3.8"

services:
  nzbgetvpn:
    image: magicalyak/nzbgetvpn:latest
    container_name: nzbgetvpn
    env_file: .env
    ports:
      - "6789:6789"        # NZBGet Web UI
      - "8080:8080"        # Monitoring (optional)
    volumes:
      - ./config:/config
      - ./downloads:/downloads
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    devices:
      - /dev/net/tun
    sysctls:
      - net.ipv4.conf.all.src_valid_mark=1
    restart: unless-stopped

Run with: docker-compose up -d

⁠🔧 Essential Environment Variables

⁠✅ Verify Everything Works

# Check container is running
docker ps | grep nzbgetvpn

# Verify VPN connection (should show VPN IP, not your real IP)
docker exec nzbgetvpn curl -s ifconfig.me

# Check logs
docker logs nzbgetvpn --tail 20

# Access monitoring (if enabled)
curl http://localhost:8080/health

⁠📚 Advanced Configuration

⁠🌐 WireGuard Setup

WireGuard often provides better performance than OpenVPN:

# 1. Get WireGuard config from your provider
# 2. Place it in ~/nzbgetvpn/config/wireguard/

# 3. Update your .env file:
VPN_CLIENT=wireguard
VPN_CONFIG=/config/wireguard/wg0.conf

# 4. Add sysctls to docker run:
docker run -d \
  --sysctl="net.ipv4.conf.all.src_valid_mark=1" \
  # ... other options

⁠🔗 VPN Provider Examples

VPN_CLIENT=openvpn
VPN_CONFIG=/config/openvpn/us9999.nordvpn.com.ovpn
VPN_USER=your_nordvpn_username
VPN_PASS=your_nordvpn_password

VPN_CLIENT=wireguard
VPN_CONFIG=/config/wireguard/nordvpn-us.conf

VPN_CLIENT=openvpn
VPN_CONFIG=/config/openvpn/us-nyc.prod.surfshark.com_udp.ovpn
VPN_USER=your_surfshark_username
VPN_PASS=your_surfshark_password

VPN_CLIENT=wireguard
VPN_CONFIG=/config/wireguard/mullvad-us.conf

VPN_CLIENT=openvpn
VPN_CONFIG=/config/openvpn/us_east.ovpn
VPN_USER=your_pia_username
VPN_PASS=your_pia_password

VPN_CLIENT=openvpn
VPN_CONFIG=/config/openvpn/privado-us.ovpn
VPN_USER=your_privado_username
VPN_PASS=your_privado_password

VPN_CLIENT=wireguard
VPN_CONFIG=/config/wireguard/privado-us.conf

⁠📊 Monitoring with Prometheus & Grafana

nzbgetvpn includes comprehensive monitoring capabilities with Prometheus metrics, health checks, and status endpoints.

⁠Quick Monitoring Setup

1. Enable monitoring in your .env file:

ENABLE_MONITORING=yes
MONITORING_PORT=8080

2. Expose monitoring port in docker-compose.yml:

ports:
  - "6789:6789"    # NZBGet
  - "8080:8080"    # Monitoring

3. Configure Prometheus to scrape metrics:

# Add to your prometheus.yml
scrape_configs:
  - job_name: 'nzbgetvpn-metrics'
    static_configs:
      - targets: ['your-host:8080']
    metrics_path: '/prometheus'
    scrape_interval: 30s

⁠Available Endpoints

⁠Example Health Response

{
  "timestamp": "2025-01-19T15:30:00Z",
  "status": "healthy",
  "exit_code": 0,
  "vpn_interface": "tun0", 
  "external_ip": "203.0.113.42",
  "checks": {
    "nzbget": "success",
    "vpn_interface": "up",
    "dns": "success",
    "news_server": "success"
  }
}

⁠Prometheus Metrics

The container provides these key metrics:

• nzbgetvpn_health_check - Overall health (1=healthy, 0=unhealthy)
• nzbgetvpn_check{check="service"} - Individual service status
• nzbgetvpn_response_time_seconds - Response times for health checks
• nzbgetvpn_success_rate_percent - Success rates by service

⁠Docker Compose with Monitoring Stack

version: '3.8'
services:
  nzbgetvpn:
    image: magicalyak/nzbgetvpn:latest
    devices:
      - /dev/net/tun
    cap_add:
      - NET_ADMIN
    environment:
      - ENABLE_MONITORING=yes
      - VPN_CLIENT=openvpn
      - VPN_CONFIG=/config/openvpn/your-provider.ovpn
    ports:
      - "6789:6789"
      - "8080:8080"

  prometheus:
    image: prom/prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml

  grafana:
    image: grafana/grafana
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin

👉 Complete monitoring guide: monitoring/docs/MONITORING_SETUP.md⁠

⁠🔧 Enhanced Monitoring & Auto-Restart

Enable advanced monitoring and automatic service recovery:

# In your .env file
ENABLE_MONITORING=yes
MONITORING_PORT=8080
ENABLE_AUTO_RESTART=true
RESTART_COOLDOWN_SECONDS=300
NOTIFICATION_WEBHOOK_URL=https://discord.com/api/webhooks/YOUR_WEBHOOK

Auto-restart features:

• Automatically restarts VPN connection if it fails
• Monitors NZBGet health and restarts if needed
• Configurable cooldown periods to prevent restart loops
• Discord/Slack notifications for service events

⁠🏗️ Multi-Architecture Support

nzbgetvpn supports multiple architectures natively:

Platform-specific examples:

# ARM64-optimized settings
docker run -d \
  --name nzbgetvpn \
  --cap-add=NET_ADMIN \
  --cap-add=SYS_MODULE \
  --device=/dev/net/tun \
  --sysctl="net.ipv4.conf.all.src_valid_mark=1" \
  -p 6789:6789 \
  -e VPN_CLIENT=wireguard \
  -e NZBGET_S1_CONN=8 \
  -v ~/nzbgetvpn/config:/config \
  -v ~/nzbgetvpn/downloads:/downloads \
  magicalyak/nzbgetvpn:latest

👉 Full guide: MULTI-ARCH.md⁠

⁠⚙️ Advanced Environment Variables

⁠🛠️ Building Fixed Version

If you encounter issues with the standard image, we provide a fixed version with BusyBox compatibility improvements:

# Build the fixed version
chmod +x build-fixed.sh
./build-fixed.sh

# Use the fixed image
docker-compose.yml:
  image: magicalyak/nzbgetvpn:fixed

The fixed version includes:

• ✅ BusyBox grep compatibility - Fixes health check issues on some systems
• ✅ Enhanced monitoring - Improved Prometheus metrics collection
• ✅ Better VPN integration - Resolved device mapping issues

When to use the fixed version:

• Health checks show "unknown" status despite working VPN
• Monitoring endpoints return incomplete data
• Running on systems with BusyBox utilities (Alpine, some routers)

⁠🔧 Building from Source

# Clone repository
git clone https://github.com/magicalyak/nzbgetvpn.git
cd nzbgetvpn

# Build for current platform
docker build -t my-nzbgetvpn .

# Multi-architecture build
./scripts/build-multiarch.sh --platforms linux/amd64,linux/arm64

👉 Build guide: scripts/README.md⁠

⁠🔍 Troubleshooting

Container won't start:

• Check docker logs nzbgetvpn
• Verify VPN config file exists
• Ensure required capabilities are added

VPN not connecting:

• Enable debug: DEBUG=true
• Try different server/protocol
• Check VPN credentials

Downloads not working:

• Verify news server configuration
• Check NZBGet logs in web interface
• Test news server connectivity

Permission errors:

• Verify PUID/PGID match your user
• Check directory ownership

Monitoring shows "unknown" status:

• Try the fixed image: magicalyak/nzbgetvpn:fixed
• Check if /dev/net/tun device is mapped correctly
• Enable debug logging: DEBUG=true

👉 Full troubleshooting guide: TROUBLESHOOTING.md⁠

⁠🤝 Contributing & Support

• 🐛 Bug Reports: Bug Report template⁠
• 🚀 Feature Requests: Feature Request template⁠
• ❓ Questions: Question template⁠

⁠🙏 Acknowledgements

Thanks to:

• LinuxServer.io - Base NZBGet image
• OpenVPN & WireGuard - VPN implementations
• Docker Community - Multi-architecture tooling
• jshridha/docker-nzbgetvpn - Original inspiration

⁠📜 License

MIT License - see LICENSE⁠ file for details.

🚀 Ready to get started? Run the Quick Start commands above and have secure downloads in minutes!