Complete documentation refactoring with 57 service docs

- Refactored README.md, getting-started.md, quick-reference.md - Enhanced setup-homelab.sh with 9-step automated process - Created services-overview.md with all stacks - Added comprehensive documentation for 57 services in docs/service-docs/ - All services include: overview, configuration, resources, educational content - Coverage: Core, Infrastructure, Dashboards, Media, Media-Extended, Home Assistant, Productivity, Utilities, Monitoring, Development stacks - Educational focus with links to tutorials, videos, and guides
2026-01-12 18:03:12 -05:00
parent 906e6008ea
commit cba45556c7
69 changed files with 24404 additions and 1522 deletions
--- a/docs/service-docs/gluetun.md
+++ b/docs/service-docs/gluetun.md
@@ -0,0 +1,576 @@
+# Gluetun - VPN Client Container
+
+## Table of Contents
+- [Overview](#overview)
+- [What is Gluetun?](#what-is-gluetun)
+- [Why Use Gluetun?](#why-use-gluetun)
+- [How It Works](#how-it-works)
+- [Configuration in AI-Homelab](#configuration-in-ai-homelab)
+- [Official Resources](#official-resources)
+- [Educational Resources](#educational-resources)
+- [Docker Configuration](#docker-configuration)
+- [Routing Traffic Through Gluetun](#routing-traffic-through-gluetun)
+- [Advanced Topics](#advanced-topics)
+- [Troubleshooting](#troubleshooting)
+
+## Overview
+
+**Category:** Core Infrastructure  
+**Docker Image:** [qmcgaw/gluetun](https://hub.docker.com/r/qmcgaw/gluetun)  
+**Default Stack:** `core.yml`  
+**Web UI:** `http://SERVER_IP:8000` (Control Server)  
+**VPN Provider:** Surfshark (or 60+ others supported)
+
+## What is Gluetun?
+
+Gluetun is a lightweight VPN client container that provides VPN connectivity to other Docker containers. Instead of installing VPN clients on your host or within individual containers, Gluetun acts as a VPN gateway that other containers can route their traffic through.
+
+### Key Features
+- **60+ VPN Providers:** Surfshark, NordVPN, Private Internet Access, ProtonVPN, Mullvad, etc.
+- **Kill Switch:** Blocks all traffic if VPN disconnects
+- **Port Forwarding:** Automatic port forwarding for supported providers
+- **Network Namespace Sharing:** Other containers can use Gluetun's network
+- **Health Checks:** Built-in monitoring and auto-reconnection
+- **DNS Management:** Uses VPN provider's DNS for privacy
+- **HTTP Control Server:** Web UI for monitoring and control
+- **IPv6 Support:** Optional IPv6 routing
+- **Custom Provider Support:** Can configure any OpenVPN/Wireguard provider
+
+## Why Use Gluetun?
+
+1. **Privacy for Torrenting:** Hide your IP when using qBittorrent
+2. **Geo-Restrictions:** Access region-locked content
+3. **Container-Level VPN:** Only specific services use VPN, not entire system
+4. **Kill Switch Protection:** Traffic blocked if VPN fails
+5. **Easy Management:** Single container for all VPN needs
+6. **Provider Flexibility:** Switch between providers easily
+7. **No Split Tunneling Complexity:** Docker handles networking
+8. **Port Forwarding:** Essential for torrent seeding
+
+## How It Works
+
+```
+Internet → VPN Server (Surfshark) → Gluetun Container
+                                         ↓
+                                    Shared Network
+                                         ↓
+                            ┌────────────┴────────────┐
+                            ↓                         ↓
+                      qBittorrent                 Prowlarr
+                  (network: gluetun)          (network: gluetun)
+```
+
+### Network Namespace Sharing
+
+Containers can use Gluetun's network stack:
+
+```yaml
+qbittorrent:
+  image: linuxserver/qbittorrent
+  network_mode: "service:gluetun"  # Use Gluetun's network
+  # This container now routes ALL traffic through VPN
+```
+
+### Traffic Flow
+
+1. **Container makes request** (e.g., qBittorrent downloads torrent)
+2. **Traffic routed** to Gluetun container
+3. **Gluetun encrypts** traffic and sends through VPN tunnel
+4. **VPN server receives** encrypted traffic
+5. **VPN server forwards** request to internet
+6. **Response flows back** through same path
+7. **If VPN fails,** kill switch blocks all traffic
+
+## Configuration in AI-Homelab
+
+### Directory Structure
+
+```
+/opt/stacks/core/gluetun/
+└── (No persistent config needed - all via environment variables)
+```
+
+### Environment Variables
+
+```bash
+# VPN Provider
+VPN_SERVICE_PROVIDER=surfshark
+VPN_TYPE=openvpn  # or wireguard
+
+# Surfshark Credentials
+OPENVPN_USER=your-surfshark-username
+OPENVPN_PASSWORD=your-surfshark-password
+
+# Server Selection
+SERVER_COUNTRIES=USA  # or SERVER_CITIES=New York
+# SERVER_REGIONS=us-east
+
+# Features
+FIREWALL_OUTBOUND_SUBNETS=192.168.1.0/24  # Allow local network
+PORT_FORWARD=on  # Enable port forwarding (if supported)
+DOT=on  # DNS over TLS
+
+# Health Check
+HEALTH_VPN_DURATION_INITIAL=30s
+HEALTH_SUCCESS_WAIT_DURATION=5m
+```
+
+### Surfshark Setup
+
+1. **Get Surfshark Account:**
+   - Sign up at https://surfshark.com
+   - Go to Manual Setup → OpenVPN/Wireguard
+   - Copy service credentials (NOT your login credentials)
+
+2. **Generate Service Credentials:**
+   ```
+   Dashboard → Manual Setup → Credentials
+   Username: random-string
+   Password: random-string
+   ```
+
+3. **Configure Gluetun:**
+   ```bash
+   OPENVPN_USER=your-service-username
+   OPENVPN_PASSWORD=your-service-password
+   ```
+
+### Server Selection Options
+
+```bash
+# By Country
+SERVER_COUNTRIES=USA,Canada
+
+# By City
+SERVER_CITIES=New York,Los Angeles
+
+# By Region (provider-specific)
+SERVER_REGIONS=us-east
+
+# By Hostname (specific server)
+SERVER_HOSTNAMES=us-nyc-st001
+
+# Random selection within criteria
+# Gluetun will pick best server automatically
+```
+
+## Official Resources
+
+- **GitHub:** https://github.com/qdm12/gluetun
+- **Docker Hub:** https://hub.docker.com/r/qmcgaw/gluetun
+- **Wiki:** https://github.com/qdm12/gluetun-wiki
+- **Provider Setup:** https://github.com/qdm12/gluetun-wiki/tree/main/setup/providers
+- **Surfshark Setup:** https://github.com/qdm12/gluetun-wiki/blob/main/setup/providers/surfshark.md
+
+## Educational Resources
+
+### Videos
+- [VPN Explained - What is a VPN? (NetworkChuck)](https://www.youtube.com/watch?v=YEe8vs26ytg)
+- [Docker VPN Setup with Gluetun (Techno Tim)](https://www.youtube.com/watch?v=fpkLvnAKen0)
+- [Secure Your Docker Containers with VPN](https://www.youtube.com/results?search_query=gluetun+docker+vpn)
+- [Port Forwarding for Torrents Explained](https://www.youtube.com/watch?v=jTThdKLHbq8)
+
+### Articles & Guides
+- [Gluetun Wiki - Getting Started](https://github.com/qdm12/gluetun-wiki)
+- [VPN Kill Switch Explained](https://www.comparitech.com/blog/vpn-privacy/vpn-kill-switch/)
+- [Why Use VPN for Torrenting](https://www.cloudwards.net/vpn-for-torrenting/)
+- [Network Namespace Sharing in Docker](https://docs.docker.com/network/)
+
+### Concepts to Learn
+- **VPN (Virtual Private Network):** Encrypted tunnel for internet traffic
+- **Kill Switch:** Blocks traffic if VPN disconnects
+- **Port Forwarding:** Allows incoming connections (important for seeding)
+- **DNS Leak:** When DNS queries bypass VPN (Gluetun prevents this)
+- **Split Tunneling:** Some apps use VPN, others don't (Docker makes this easy)
+- **OpenVPN vs Wireguard:** Two VPN protocols (Wireguard is newer, faster)
+- **Network Namespace:** Container network isolation/sharing
+
+## Docker Configuration
+
+### Complete Service Definition
+
+```yaml
+gluetun:
+  image: qmcgaw/gluetun:latest
+  container_name: gluetun
+  restart: unless-stopped
+  cap_add:
+    - NET_ADMIN  # Required for VPN
+  devices:
+    - /dev/net/tun:/dev/net/tun  # Required for VPN
+  networks:
+    - traefik-network
+  ports:
+    # Gluetun Control Server
+    - "8000:8000"
+    
+    # Ports for services using Gluetun's network
+    - "8080:8080"   # qBittorrent Web UI
+    - "9696:9696"   # Prowlarr Web UI (if through VPN)
+    # Add more as needed
+  
+  volumes:
+    - /opt/stacks/core/gluetun:/gluetun
+  
+  environment:
+    - VPN_SERVICE_PROVIDER=surfshark
+    - VPN_TYPE=openvpn
+    - OPENVPN_USER=${SURFSHARK_USER}
+    - OPENVPN_PASSWORD=${SURFSHARK_PASSWORD}
+    - SERVER_COUNTRIES=USA
+    - FIREWALL_OUTBOUND_SUBNETS=192.168.1.0/24
+    - PORT_FORWARD=on
+    - DOT=on
+    - TZ=America/New_York
+  
+  # Health check
+  healthcheck:
+    test: ["CMD", "wget", "--spider", "-q", "https://api.ipify.org"]
+    interval: 1m
+    timeout: 10s
+    retries: 3
+    start_period: 30s
+```
+
+### Alternative: Wireguard
+
+```yaml
+environment:
+  - VPN_SERVICE_PROVIDER=surfshark
+  - VPN_TYPE=wireguard
+  - WIREGUARD_PRIVATE_KEY=${SURFSHARK_WG_PRIVATE_KEY}
+  - WIREGUARD_ADDRESSES=10.14.0.2/16
+  - SERVER_COUNTRIES=USA
+```
+
+## Routing Traffic Through Gluetun
+
+### Method 1: Network Mode (Recommended)
+
+```yaml
+qbittorrent:
+  image: linuxserver/qbittorrent
+  container_name: qbittorrent
+  network_mode: "service:gluetun"  # Use Gluetun's network
+  depends_on:
+    - gluetun
+  volumes:
+    - /opt/stacks/media/qbittorrent:/config
+    - /mnt/downloads:/downloads
+  environment:
+    - PUID=1000
+    - PGID=1000
+    - TZ=America/New_York
+    - WEBUI_PORT=8080
+  # NO ports section - use Gluetun's ports
+  # NO networks section - uses Gluetun's network
+```
+
+**Important:** When using `network_mode: "service:gluetun"`:
+- Don't define `ports:` on the service
+- Don't define `networks:` on the service
+- Add ports to **Gluetun's** ports section
+- Access WebUI through Gluetun's IP
+
+### Method 2: Custom Network (Advanced)
+
+```yaml
+services:
+  gluetun:
+    # ... gluetun config ...
+    networks:
+      vpn-network:
+        ipv4_address: 172.20.0.2
+  
+  qbittorrent:
+    # ... qbittorrent config ...
+    networks:
+      vpn-network:
+    depends_on:
+      - gluetun
+
+networks:
+  vpn-network:
+    driver: bridge
+    ipam:
+      config:
+        - subnet: 172.20.0.0/16
+```
+
+### Exposing Services Through Traefik
+
+When using `network_mode: "service:gluetun"`, Traefik labels go on **Gluetun**:
+
+```yaml
+gluetun:
+  image: qmcgaw/gluetun
+  # ... other config ...
+  labels:
+    # qBittorrent labels on Gluetun
+    - "traefik.enable=true"
+    - "traefik.http.routers.qbittorrent.rule=Host(`qbit.${DOMAIN}`)"
+    - "traefik.http.routers.qbittorrent.entrypoints=websecure"
+    - "traefik.http.routers.qbittorrent.tls.certresolver=letsencrypt"
+    - "traefik.http.routers.qbittorrent.middlewares=authelia@docker"
+    - "traefik.http.services.qbittorrent.loadbalancer.server.port=8080"
+
+qbittorrent:
+  image: linuxserver/qbittorrent
+  network_mode: "service:gluetun"
+  # NO labels here
+```
+
+## Advanced Topics
+
+### Port Forwarding
+
+Essential for torrent seeding. Supported providers:
+- Private Internet Access (PIA)
+- ProtonVPN
+- Perfect Privacy
+- AirVPN
+
+**Configuration:**
+```bash
+PORT_FORWARD=on
+PORT_FORWARD_ONLY=true  # Only use servers with port forwarding
+```
+
+**Get forwarded port:**
+```bash
+# Check Gluetun logs
+docker logs gluetun | grep "port forwarded"
+
+# Or via control server
+curl http://localhost:8000/v1/openvpn/portforwarded
+```
+
+**Use in qBittorrent:**
+1. Get port from Gluetun logs: `Port forwarded is 12345`
+2. In qBittorrent Settings → Connection → Listening Port → Set to `12345`
+
+### Multiple VPN Connections
+
+Run multiple Gluetun instances for different regions:
+
+```yaml
+gluetun-usa:
+  image: qmcgaw/gluetun
+  container_name: gluetun-usa
+  environment:
+    - SERVER_COUNTRIES=USA
+  # ... rest of config ...
+
+gluetun-uk:
+  image: qmcgaw/gluetun
+  container_name: gluetun-uk
+  environment:
+    - SERVER_COUNTRIES=United Kingdom
+  # ... rest of config ...
+```
+
+### Custom VPN Provider
+
+For providers not natively supported:
+
+```yaml
+environment:
+  - VPN_SERVICE_PROVIDER=custom
+  - VPN_TYPE=openvpn
+  - OPENVPN_CUSTOM_CONFIG=/gluetun/custom.conf
+
+volumes:
+  - ./custom.ovpn:/gluetun/custom.conf:ro
+```
+
+### DNS Configuration
+
+```bash
+# Use VPN provider DNS (default)
+DOT=on  # DNS over TLS
+
+# Use custom DNS
+DNS_ADDRESS=1.1.1.1  # Cloudflare
+
+# Multiple DNS servers
+DNS_ADDRESS=1.1.1.1,8.8.8.8
+```
+
+### Firewall Rules
+
+```bash
+# Allow local network access
+FIREWALL_OUTBOUND_SUBNETS=192.168.1.0/24,172.16.0.0/12
+
+# Block all except VPN
+FIREWALL_VPN_INPUT_PORTS=  # No incoming connections
+
+# Allow specific outbound ports
+FIREWALL_OUTBOUND_PORTS=80,443,53
+```
+
+## Troubleshooting
+
+### Check VPN Connection
+
+```bash
+# View Gluetun logs
+docker logs gluetun
+
+# Check public IP (should show VPN IP)
+docker exec gluetun wget -qO- https://api.ipify.org
+
+# Check if VPN is connected
+docker exec gluetun cat /tmp/gluetun/ip
+```
+
+### Service Can't Access Internet
+
+```bash
+# Check if service is using Gluetun's network
+docker inspect service-name | grep NetworkMode
+
+# Test from within service
+docker exec service-name curl https://api.ipify.org
+
+# Check firewall rules
+docker logs gluetun | grep -i firewall
+
+# Verify outbound subnets
+# Ensure FIREWALL_OUTBOUND_SUBNETS includes your local network
+```
+
+### VPN Keeps Disconnecting
+
+```bash
+# Check provider status
+# Visit your VPN provider's status page
+
+# Try different server
+SERVER_COUNTRIES=Canada  # Change country
+
+# Try Wireguard instead of OpenVPN
+VPN_TYPE=wireguard
+
+# Check system resources
+docker stats gluetun
+
+# View connection logs
+docker logs gluetun | grep -i "connection\|disconnect"
+```
+
+### Port Forwarding Not Working
+
+```bash
+# Check if provider supports it
+# Only certain providers support port forwarding
+
+# Verify it's enabled
+docker logs gluetun | grep -i "port forward"
+
+# Get forwarded port
+curl http://localhost:8000/v1/openvpn/portforwarded
+
+# Check if server supports it
+PORT_FORWARD_ONLY=true  # Force port-forward-capable servers
+```
+
+### DNS Leaks
+
+```bash
+# Test DNS
+docker exec gluetun nslookup google.com
+
+# Check DNS configuration
+docker exec gluetun cat /etc/resolv.conf
+
+# Enable DNS over TLS
+DOT=on
+```
+
+### Can't Access Service WebUI
+
+```bash
+# If using network_mode: "service:gluetun"
+# Access via: http://GLUETUN_IP:PORT
+
+# Check Gluetun's IP
+docker inspect gluetun | grep IPAddress
+
+# Verify ports are exposed on Gluetun
+docker ps | grep gluetun
+
+# Check if service is running
+docker ps | grep service-name
+```
+
+### Kill Switch Testing
+
+```bash
+# Stop VPN (simulate disconnection)
+docker exec gluetun killall openvpn
+
+# Try accessing internet from connected service
+docker exec qbittorrent curl https://api.ipify.org
+# Should fail or timeout
+
+# Restart VPN
+docker restart gluetun
+```
+
+## Security Best Practices
+
+1. **Use Strong Credentials:** Never share your VPN credentials
+2. **Enable Kill Switch:** Always use Gluetun's built-in kill switch
+3. **DNS over TLS:** Enable `DOT=on` to prevent DNS leaks
+4. **Firewall Rules:** Restrict outbound traffic to necessary subnets only
+5. **Regular Updates:** Keep Gluetun updated for security patches
+6. **Provider Selection:** Use reputable VPN providers (no-logs policy)
+7. **Monitor Logs:** Regularly check for connection issues
+8. **Test IP Leaks:** Verify your IP is hidden: https://ipleak.net
+9. **Port Security:** Only forward ports when necessary
+10. **Split Tunneling:** Only route traffic that needs VPN through Gluetun
+
+## Provider Comparisons
+
+### Surfshark
+- **Pros:** Unlimited devices, fast, affordable
+- **Cons:** No port forwarding
+- **Best for:** General privacy, torrenting (without seeding priority)
+
+### Private Internet Access (PIA)
+- **Pros:** Port forwarding, proven no-logs
+- **Cons:** US-based
+- **Best for:** Torrenting with seeding
+
+### Mullvad
+- **Pros:** Anonymous (no email required), port forwarding
+- **Cons:** More expensive
+- **Best for:** Maximum privacy
+
+### ProtonVPN
+- **Pros:** Port forwarding, excellent privacy
+- **Cons:** Expensive for full features
+- **Best for:** Privacy-focused users
+
+### NordVPN
+- **Pros:** Fast, large server network
+- **Cons:** No port forwarding
+- **Best for:** General use, streaming
+
+## Summary
+
+Gluetun is essential for:
+- Protecting torrent traffic (qBittorrent, Transmission)
+- Bypassing geo-restrictions
+- Hiding your IP from specific services
+- Maintaining privacy for indexers (Prowlarr, Jackett)
+- Professional homelab security
+
+By routing only specific containers through the VPN, you maintain:
+- Fast local network access for other services
+- Privacy where it matters
+- Simple, maintainable configuration
+- Automatic failover protection
+
+Remember: Always verify your VPN is working correctly by checking your public IP from containers using Gluetun's network. The IP should match your VPN provider's IP, not your home IP.