VPN Exit Controller¶

A sophisticated VPN management system that provides dual-mode access to country-specific VPN routing: Tailscale Exit Nodes for network-level routing and Proxy URLs for application-level routing. Features intelligent load balancing, automatic failover, and performance monitoring with a modern Next.js dashboard.

🚀 Overview¶

The VPN Exit Controller manages Docker-based VPN containers that function as both Tailscale exit nodes and proxy servers across multiple countries. This dual approach provides maximum flexibility:

🌐 Tailscale Exit Nodes: Route entire networks or devices through VPN containers via Tailscale's mesh network
🔗 Proxy Endpoints: Route individual applications through HTTP/HTTPS/SOCKS5 proxies for specific use cases
🤝 Complementary Approaches: Use both simultaneously for different needs - network routing for general use, proxies for development/testing

✨ Key Features¶

🌐 Dual-Mode VPN Access¶

Tailscale Exit Nodes: Full network-level routing through VPN containers in the Tailscale mesh
HTTP/HTTPS/SOCKS5 Proxies: Application-level routing with direct Tailscale IP access
Legacy Proxy URLs: Country-specific endpoints like proxy-us.rbnk.uk, proxy-de.rbnk.uk

🎛️ Management & Monitoring¶

Modern Web Dashboard: Professional Next.js interface at https://vpn.rbnk.uk with real-time monitoring
⚖️ Intelligent Load Balancing: 5 strategies including health-score based routing
🔄 Automatic Failover: Seamless switching when nodes become unavailable
📊 Performance Monitoring: Real-time speed testing and latency monitoring

🔧 Infrastructure¶

🔒 SSL Security: Automatic certificate management with Let's Encrypt
🐳 Container-Based: Docker containers with NordVPN + Tailscale mesh networking
📈 Auto-Scaling: Automatic node scaling based on connection load
🛡️ Health Monitoring: Comprehensive health checks and recovery procedures
🎨 Responsive Design: Dashboard works on desktop, tablet, and mobile devices

🏗️ Architecture Overview¶

Dual-Mode Access Architecture¶

┌─ Tailscale Exit Nodes ─────────────────────────────────┐ ┌─ Proxy URLs ─────────────────────────────────────┐
│                                                         │ │                                                   │
│  Device/Network → Tailscale Mesh → VPN Container       │ │  Application → Cloudflare → Traefik → HAProxy    │
│                   (100.x.x.x)      (NordVPN Exit)      │ │               (rbnk.uk)     (SSL)    (Routing)   │
│                                                         │ │                                        ↓          │
└─────────────────────────────────────────────────────────┘ │                               VPN Container      │
                                                             │               (Squid/Dante Proxies)              │
                                                             └───────────────────────────────────────────────────┘

Core Components¶

Next.js Dashboard: Modern web interface for VPN node management and monitoring
FastAPI Application: RESTful API for managing VPN nodes and load balancing
Docker VPN Containers: Multi-service containers providing:
Tailscale Exit Node: Full network routing via Tailscale mesh
Squid HTTP/HTTPS Proxy: Web traffic routing on port 3128
Dante SOCKS5 Proxy: Application-level tunneling on port 1080
NordVPN Connection: Secure VPN tunnel to country-specific servers
HAProxy: Country-based proxy routing for legacy proxy URLs
Traefik: SSL termination and reverse proxy with automatic certificates
Tailscale Mesh: Secure networking for both exit nodes and direct proxy access
Redis: Metrics storage and session state management

🚀 Quick Start¶

Prerequisites¶

Proxmox VE with LXC container support
Ubuntu 22.04 LTS
Docker and Docker Compose
Node.js 18+ and npm (for dashboard)
NordVPN service credentials
Cloudflare domain and API token

Basic Setup¶

Clone the repository:

git clone https://your-repo/vpn-exit-controller.git
cd vpn-exit-controller

Set up Python environment:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Configure environment variables:

cp .env.example .env
# Edit .env with your NordVPN credentials, Tailscale auth key, etc.

Start the services:

# Start infrastructure
cd traefik && docker-compose -f docker-compose.traefik.yml up -d
cd ../proxy && docker-compose up -d

# Start the API
systemctl start vpn-controller

# Start the dashboard
cd dashboard && docker-compose up -d

Web Dashboard¶

Access the modern web dashboard at: - Production: https://vpn.rbnk.uk - Local Development: http://localhost:3000

The dashboard provides: - Real-time Monitoring: Live updates every 3 seconds - Country Selection: Visual grid with flags - One-click Controls: Start, stop, restart nodes - Performance Metrics: CPU, memory, network stats - Professional UI: Dark mode with responsive design

API Usage¶

# Dashboard endpoints (public, no auth required)
curl https://vpn.rbnk.uk/api/stats
curl https://vpn.rbnk.uk/api/countries
curl https://vpn.rbnk.uk/api/nodes

