projects/Dockers/vpn-proxy/README.md

VPN Proxy Docker Container

A Docker container that creates a proxy server routed through a VPN connection (OpenVPN or WireGuard). This allows you to access websites through a VPN tunnel by using the container as a proxy.

Features

• Supports both OpenVPN (.ovpn) and WireGuard (.conf) configurations
• Squid proxy server for HTTP/HTTPS traffic
• Automatic VPN connection and health monitoring
• Configurable target URL for testing
• Health checks and automatic restart on failure

Usage

Prerequisites

• Docker with --cap-add=NET_ADMIN capability
• Access to /dev/net/tun device (for OpenVPN)
• VPN configuration file (.ovpn or .conf)

Basic Usage

1. Build the container:

   docker build -t vpn-proxy .
   

2. Run with OpenVPN:

   docker run -d \
     --name vpn-proxy \
     --cap-add=NET_ADMIN \
     --device /dev/net/tun \
     -p 3128:3128 \
     -e PROXY_URL=https://example.com \
     -e VPN_CONFIG=/vpn/config.ovpn \
     -e VPN_TYPE=openvpn \
     -v /path/to/your/config.ovpn:/vpn/config.ovpn:ro \
     vpn-proxy
   

3. Run with WireGuard:

   docker run -d \
     --name vpn-proxy \
     --cap-add=NET_ADMIN \
     -p 3128:3128 \
     -e PROXY_URL=https://example.com \
     -e VPN_CONFIG=/vpn/wg0.conf \
     -e VPN_TYPE=wireguard \
     -v /path/to/your/wg0.conf:/vpn/wg0.conf:ro \
     vpn-proxy
   

Environment Variables

Variable	Required	Default	Description
PROXY_URL	Yes	-	Target URL to proxy through VPN
VPN_CONFIG	Yes	-	Path to VPN configuration file
VPN_TYPE	No	openvpn	VPN type: openvpn or wireguard

Using the Proxy

Once the container is running, you can use it as a proxy:

# Test the proxy
curl -x localhost:3128 https://httpbin.org/ip

# Use in applications
export http_proxy=http://localhost:3128
export https_proxy=http://localhost:3128

Docker Compose Example

version: "3.8"
services:
  vpn-proxy:
    build: .
    container_name: vpn-proxy
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun
    ports:
      - "3128:3128"
    environment:
      - PROXY_URL=https://example.com
      - VPN_CONFIG=/vpn/config.ovpn
      - VPN_TYPE=openvpn
    volumes:
      - ./config.ovpn:/vpn/config.ovpn:ro
    restart: unless-stopped

Configuration Files

OpenVPN Configuration

Your .ovpn file should contain all necessary connection details including:

• Server address and port
• Authentication credentials
• Certificate data
• Cipher settings

WireGuard Configuration

Your .conf file should follow the standard WireGuard format:

[Interface]
PrivateKey = your_private_key
Address = 10.0.0.2/24
DNS = 8.8.8.8

[Peer]
PublicKey = server_public_key
Endpoint = server.example.com:51820
AllowedIPs = 0.0.0.0/0

Monitoring

The container includes health checks and will automatically restart if:

• VPN connection is lost
• Proxy server stops responding
• Container receives SIGTERM/SIGINT

Check logs with:

docker logs vpn-proxy

Security Notes

• The container runs with NET_ADMIN capability to manage network interfaces
• VPN credentials are stored in mounted configuration files
• The proxy server is configured to forward all traffic through the VPN
• No caching is performed to ensure fresh data through VPN

Troubleshooting

1. VPN won't connect:

   • Check that the configuration file is properly mounted
   • Verify VPN credentials and server availability
   • Check container logs for specific error messages

2. Proxy not working:

   • Ensure port 3128 is accessible
   • Test with curl -x localhost:3128 http://httpbin.org/ip
   • Check that the VPN connection is active

3. Permission denied:

   • Ensure the container has --cap-add=NET_ADMIN
   • For OpenVPN, ensure /dev/net/tun is accessible

License

This project is open source and available under the MIT License.