genericmale/protonvpn repository overview

⁠ProtonVPN Docker Image

This Docker image provides a lightweight and secure solution to connect your containers to ProtonVPN.

⁠Features

• Minimal Footprint: Built on Alpine Linux for a compact image size.
• Flexible Server Selection: Use JQ filters for granular control over servers with random selection.
• Automatic Server Rotation (Optional): Schedule automatic reconnection to switch servers periodically.
• Multi-Container Support: Easily connect any number of containers to the VPN.
• Kill Switch: Disconnect containers on VPN drop.
• HTTP Proxy (Optional): Easily route any http and https traffic through the VPN.

⁠Usage

1. Obtain OpenVPN Credentials: Get your credentials from your ProtonVPN account: https://account.proton.me/u/0/vpn/OpenVpnIKEv2⁠.
2. Configure Credentials: Choose one of the following methods:
   • Secrets File: Create a file containing your username and password on separate lines. Set the AUTH_USER_PASS_FILE environment variable to the file path.
   • Environment Variables: Define the OPENVPN_USER and OPENVPN_PASS environment variables with your credentials.
3. Connect Containers and/or Enable HTTP Proxy:
   • VPN Access: Use the network_mode: service:protonvpn option in your Docker Compose configuration for containers requiring VPN protection.
   • HTTP Proxy: Set the HTTP_PROXY environment variable to 1 and map port 3128 to use the VPN in any application with HTTP(S) proxy support.

⁠Example Docker Compose with other Container

services:
  protonvpn:
    image: genericmale/protonvpn
    restart: unless-stopped
    environment:
      - OPENVPN_USER_PASS_FILE=/run/secrets/protonvpn
      - VPN_RECONNECT=2:00
      - VPN_SERVER_COUNT=10
    ports:
      - 8118:8118 # Privoxy Port
    volumes:
      - /etc/localtime:/etc/localtime:ro
    devices:
      - /dev/net/tun
    cap_add:
      - NET_ADMIN
    secrets:
      - protonvpn
  privoxy:
    image: vimagick/privoxy
    restart: unless-stopped
    network_mode: service:protonvpn
    depends_on:
      protonvpn:
        condition: service_healthy
secrets:
  protonvpn:
    file: protonvpn.auth

This configuration achieves the following:

• Uses VPN_SERVER_COUNT=10 to randomly selects one of the 10 fastest servers.
• Schedules reconnection at 2:00 AM with VPN_RECONNECT=2:00 to rotate servers.
• Runs a Privoxy container attached to the VPN network. (network_mode: service:protonvpn)
• Privoxy is not started until the VPN is connected with depends_on and condition: service_healthy.
• Exposes Privoxy's port (8118) for clients to connect to the VPN using Privoxy as a forward proxy. Notice the port mapping on the ProtonVPN container.

⁠Example Docker Compose using built-in Proxy

services:
  protonvpn:
    image: genericmale/protonvpn
    restart: unless-stopped
    environment:
      - OPENVPN_USER_PASS_FILE=/run/secrets/protonvpn
      - HTTP_PROXY=1
    ports:
      - 3128:3128
    volumes:
      - /etc/localtime:/etc/localtime:ro
    devices:
      - /dev/net/tun
    cap_add:
      - NET_ADMIN
    secrets:
      - protonvpn
secrets:
  protonvpn:
    file: protonvpn.auth

⁠Environment Variables

⁠JQ Filters for Advanced Server Selection

The VPN_SERVER_FILTER environment variable allows you to filter available ProtonVPN servers using JQ queries.

Some examples:

# Fastest Servers from Germany
- VPN_SERVER_FILTER=map(select(.ExitCountry == "DE"))

# Servers with Lowest Load
- VPN_SERVER_FILTER=sort_by(.Load)

# Specific server
- VPN_SERVER_FILTER=map(select(.Name == "GR#3"))

# Fastest Servers from Berlin with Load <50%
- VPN_SERVER_FILTER=map(select(.City == "Berlin" and .Load < 50))

# Fastest Servers from Different Countries
- VPN_SERVER_FILTER=group_by(.ExitCountry) | map(.[0]) | sort_by(.Score)

⁠Building

To build the image, the following command can be used (adapt tag name to your liking):

docker image build . -t protonvpn

⁠Additional Resources

• Docker Compose Overview: https://docs.docker.com/compose/⁠
• ProtonVPN Documentation: https://protonvpn.com/support/linux-openvpn/⁠
• OpenVPN Reference Manual: https://openvpn.net/community-resources/reference-manual-for-openvpn-2-6/⁠
• Tinyproxy: https://tinyproxy.github.io/⁠
• JQ Manual: https://jqlang.github.io/jq/manual/⁠