# Management endpoints (require authentication)
curl -u admin:Bl4ckMagic!2345erver https://vpn.rbnk.uk/api/status

# Start a VPN node
curl -X POST -u admin:Bl4ckMagic!2345erver \
  https://vpn.rbnk.uk/api/nodes/us/start \
  -H "Content-Type: application/json" \
  -d '{"server": "us9999.nordvpn.com"}'

# Get best node for a country
curl -u admin:Bl4ckMagic!2345erver \
  https://vpn.rbnk.uk/api/load-balancer/best-node/us

🌍 Available Countries¶

The system supports VPN containers in 25+ countries, accessible via both Tailscale exit nodes and proxy endpoints:

Country	Code	Tailscale Exit Node	Direct Proxy Access	Legacy Proxy URLs	Flag
United States	`us`	Route via Tailscale	`100.x.x.x:3128/1080`	`proxy-us.rbnk.uk`	🇺🇸
Germany	`de`	Route via Tailscale	`100.x.x.x:3128/1080`	`proxy-de.rbnk.uk`	🇩🇪
Japan	`jp`	Route via Tailscale	`100.x.x.x:3128/1080`	`proxy-jp.rbnk.uk`	🇯🇵
United Kingdom	`uk`	Route via Tailscale	`100.125.27.111:3128/1080`	`proxy-uk.rbnk.uk`	🇬🇧
And 20+ more...

Note: Tailscale IPs are dynamic and can be discovered via the API

🔌 Usage Approaches¶

Choose the approach that best fits your use case:

🌐 Approach 1: Tailscale Exit Nodes (Recommended)¶

Best for: Full network routing, device-level VPN, multiple applications

# Enable Tailscale exit node routing (macOS/Linux)
tailscale up --exit-node=exit-us-server123

# All traffic from your device now routes through US VPN container
curl https://ipinfo.io/ip  # Shows US IP

Benefits: - Routes all network traffic through VPN - Works with any application (no proxy configuration needed) - Perfect for mobile devices, entire computers, or Docker containers - Automatic DNS resolution through VPN - Zero application configuration required

🔗 Approach 2: Direct Proxy Access via Tailscale¶

Best for: Development, testing, specific applications

# Get current Tailscale IPs for active nodes
curl -u admin:password https://vpn.rbnk.uk/api/nodes

# Use direct Tailscale IP for HTTP proxy (discovered from API)
curl -x http://100.86.140.98:3128 https://httpbin.org/ip

# Use SOCKS5 proxy
curl --socks5 100.86.140.98:1080 https://httpbin.org/ip

# UK example
curl -x http://100.125.27.111:3128 https://httpbin.org/ip

Benefits: - Direct connection to VPN containers via Tailscale mesh - No internet routing through proxy infrastructure - Lower latency and better performance - Ideal for development and scripting

🌍 Approach 3: Legacy Proxy URLs¶

Best for: External access, non-Tailscale networks

# Use legacy country-specific URLs
curl -x http://proxy-us.rbnk.uk:8080 https://httpbin.org/ip
curl --socks5 proxy-de.rbnk.uk:1080 https://httpbin.org/ip
curl -x http://proxy-uk.rbnk.uk:8132 https://httpbin.org/ip

Benefits: - Accessible from any internet connection - No Tailscale client required - SSL/TLS termination via Traefik

Browser Configuration¶

For HTTP Proxy: 1. Go to Browser Proxy Settings 2. Select "Manual proxy configuration" 3. HTTP Proxy: proxy-de.rbnk.uk (or desired country) 4. Port: 8129 (for Germany, 8132 for UK, adjust for other countries) 5. Check "Use this proxy server for all protocols" 6. No username/password required

Programming Examples¶

Python with HTTP Proxy (No Auth):

import requests

# HTTP proxy - no authentication required
proxies = {
    'http': 'http://proxy-de.rbnk.uk:8129',
    'https': 'http://proxy-de.rbnk.uk:8129'
}

# UK proxy example
uk_proxies = {
    'http': 'http://proxy-uk.rbnk.uk:8132',
    'https': 'http://proxy-uk.rbnk.uk:8132'
}

response = requests.get('https://httpbin.org/ip', proxies=proxies)
print(response.json())

Python with SOCKS5 Proxy:

import requests

# SOCKS5 proxy - requires requests[socks]
proxies = {
    'http': 'socks5://proxy-jp.rbnk.uk:1082',
    'https': 'socks5://proxy-jp.rbnk.uk:1082'
}

# UK SOCKS5 example
uk_socks_proxies = {
    'http': 'socks5://proxy-uk.rbnk.uk:1084',
    'https': 'socks5://proxy-uk.rbnk.uk:1084'
}

response = requests.get('https://httpbin.org/ip', proxies=proxies)
print(response.json())

Node.js with HTTP Proxy:

const axios = require('axios');

