VPNOrchestra

A FastAPI-based OpenVPN management system with automatic SOCKS5 proxy routing

📋 Table of Contents

📖 Summary
📋 Prerequisites
🚀 Installation
⚙️ Configuration
🎯 Usage
📚 API Documentation
🧪 Testing
⚠️ Known Issues
🗺️ Roadmap
🤝 Contributing
👥 Contributors
📄 License

📖 Summary

VPNOrchestra is a containerized VPN management system that allows you to deploy and orchestrate multiple OpenVPN connections simultaneously, each providing its own SOCKS5 proxy.

flowchart TB
 subgraph subGraph0["Load Balancer"]
        Gateway["HAProxy Gateway"]
  end
 subgraph VPN_Containers["VPN_Containers"]
        VPN_0["VPN Container 1"]
        VPN_1["VPN Container 2"]
        ...["..."]
        VPN_N["VPN Container N"]
  end
 subgraph subGraph2["VPNOrchestra Stack"]
        DockerProxy["Docker Socket Proxy"]
        Controller["FastAPI Controller"]
        VPN_Containers
        subGraph0
  end
    Client["Application/User"] -- SOCKS5 Request --> Gateway
    Controller -- Docker API --> DockerProxy
    DockerProxy -- Manage --> VPN_Containers
    Gateway -- Round Robin --> VPN_0 & VPN_1 & VPN_N
    VPN_0 -- OpenVPN Tunnel --> Web(("Internet"))
    VPN_1 -- OpenVPN Tunnel --> Web
    VPN_N -- OpenVPN Tunnel --> Web

How It Works

The system consists of three main components:

FastAPI Controller - A REST API service that manages the entire VPN infrastructure through simple HTTP endpoints. It handles container lifecycle, configuration, and monitoring.
VPN Containers - Each OpenVPN configuration file spawns an isolated Docker container running both an OpenVPN client and a SOCKS5 proxy (microsocks). Every container connects to a different VPN server and exposes its proxy on a unique port.
HAProxy Gateway - An intelligent load balancer that sits in front of all VPN containers. It automatically distributes traffic across healthy VPN connections using round-robin scheduling, with built-in health checks and automatic failover.

Typical Workflow

Setup: Place your .ovpn configuration files and vpn.auth credentials in the ovpn_configs directory
Deploy: Call the API to start VPN containers - the system automatically creates one container per config file
Connect: Applications connect to the HAProxy gateway on port 8080, which routes traffic through available VPN connections
Monitor: Check container status and gateway health through API endpoints
Manage: Stop, restart, or scale VPN containers on-demand via the API

This architecture provides redundancy (if one VPN fails, traffic routes to others), load distribution (requests spread across multiple VPN endpoints), and simplified management (one gateway endpoint instead of tracking individual containers).

📋 Prerequisites

🐳 Required

Docker: Install Docker
Docker Compose: Usually included with Docker Desktop
Python: 3.14 or higher (for local development/scripts)
VPN Credentials: Valid OpenVPN credentials (e.g., Surfshark, NordVPN)

📦 Optional

Poetry: For dependency management with pyproject.toml

🚀 Installation

Step 1: Clone the Repository

git clone https://github.com/giabb/VPNOrchestra.git
cd VPNOrchestra

Step 2: Configure VPN Credentials

Navigate to the configs directory
```
cd ovpn_configs
```
Create your credentials file
```
cp vpn.auth.sample vpn.auth
```
Edit vpn.auth with your VPN credentials
```
your_vpn_username
your_vpn_password
```
1. Important: The vpn.auth file should contain exactly two lines:
  - Line 1: Your VPN username
  - Line 2: Your VPN password

Step 3: Select VPN Servers

The script scripts/update_configs.py will update the ovpn_configs folder with pre-configured OpenVPN servers. By default, this will take Surfshark profiles, but you can change this behaviour by specifying a different OVPN_DOWNLOAD_URL environment variable.

Alternatively, you can also add your own .ovpn configuration files

Example server naming:

us-nyc.ovpn - New York, USA
uk-lon.ovpn - London, UK

🐳 Docker Installation (Required)

This project requires Docker as VPNs run in isolated containers.

Quick Start:

docker compose up --build -d

View Logs:

docker compose logs -f

Stop Services:

docker compose down

The API will be available at http://localhost:8000

📦 Python Dependencies (Optional, for scripts and test)

Using pip:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt

Using Poetry:

poetry install --no-root
poetry shell

⚙️ Configuration

Environment Variables

The system uses the following environment variables (configured in docker-compose.yml):

Variable	Default	Description
`DOCKER_HOST`	`tcp://docker-proxy:2375`	Docker API endpoint
`GATEWAY_PORT`	`8080`	Gateway SOCKS5 proxy port
`HOST_VPN_DIR`	`./ovpn_configs`	Host path for OVPN profiles
`VPN_DIR`	`/ovpn_configs`	Container path for OVPN profiles

Moreover, these environment variables can be used to override default for files in /scripts and /test:

