Skip to content

Installation Guide

This guide covers detailed installation instructions for VPN Exit Controller on various platforms.

System Requirements

Minimum Requirements

  • CPU: 2 cores
  • RAM: 4GB
  • Storage: 20GB SSD
  • Network: 100 Mbps connection
  • OS: Ubuntu 22.04 LTS or compatible
  • CPU: 4+ cores
  • RAM: 8GB+
  • Storage: 50GB+ SSD
  • Network: 1 Gbps connection
  • OS: Ubuntu 22.04 LTS

Supported Platforms

Platform Version Support Level
Ubuntu 22.04 LTS ✅ Full Support
Ubuntu 20.04 LTS ✅ Full Support
Debian 11/12 ✅ Full Support
RHEL/CentOS 8/9 ⚠️ Community Support
Proxmox LXC 7.x/8.x ✅ Full Support
Docker 20.10+ ✅ Full Support

Installation Methods

# Download and run installer
curl -sSL https://vpn-docs.rbnk.uk/install.sh | bash

The installer will: - ✅ Check system requirements - ✅ Install dependencies - ✅ Configure services - ✅ Set up systemd units - ✅ Create necessary directories

Method 2: Manual Installation

Step 1: Install System Dependencies

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

# Install dependencies
sudo apt install -y \
  curl \
  git \
  python3.10 \
  python3.10-venv \
  python3-pip \
  docker.io \
  docker-compose \
  redis-server \
  nginx \
  certbot \
  python3-certbot-nginx

# Start services
sudo systemctl enable --now docker redis

# Update system
sudo dnf update -y

# Install dependencies
sudo dnf install -y \
  curl \
  git \
  python3.10 \
  python3-pip \
  docker \
  docker-compose \
  redis \
  nginx \
  certbot \
  python3-certbot-nginx

# Start services
sudo systemctl enable --now docker redis

Step 2: Install Tailscale

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

# Start Tailscale
sudo systemctl enable --now tailscaled

Step 3: Clone Repository

# Clone from Gitea
git clone https://gitea.rbnk.uk/admin/vpn-controller.git /opt/vpn-exit-controller
cd /opt/vpn-exit-controller

Step 4: Python Environment Setup

# Create virtual environment
python3 -m venv venv

# Activate environment
source venv/bin/activate

# Install Python packages
pip install --upgrade pip
pip install -r requirements.txt

Step 5: Configure Environment

# Copy example configuration
cp .env.example .env

# Edit configuration
nano .env

Required environment variables:

# NordVPN Service Credentials
NORDVPN_USER=your_service_username
NORDVPN_PASS=your_service_password

# Tailscale Configuration
TAILSCALE_AUTH_KEY=tskey-auth-xxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxx

# API Authentication
API_USERNAME=admin
API_PASSWORD=strong_password_here

# Cloudflare (for DNS management)
CF_API_TOKEN=your_cloudflare_api_token

# Redis Configuration
REDIS_HOST=localhost
REDIS_PORT=6379

Step 6: Create Systemd Service

# Create service file
sudo tee /etc/systemd/system/vpn-controller.service << EOF
[Unit]
Description=VPN Exit Controller API
After=network.target redis.service docker.service
Wants=redis.service docker.service

[Service]
Type=exec
User=root
WorkingDirectory=/opt/vpn-exit-controller
Environment="PATH=/opt/vpn-exit-controller/venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
ExecStart=/opt/vpn-exit-controller/venv/bin/python -m uvicorn api.main:app --host 0.0.0.0 --port 8080
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# Enable and start service
sudo systemctl daemon-reload
sudo systemctl enable --now vpn-controller

Method 3: Docker Installation

Using Docker Compose

# Create docker-compose.yml
cat > docker-compose.yml << EOF
version: '3.8'

services:
  redis:
    image: redis:alpine
    restart: always
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data

  vpn-controller:
    build: .
    restart: always
    ports:
      - "8080:8080"
    environment:
      - REDIS_HOST=redis
    env_file:
      - .env
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./configs:/app/configs
    depends_on:
      - redis

volumes:
  redis-data:
EOF

# Start services
docker-compose up -d

Post-Installation Setup

1. Verify Installation

# Check service status
sudo systemctl status vpn-controller

# Test API endpoint
curl http://localhost:8080/api/health -u admin:your_password

2. Configure Firewall

# Allow required ports
sudo ufw allow 8080/tcp  # API
sudo ufw allow 80/tcp    # HTTP
sudo ufw allow 443/tcp   # HTTPS
sudo ufw allow 8888/tcp  # HAProxy stats

# Enable firewall
sudo ufw enable

# Allow required ports
sudo firewall-cmd --permanent --add-port=8080/tcp
sudo firewall-cmd --permanent --add-port=80/tcp
sudo firewall-cmd --permanent --add-port=443/tcp
sudo firewall-cmd --permanent --add-port=8888/tcp

# Reload firewall
sudo firewall-cmd --reload

3. Set Up SSL Certificates

# Using Certbot
sudo certbot --nginx -d vpn-api.yourdomain.com

# Or using Traefik (automatic)
cd traefik && docker-compose up -d

4. Configure DNS Records

Add these records to your domain:

Type Name Value Proxy
A vpn-api YOUR_SERVER_IP ❌
A proxy-us YOUR_SERVER_IP ✅
A proxy-uk YOUR_SERVER_IP ✅
A proxy-jp YOUR_SERVER_IP ✅

Troubleshooting Installation

Common Issues

Docker Permission Denied 

# Add user to docker group
sudo usermod -aG docker $USER
# Log out and back in

Port Already in Use 

# Find process using port
sudo lsof -i :8080
# Change port in configuration

Python Version Issues 

# Install specific Python version
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt install python3.10 python3.10-venv

Uninstallation

To completely remove VPN Exit Controller:

# Stop services
sudo systemctl stop vpn-controller
sudo systemctl disable vpn-controller

# Remove files
sudo rm -rf /opt/vpn-exit-controller
sudo rm /etc/systemd/system/vpn-controller.service

# Remove Docker containers
docker stop $(docker ps -a -q --filter name=vpn-)
docker rm $(docker ps -a -q --filter name=vpn-)

# Clean up (optional)
sudo apt remove --purge docker.io docker-compose

Next Steps

Need Help?

If you encounter issues during installation, check our Troubleshooting Guide or open an issue.