Skip to content

Quick Start Guide

Get VPN Exit Controller up and running in under 10 minutes!

Prerequisites Checklist

Before starting, ensure you have:

  • Ubuntu 22.04+ server with root access
  • Docker and Docker Compose installed
  • Python 3.10+ with pip
  • Domain with Cloudflare DNS
  • NordVPN service credentials
  • Tailscale auth key

1. Clone the Repository

git clone https://gitea.rbnk.uk/admin/vpn-controller.git
cd vpn-controller

2. Configure Environment

Copy the example environment file:

cp .env.example .env

Edit .env with your credentials:

# Essential configuration
NORDVPN_USER=your_nordvpn_service_username
NORDVPN_PASS=your_nordvpn_service_password
TAILSCALE_AUTH_KEY=your_tailscale_auth_key
CF_API_TOKEN=your_cloudflare_api_token
API_PASSWORD=your_secure_password_here

Security Note

Never commit .env to version control. The file is already in .gitignore.

3. Install Dependencies

Create Python virtual environment:

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

4. Start Services

Redis (Required for metrics)

docker run -d --name redis \
  -p 6379:6379 \
  --restart always \
  redis:alpine

VPN Controller API

# Development mode
uvicorn api.main:app --reload --host 0.0.0.0 --port 8080

# Or use the systemd service (production)
sudo systemctl enable vpn-controller
sudo systemctl start vpn-controller

5. Create Your First VPN Node

Start a US exit node:

curl -X POST http://localhost:8080/api/nodes/start \
  -u admin:your_api_password \
  -H "Content-Type: application/json" \
  -d '{"country": "us", "city": "New York"}'

Check node status:

curl http://localhost:8080/api/nodes \
  -u admin:your_api_password

6. Set Up Proxy Access (Optional)

Deploy HAProxy

cd proxy
docker-compose up -d

Deploy Traefik for SSL

cd ../traefik
docker-compose up -d

Configure DNS

# Set your Cloudflare API token
export CF_API_TOKEN=your_cloudflare_api_token

# Run DNS setup
./scripts/setup-proxy-dns.sh

7. Test Your Setup

Test VPN connectivity:

# Check if node is connected
curl http://localhost:8080/api/health -u admin:your_api_password

Test proxy URL (if configured):

# Test US proxy
curl -x https://proxy-us.yourdomain.com https://ipinfo.io

🎉 Success!

You now have a working VPN Exit Controller! Here's what you can do next:

Essential Commands

# List all nodes
curl http://localhost:8080/api/nodes -u admin:$API_PASSWORD

# Start a node
curl -X POST http://localhost:8080/api/nodes/start \
  -u admin:$API_PASSWORD \
  -H "Content-Type: application/json" \
  -d '{"country": "uk"}'

# Start a specific UK node
curl -X POST http://localhost:8080/api/nodes/uk/start \
  -u admin:$API_PASSWORD

# Stop a node
curl -X DELETE http://localhost:8080/api/nodes/vpn-uk \
  -u admin:$API_PASSWORD

# System health
curl http://localhost:8080/api/health -u admin:$API_PASSWORD

# Node metrics
curl http://localhost:8080/api/metrics -u admin:$API_PASSWORD

# Speed test
curl -X POST http://localhost:8080/api/speed-test/vpn-us \
  -u admin:$API_PASSWORD

# Get best node for country
curl http://localhost:8080/api/load-balancer/best-node/us \
  -u admin:$API_PASSWORD

# Get best UK node
curl http://localhost:8080/api/load-balancer/best-node/uk \
  -u admin:$API_PASSWORD

# Change strategy
curl -X POST http://localhost:8080/api/load-balancer/strategy \
  -u admin:$API_PASSWORD \
  -H "Content-Type: application/json" \
  -d '{"strategy": "health_score"}'

Common Issues & Solutions

Node won't start?

  • Check Docker is running: docker ps
  • Verify NordVPN credentials in .env
  • Check logs: docker logs vpn-us

Can't access proxy URLs?

  • Ensure DNS records are created
  • Check Traefik is running: docker ps | grep traefik
  • Verify SSL certificates: Check Traefik logs

API returns 401 Unauthorized?

  • Check username is admin
  • Verify password matches .env setting
  • Use -u admin:password with curl

Next Steps

Congratulations!

You've successfully deployed VPN Exit Controller. Join our community to stay updated with new features and best practices.