const proxy = {
  host: 'proxy-de.rbnk.uk',
  port: 8129
  // No authentication required
};

// UK proxy example
const ukProxy = {
  host: 'proxy-uk.rbnk.uk',
  port: 8132
};

axios.get('https://httpbin.org/ip', { proxy })
  .then(response => console.log(response.data));

📁 Directory Structure¶

/opt/vpn-exit-controller/
├── dashboard/             # Next.js web dashboard
│   ├── src/              # Dashboard source code
│   ├── public/           # Static assets
│   ├── Dockerfile        # Dashboard container
│   └── docker-compose.yml # Dashboard deployment
├── api/                  # FastAPI application
│   ├── main.py          # Main application entry point
│   ├── models/          # Data models and schemas
│   ├── routes/          # API route handlers
│   └── services/        # Business logic services
├── configs/             # VPN configuration files
├── traefik/            # Traefik reverse proxy configuration
│   ├── docker-compose.traefik.yml
│   ├── traefik.yml
│   └── dynamic/        # Dynamic configuration
├── proxy/              # HAProxy configuration
│   ├── docker-compose.yml
│   └── haproxy.cfg
├── scripts/            # Utility scripts
├── venv/               # Python virtual environment
├── .env                # Environment variables
└── requirements.txt    # Python dependencies

⚙️ Configuration¶

Environment Variables¶

Key configuration options in .env:

# NordVPN Credentials
NORDVPN_USER=your_service_username
NORDVPN_PASS=your_service_password

# Tailscale
TAILSCALE_AUTH_KEY=your_tailscale_auth_key

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379

# API Authentication
API_USERNAME=admin
API_PASSWORD=Bl4ckMagic!2345erver

# Cloudflare
CF_API_TOKEN=your_cloudflare_api_token

Advanced Configuration¶

Load Balancing Strategy: Set via API or environment variables
Health Check Intervals: Configurable per-node monitoring
Auto-scaling Thresholds: Connection-based scaling triggers
Speed Test Frequency: Configurable performance monitoring

📊 Monitoring & Health Checks¶

System Status¶

# Check overall system health
curl -u admin:Bl4ckMagic!2345erver http://localhost:8080/api/health

# Get detailed metrics
curl -u admin:Bl4ckMagic!2345erver http://localhost:8080/api/metrics

# View active nodes
curl -u admin:Bl4ckMagic!2345erver http://localhost:8080/api/nodes

Service Status¶

# Check systemd service
systemctl status vpn-controller

# View logs
journalctl -u vpn-controller -f

# Check Docker containers
docker ps --filter name=vpn-exit

🔧 Troubleshooting¶

Common Issues¶

VPN Node Won't Start:

# Check NordVPN credentials
docker logs vpn-exit-us

# Verify Tailscale connectivity
tailscale status

Proxy Connection Fails:

# Test HAProxy configuration
docker exec vpn-proxy haproxy -c -f /usr/local/etc/haproxy/haproxy.cfg

# Check Traefik routing
curl -H "Host: proxy-us.rbnk.uk" http://localhost

Load Balancing Issues:

# Check Redis connectivity
redis-cli ping

# View load balancing stats
curl -u admin:Bl4ckMagic!2345erver http://localhost:8080/api/load-balancer/stats

📚 Documentation¶

🎛️ Dashboard Guide - Complete dashboard documentation
📋 API Documentation - Complete API reference
🏗️ Architecture Guide - Technical architecture details
🚀 Deployment Guide - Setup and installation
🌐 Proxy Usage - How to use proxy URLs
⚖️ Load Balancing - Load balancing strategies
🔒 Security Guide - Security best practices
🔧 Troubleshooting - Common issues and solutions
🛠️ Maintenance - Operations and maintenance

👥 Development¶

Local Development¶

API Development:

# Activate virtual environment
source venv/bin/activate

# Install development dependencies
pip install -r requirements-dev.txt

# Run in development mode
uvicorn api.main:app --reload --host 0.0.0.0 --port 8080

Dashboard Development:

# Navigate to dashboard directory
cd dashboard

# Install dependencies
npm install

# Start development server
npm run dev

# Access at http://localhost:3000

Testing¶

# Run unit tests
pytest tests/

# Run integration tests
pytest tests/integration/

# Test specific functionality
pytest tests/test_load_balancer.py -v

Contributing¶

Fork the repository
Create a feature branch: git checkout -b feature/new-feature
Make changes and add tests
Commit changes: git commit -am 'Add new feature'
Push to branch: git push origin feature/new-feature
Submit a pull request

📄 License¶

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support¶

📖 Documentation: Check the comprehensive guides in this repository
🐛 Issues: Report bugs via GitHub Issues
💬 Discussions: Join GitHub Discussions for questions and ideas
📧 Contact: For enterprise support and custom deployments

Built with ❤️ for reliable, intelligent VPN infrastructure management