Variable	Default	Description
`BASE_URI`	`http://localhost:8000`	The URI used by `restart_vpn.py` to make API calls
`MAX_VPN`	`4`	The max number of VPNs to be created by `restart_vpn.py`
`OVPN_DOWNLOAD_URL`	`https://my.surfshark.com/vpn/p_api/v1/server/configurations`	The link used by `update_configs.py` to update OVPN profiles

Docker Compose Services

docker-proxy: Secure Docker socket proxy (Tecnativa)

Restricts Docker API access
Provides container/image/network/volume operations only

vpnorchestra-controller: FastAPI management service

Manages VPN containers lifecycle
Provides REST API endpoints
Controls the creation of the gateway

🎯 Usage

Quick Start

If you're just interested in run the gateway and the VPNs, after configuring the OVPN profiles, you can simply run python scripts/restart_vpn.py after following the installation guide

An example of how to redirect requests to the gateway, along with a simple test, can be found under test/test_gateway.py

🔧 REST API

If you need to perform manual REST API calls, here are some examples:

Example 1: Start VPN Containers

curl -X POST "http://localhost:8000/start-vpns/" \
  -H "Content-Type: application/json" \
  -d '{
    "filenames": [
      "us-nyc.ovpn",
      "uk-lon.ovpn"
    ]
  }'

Response 1:

{
  "message": "VPN containers started successfully",
  "containers": [
    {
      "name": "vpn_0",
      "config": "us-nyc.ovpn",
      "proxy_port": 1080,
      "status": "running"
    }
  ],
  "gateway": {
    "name": "ovpn-gateway",
    "port": 8080,
    "status": "running",
    "backends": 2
  }
}

Example 2: Stop All VPN Containers

curl -X DELETE "http://localhost:8000/stop-vpns/"

Example 3: List Active Containers

curl -X GET "http://localhost:8000/vpns/"

Example 4: Gateway Status

curl -X GET "http://localhost:8000/gateway-status/"

📚 API Documentation

Interactive Documentation:

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

📜 Scripts

The scripts/ directory contains automation tools:

Restart VPN Containers

python scripts/restart_vpn.py

This script:

Stops all running VPN containers
Reads new .ovpn files from ovpn_configs/
Starts a container for each config
Deploys the HAProxy gateway

Update VPN Configurations

python scripts/update_configs.py

Downloads the latest OpenVPN configurations from your preferred provider (tunable with the OVPN_DOWNLOAD_URL envvar).

🧪 Testing

Quick test

You can run curl --socks5-hostname localhost:1080 https://api.ipify.org to perform a quick test to see if the gateway is up and running. This will return the IP of one of your VPNs.

Test Gateway Routing

python test/test_gateway.py

This script:

Tests connectivity through the HAProxy gateway
Verifies load balancing across VPN backends
Checks SOCKS5 proxy functionality
Gives an example of how to use the gateway to perform a request

Manual Container Testing

Access VPN container:

docker exec -it vpn_0 bash

Check connectivity:

curl -x socks5://localhost:1080 https://api.ipify.org

View container logs:

docker logs vpn_0

⚠️ Known Issues

Currently, there are no known major issues.

If you encounter problems:

Check the Issues page
Verify Docker is running and accessible
Ensure vpn.auth contains valid credentials
Check container logs: docker compose logs

🗺️ Roadmap

📋 Planned Features

I plan to integrate one or more of these features in the future updates, if you have any other idea please reach me out.

Web Dashboard: Browser-based management interface
Container Health Checks: Automatic restart on connection failure
Traffic Statistics: Monitor bandwidth usage per VPN
Custom Routing Rules: Per-application VPN routing
Multi-VPN Provider Support: NordVPN, ExpressVPN, etc.
Metrics Export: Prometheus/Grafana integration

🤝 Contributing

Here's how you can help:

🐛 Bug Reports

Use the issue tracker
Include Docker version and OS information
Provide container logs and error messages
List steps to reproduce

🚀 Feature Requests

Describe the feature and its use case
Explain how it improves the project
Provide implementation suggestions

💻 Code Contributions

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes with tests
Commit with clear messages (git commit -m 'Add amazing feature')
Push to your fork (git push origin feature/amazing-feature)
Open a Pull Request

📖 Documentation

Improve README clarity
Add usage examples
Document API endpoints
Create tutorials

👥 Contributors

Project Creator & Maintainer

Giovanbattista Abbate

Want to contribute? See the Contributing section above!

📄 License

This project is licensed under the GNU General Public License v3.0.

This means you can:

✅ Use the software for any purpose
✅ Study and modify the source code
✅ Distribute copies of the software
✅ Distribute modified versions

Requirements:

📋 Include the original license
📋 State changes made to the code
📋 Make source code available when distributing

See the LICENSE.md file for complete details.

Built for privacy-conscious developers and network engineers

⭐ Star this repo • 🐛 Report Issues • 💬 Discussions

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
ovpn_configs		ovpn_configs
proxy_files		proxy_files
scripts		scripts
src		src
test		test
.gitattributes		.gitattributes
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE.md		LICENSE.md
README.md		README.md
docker-compose.yml		docker-compose.yml
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation