VPN Exit Controller - Deployment Guide¶

This comprehensive guide covers the complete deployment of the VPN Exit Controller system from scratch, including infrastructure setup, dependencies, configuration, and testing procedures.

Table of Contents¶

Infrastructure Prerequisites
System Dependencies
Application Setup
Service Configuration
Network and DNS Setup
Container Infrastructure
Testing and Verification
Troubleshooting

1. Infrastructure Prerequisites¶

1.1 Proxmox VE Setup Requirements¶

Hardware Specifications (Minimum)¶

CPU: 4 cores (Intel/AMD with virtualization support)
RAM: 8GB (16GB recommended for multiple VPN nodes)
Storage: 100GB SSD (for container and Docker images)
Network: 1Gbps NIC with stable internet connection

Proxmox VE Installation¶

Install Proxmox VE 8.0+ on the host system
Configure network bridges in Proxmox web interface
Set up storage pools for container data

1.2 LXC Container Configuration¶

Create LXC Container¶

# Create Ubuntu 22.04 LXC container
pct create 201 local:vztmpl/ubuntu-22.04-standard_22.04-1_amd64.tar.zst \
  --hostname vpn-controller \
  --memory 4096 \
  --cores 2 \
  --rootfs local-lvm:32 \
  --net0 name=eth0,bridge=vmbr1,ip=10.10.10.20/24,gw=10.10.10.1 \
  --nameserver 1.1.1.1 \
  --onboot 1 \
  --unprivileged 0 \
  --features nesting=1,keyctl=1

Essential Container Features¶

nesting=1: Enables Docker containers within LXC
keyctl=1: Required for Docker operations
unprivileged=0: Runs as privileged container for Docker access

Network Configuration¶

# Configure static network in container
cat > /etc/netplan/01-netcfg.yaml << 'EOF'
network:
  version: 2
  ethernets:
    eth0:
      addresses:
        - 10.10.10.20/24
      gateway4: 10.10.10.1
      nameservers:
        addresses: [1.1.1.1, 8.8.8.8]
EOF

netplan apply

AppArmor Configuration (if needed)¶

# On Proxmox host, disable AppArmor for container
echo "lxc.apparmor.profile: unconfined" >> /etc/pve/lxc/201.conf
pct reboot 201

2. System Dependencies¶

2.1 Ubuntu 22.04 LXC Base Setup¶

# Update system packages
apt update && apt upgrade -y

# Install essential system packages
apt install -y \
    curl \
    wget \
    git \
    nano \
    htop \
    net-tools \
    iptables \
    ca-certificates \
    gnupg \
    lsb-release \
    software-properties-common \
    apt-transport-https

2.2 Docker Installation and Configuration¶

# Add Docker's official GPG key
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# Add Docker repository
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker
apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Start and enable Docker
systemctl start docker
systemctl enable docker

# Add user to docker group (if not running as root)
usermod -aG docker $USER

Docker Configuration¶

# Configure Docker daemon
cat > /etc/docker/daemon.json << 'EOF'
{
    "log-driver": "json-file",
    "log-opts": {
        "max-size": "10m",
        "max-file": "3"
    },
    "dns": ["1.1.1.1", "8.8.8.8"],
    "storage-driver": "overlay2"
}
EOF

systemctl restart docker

2.3 Python 3.10 with Virtual Environment¶

# Install Python 3.10 and pip
apt install -y python3.10 python3.10-venv python3-pip

# Verify Python installation
python3 --version

2.4 Redis Server Installation¶

# Install Redis
apt install -y redis-server

# Configure Redis
sed -i 's/bind 127.0.0.1 ::1/bind 127.0.0.1/' /etc/redis/redis.conf
sed -i 's/# requirepass foobared/requirepass vpn-redis-2024/' /etc/redis/redis.conf

# Start and enable Redis
systemctl start redis-server
systemctl enable redis-server

# Test Redis
redis-cli ping

2.5 Additional System Packages¶

# Install network utilities
apt install -y \
    openvpn \
    iptables-persistent \
    netfilter-persistent \
    bridge-utils \
    iproute2 \
    tcpdump \
    nmap \
    jq

3. Application Setup¶

3.1 Repository Cloning and Directory Setup¶

# Create application directory
mkdir -p /opt/vpn-exit-controller
cd /opt/vpn-exit-controller

