feat: merge upstream dev branch

- Add Gluetun dynamic VPN-to-HTTP proxy provider - Add remote services and authentication system - Add country code utilities - Add Docker binary detection - Update proxy providers
2026-03-10 08:29:00 +00:00 · 2025-11-25 20:14:48 +00:00
parent 2d4bf140fa
commit 965482a1e4
27 changed files with 6678 additions and 98 deletions
--- a/docs/GLUETUN.md
+++ b/docs/GLUETUN.md
@@ -0,0 +1,159 @@
+# Gluetun VPN Proxy
+
+Gluetun provides Docker-managed VPN proxies supporting 50+ VPN providers.
+
+## Prerequisites
+
+**Docker must be installed and running.**
+
+```bash
+# Linux
+curl -fsSL https://get.docker.com | sh
+sudo usermod -aG docker $USER  # Then log out/in
+
+# Windows/Mac
+# Install Docker Desktop: https://www.docker.com/products/docker-desktop/
+```
+
+## Quick Start
+
+### 1. Configuration
+
+Add to `~/.config/unshackle/unshackle.yaml`:
+
+```yaml
+proxy_providers:
+  gluetun:
+    providers:
+      nordvpn:
+        vpn_type: wireguard
+        credentials:
+          private_key: YOUR_PRIVATE_KEY
+```
+
+### 2. Usage
+
+Use 2-letter country codes directly:
+
+```bash
+uv run unshackle dl SERVICE CONTENT --proxy gluetun:nordvpn:us
+uv run unshackle dl SERVICE CONTENT --proxy gluetun:nordvpn:uk
+```
+
+Format: `gluetun:provider:region`
+
+## Provider Credential Requirements
+
+Each provider has different credential requirements. See the [Gluetun Wiki](https://github.com/qdm12/gluetun-wiki/tree/main/setup/providers) for complete details.
+
+| Provider | VPN Type | Required Credentials |
+|----------|----------|---------------------|
+| NordVPN | WireGuard | `private_key` only |
+| ProtonVPN | WireGuard | `private_key` only |
+| Windscribe | WireGuard | `private_key`, `addresses`, `preshared_key` (all required) |
+| Surfshark | WireGuard | `private_key`, `addresses` |
+| Mullvad | WireGuard | `private_key`, `addresses` |
+| IVPN | WireGuard | `private_key`, `addresses` |
+| ExpressVPN | OpenVPN | `username`, `password` (no WireGuard support) |
+| Any | OpenVPN | `username`, `password` |
+
+### Configuration Examples
+
+**NordVPN/ProtonVPN** (only private_key needed):
+```yaml
+providers:
+  nordvpn:
+    vpn_type: wireguard
+    credentials:
+      private_key: YOUR_PRIVATE_KEY
+```
+
+**Windscribe** (all three credentials required):
+```yaml
+providers:
+  windscribe:
+    vpn_type: wireguard
+    credentials:
+      private_key: YOUR_PRIVATE_KEY
+      addresses: 10.x.x.x/32
+      preshared_key: YOUR_PRESHARED_KEY  # Required, can be empty string
+```
+
+**OpenVPN** (any provider):
+```yaml
+providers:
+  expressvpn:
+    vpn_type: openvpn
+    credentials:
+      username: YOUR_USERNAME
+      password: YOUR_PASSWORD
+```
+
+## Server Selection
+
+Most providers use `SERVER_COUNTRIES`, but some use `SERVER_REGIONS`:
+
+| Variable | Providers |
+|----------|-----------|
+| `SERVER_COUNTRIES` | NordVPN, ProtonVPN, Surfshark, Mullvad, ExpressVPN, and most others |
+| `SERVER_REGIONS` | Windscribe, VyprVPN, VPN Secure |
+
+Unshackle handles this automatically - just use 2-letter country codes.
+
+## Global Settings
+
+```yaml
+proxy_providers:
+  gluetun:
+    providers: {...}
+    base_port: 8888           # Starting port (default: 8888)
+    auto_cleanup: true        # Remove containers on exit (default: true)
+    verify_ip: true           # Verify IP matches region (default: true)
+    container_prefix: "unshackle-gluetun"
+    auth_user: username       # Proxy auth (optional)
+    auth_password: password
+```
+
+## Features
+
+- **Container Reuse**: First request takes 10-30s; subsequent requests are instant
+- **IP Verification**: Automatically verifies VPN exit IP matches requested region
+- **Concurrent Sessions**: Multiple downloads share the same container
+- **Specific Servers**: Use `--proxy gluetun:nordvpn:us1239` for specific server selection
+
+## Container Management
+
+```bash
+# View containers
+docker ps | grep unshackle-gluetun
+
+# Check logs
+docker logs unshackle-gluetun-nordvpn-us
+
+# Remove all containers
+docker ps -a | grep unshackle-gluetun | awk '{print $1}' | xargs docker rm -f
+```
+
+## Troubleshooting
+
+### Docker Permission Denied (Linux)
+```bash
+sudo usermod -aG docker $USER
+# Then log out and log back in
+```
+
+### VPN Connection Failed
+Check container logs for specific errors:
+```bash
+docker logs unshackle-gluetun-nordvpn-us
+```
+
+Common issues:
+- Invalid/missing credentials
+- Windscribe requires `preshared_key` (can be empty string)
+- VPN provider server issues
+
+## Resources
+
+- [Gluetun Wiki](https://github.com/qdm12/gluetun-wiki) - Official provider documentation
+- [Gluetun GitHub](https://github.com/qdm12/gluetun)