# Clone repository (adjust URL as needed)
git clone https://github.com/your-repo/vpn-exit-controller.git .

# Set proper permissions
chown -R root:root /opt/vpn-exit-controller
chmod +x scripts/*.sh
chmod +x start.sh

3.2 Python Virtual Environment Setup¶

# Create virtual environment
cd /opt/vpn-exit-controller
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate

# Install Python dependencies
pip install --upgrade pip
pip install -r api/requirements.txt

# Verify installations
pip list

3.3 Environment Variable Configuration¶

# Create .env file
cat > /opt/vpn-exit-controller/.env << 'EOF'
# Application Settings
SECRET_KEY=your-super-secret-key-change-this-in-production
ADMIN_USER=admin
ADMIN_PASS=Bl4ckMagic!2345erver

# Tailscale Configuration
TAILSCALE_AUTHKEY=tskey-auth-your-tailscale-key-here

# NordVPN Credentials
NORDVPN_USERNAME=your-nordvpn-username
NORDVPN_PASSWORD=your-nordvpn-password

# Redis Configuration
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=vpn-redis-2024

# Cloudflare DNS API (for SSL certificates)
[email protected]
CLOUDFLARE_API_KEY=your-cloudflare-api-key

# Domain Configuration
DOMAIN=rbnk.uk
API_DOMAIN=vpn-api.rbnk.uk
EOF

# Secure the .env file
chmod 600 /opt/vpn-exit-controller/.env

3.4 NordVPN Configuration Setup¶

# Create NordVPN authentication file
mkdir -p /opt/vpn-exit-controller/configs
cat > /opt/vpn-exit-controller/configs/auth.txt << 'EOF'
your-nordvpn-username
your-nordvpn-password
EOF

chmod 600 /opt/vpn-exit-controller/configs/auth.txt

# Download NordVPN configuration files
cd /opt/vpn-exit-controller
bash scripts/download-nordvpn-configs.sh

4. Service Configuration¶

4.1 NordVPN Service Credentials Setup¶

The NordVPN configurations are already present in the /opt/vpn-exit-controller/configs/vpn/ directory. Ensure your NordVPN credentials are properly configured:

# Verify NordVPN configs exist
ls -la /opt/vpn-exit-controller/configs/vpn/

# Test a configuration (optional)
openvpn --config /opt/vpn-exit-controller/configs/vpn/us.ovpn \
        --auth-user-pass /opt/vpn-exit-controller/configs/auth.txt \
        --daemon

4.2 Tailscale Installation and Configuration¶

# Install Tailscale
curl -fsSL https://tailscale.com/install.sh | sh

# Start Tailscale daemon
systemctl start tailscaled
systemctl enable tailscaled

# Authenticate with Tailscale (use your auth key from .env)
tailscale up --authkey=tskey-auth-your-key-here \
             --advertise-exit-node \
             --hostname=vpn-controller

# Verify Tailscale status
tailscale status
tailscale ip -4

4.3 Systemd Service Installation¶

# Create the systemd service file
cat > /etc/systemd/system/vpn-controller.service << 'EOF'
[Unit]
Description=VPN Exit Controller API
After=docker.service tailscaled.service redis-server.service
Requires=docker.service
Wants=tailscaled.service redis-server.service

[Service]
Type=simple
ExecStart=/opt/vpn-exit-controller/start.sh
Restart=on-failure
RestartSec=10
User=root
WorkingDirectory=/opt/vpn-exit-controller
Environment=PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

[Install]
WantedBy=multi-user.target
EOF

# Reload systemd and enable service
systemctl daemon-reload
systemctl enable vpn-controller

4.4 Firewall and iptables Configuration¶

# Configure iptables for VPN traffic
cat > /etc/iptables/rules.v4 << 'EOF'
*nat
:PREROUTING ACCEPT [0:0]
:INPUT ACCEPT [0:0]
:OUTPUT ACCEPT [0:0]
:POSTROUTING ACCEPT [0:0]

# NAT rules for VPN traffic
-A POSTROUTING -s 10.0.0.0/8 -o tun+ -j MASQUERADE
-A POSTROUTING -s 172.16.0.0/12 -o tun+ -j MASQUERADE
-A POSTROUTING -s 192.168.0.0/16 -o tun+ -j MASQUERADE

COMMIT

*filter
:INPUT ACCEPT [0:0]
:FORWARD ACCEPT [0:0]
:OUTPUT ACCEPT [0:0]

# Allow loopback
-A INPUT -i lo -j ACCEPT

# Allow established connections
-A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT

# Allow SSH
-A INPUT -p tcp --dport 22 -j ACCEPT

# Allow HTTP/HTTPS
-A INPUT -p tcp --dport 80 -j ACCEPT
-A INPUT -p tcp --dport 443 -j ACCEPT

# Allow API port
-A INPUT -p tcp --dport 8080 -j ACCEPT

# Allow Tailscale
-A INPUT -p udp --dport 41641 -j ACCEPT

# Forward VPN traffic
-A FORWARD -i tun+ -j ACCEPT
-A FORWARD -o tun+ -j ACCEPT

# Drop invalid packets
-A INPUT -m state --state INVALID -j DROP

COMMIT
EOF

# Apply iptables rules
iptables-restore < /etc/iptables/rules.v4
netfilter-persistent save

5. Network and DNS Setup¶

5.1 Cloudflare DNS Configuration¶

Configure the following DNS records in your Cloudflare dashboard for rbnk.uk:

# Main API endpoint
vpn-api.rbnk.uk     A       10.10.10.20     (Proxied: Yes)

# Proxy endpoints for each country
proxy-us.rbnk.uk    A       10.10.10.20     (Proxied: Yes)
proxy-uk.rbnk.uk    A       10.10.10.20     (Proxied: Yes)
proxy-de.rbnk.uk    A       10.10.10.20     (Proxied: Yes)
proxy-jp.rbnk.uk    A       10.10.10.20     (Proxied: Yes)
proxy-ca.rbnk.uk    A       10.10.10.20     (Proxied: Yes)
proxy-au.rbnk.uk    A       10.10.10.20     (Proxied: Yes)
proxy-nl.rbnk.uk    A       10.10.10.20     (Proxied: Yes)
proxy-fr.rbnk.uk    A       10.10.10.20     (Proxied: Yes)
proxy-it.rbnk.uk    A       10.10.10.20     (Proxied: Yes)
proxy-es.rbnk.uk    A       10.10.10.20     (Proxied: Yes)

# Traefik dashboard (optional)
traefik.rbnk.uk     A       10.10.10.20     (Proxied: Yes)

5.2 SSL Certificate Configuration¶

The Traefik configuration handles SSL certificates automatically via Let's Encrypt and Cloudflare DNS challenge:

# Ensure acme.json has correct permissions
mkdir -p /opt/vpn-exit-controller/traefik/letsencrypt
touch /opt/vpn-exit-controller/traefik/letsencrypt/acme.json
chmod 600 /opt/vpn-exit-controller/traefik/letsencrypt/acme.json

6. Container Infrastructure¶

6.1 Docker Network Setup¶

# Create custom Docker networks
docker network create vpn-network --subnet=172.20.0.0/16
docker network create traefik-network --subnet=172.21.0.0/16

6.2 Build VPN Node Container¶

# Build the VPN node Docker image
cd /opt/vpn-exit-controller/vpn-node
docker build -t vpn-exit-node:latest .

# Verify image was built
docker images | grep vpn-exit-node

6.3 Traefik Deployment¶

# Start Traefik container
cd /opt/vpn-exit-controller/traefik
docker compose -f docker-compose.traefik.yml up -d

# Check Traefik status
docker ps | grep traefik
docker logs traefik

6.4 HAProxy Deployment¶

# Start HAProxy and proxy infrastructure
cd /opt/vpn-exit-controller/proxy
docker compose up -d

# Verify HAProxy is running
docker ps | grep haproxy
curl -s http://localhost:8404  # HAProxy stats page

6.5 Main Application Deployment¶

# Start the main application stack
cd /opt/vpn-exit-controller
docker compose up -d

# Start the systemd service
systemctl start vpn-controller
systemctl status vpn-controller

7. Testing and Verification¶

7.1 Health Check Procedures¶

# Check all services are running
systemctl status vpn-controller
systemctl status docker
systemctl status tailscaled
systemctl status redis-server

# Check Docker containers
docker ps -a

# Check application logs
journalctl -u vpn-controller -f
docker logs vpn-api
docker logs vpn-redis

7.2 API Endpoint Testing¶

# Test API status endpoint
curl -u admin:Bl4ckMagic!2345erver http://localhost:8080/api/status

# Test via domain (after DNS propagation)
curl -u admin:Bl4ckMagic!2345erver https://vpn-api.rbnk.uk/api/status

# Test node management endpoints
curl -u admin:Bl4ckMagic!2345erver https://vpn-api.rbnk.uk/api/nodes

# Test metrics endpoint
curl -u admin:Bl4ckMagic!2345erver https://vpn-api.rbnk.uk/api/metrics

7.3 Proxy URL Verification¶

# Test HTTP proxy endpoints
curl -x proxy-us.rbnk.uk:80 http://ipinfo.io/country
curl -x proxy-uk.rbnk.uk:80 http://ipinfo.io/country
curl -x proxy-de.rbnk.uk:80 http://ipinfo.io/country

# Test SOCKS5 proxy (if configured)
curl --socks5 proxy-us.rbnk.uk:1080 http://ipinfo.io/country

7.4 Performance Testing¶

# Speed test through proxy
curl -x proxy-us.rbnk.uk:80 -w "@curl-format.txt" -o /dev/null -s http://speedtest.net/mini.php

# Create curl format file for detailed timing
cat > curl-format.txt << 'EOF'
     time_namelookup:  %{time_namelookup}\n
        time_connect:  %{time_connect}\n
     time_appconnect:  %{time_appconnect}\n
    time_pretransfer:  %{time_pretransfer}\n
       time_redirect:  %{time_redirect}\n
  time_starttransfer:  %{time_starttransfer}\n
                     ----------\n
          time_total:  %{time_total}\n
EOF

7.5 Tailscale Exit Node Verification¶

# Check Tailscale status
tailscale status

# Verify exit node advertisement
tailscale status | grep "exit node"

# Test from another Tailscale device
# Use this node as exit node and check external IP

8. Troubleshooting¶

8.1 Common Issues and Solutions¶

Docker Permission Issues¶

# Add user to docker group
usermod -aG docker $USER
newgrp docker

# Or run as root
sudo su -

Container Networking Issues¶

# Restart Docker daemon
systemctl restart docker

# Recreate networks
docker network rm vpn-network traefik-network
docker network create vpn-network --subnet=172.20.0.0/16
docker network create traefik-network --subnet=172.21.0.0/16

SSL Certificate Issues¶

# Check Traefik logs
docker logs traefik

# Verify Cloudflare API credentials
# Check acme.json permissions
ls -la /opt/vpn-exit-controller/traefik/letsencrypt/acme.json

VPN Connection Issues¶

# Check NordVPN credentials
cat /opt/vpn-exit-controller/configs/auth.txt

# Test manual OpenVPN connection
openvpn --config /opt/vpn-exit-controller/configs/vpn/us.ovpn \
        --auth-user-pass /opt/vpn-exit-controller/configs/auth.txt

8.2 Log Locations¶

# Application logs
journalctl -u vpn-controller -f

# Docker container logs
docker logs vpn-api
docker logs vpn-redis
docker logs traefik
docker logs haproxy

# System logs
/var/log/syslog
/var/log/daemon.log

# Traefik logs
/opt/vpn-exit-controller/traefik/logs/

8.3 Recovery Procedures¶

Service Recovery¶

# Restart all services
systemctl restart vpn-controller
docker compose down && docker compose up -d

# Clean restart
docker system prune -f
docker compose down -v
docker compose up -d --build

Database Recovery¶

# Restart Redis
systemctl restart redis-server

# Clear Redis cache if needed
redis-cli FLUSHALL

Post-Deployment Checklist¶

Security Considerations¶

Change default passwords in .env file
Restrict API access using proper authentication
Configure firewall rules to limit exposed ports
Regular security updates for all components
Monitor access logs for suspicious activity
Secure NordVPN credentials with proper file permissions
Use strong Tailscale authentication keys
Regular backup of configuration files

Maintenance¶

Regular Tasks¶

Monitor disk space and logs
Update Docker images monthly
Rotate authentication keys quarterly
Review access logs weekly
Test backup/recovery procedures monthly

Updates¶

Always test updates in staging environment
Backup configurations before updates
Update dependencies in requirements.txt
Monitor for security advisories

This deployment guide provides a complete foundation for setting up the VPN Exit Controller system. Adjust specific values like domain names, IP addresses, and credentials according to your environment.