azinchen/nordvpn repository overview

⁠NordVPN OpenVPN Docker Container

OpenVPN client docker container that routes other containers' traffic through NordVPN servers automatically.

⁠✨ Key Features

• 🚀 Easy Setup — Route any container's traffic through VPN with --net=container:vpn
• 🌍 Smart Server Selection — Auto-select servers by country, city, group, or specific hostname (details⁠)
• ⚖️ Load Balancing — Intelligent sorting by server load when multiple locations specified
• 🔄 Auto-Reconnection — Periodic server switching and health monitoring (details⁠)
• 🕵️ XOR Obfuscation — Built-in XOR patches disguise OpenVPN traffic to bypass DPI (details⁠)
• 🛡️ Kill Switch — Default-deny firewall blocks all traffic when VPN is down (details⁠)
• 🏠 Local/LAN Access — Allow specific CIDRs with NETWORK=... (details⁠)
• 🧭 Custom DNS — Resolve through the tunnel; override with DNS=... (details⁠)
• 📵 IPv6 Firewall — Built-in chains default to DROP (details⁠)
• 🧱 iptables Compatibility — Auto-selects nft or legacy backend (details⁠)
• 🚪 VPN Gateway Mode — Route downstream subnets through the tunnel with FORWARD_FROM (details⁠)

⁠Quick Start

docker run -d --cap-add=NET_ADMIN --device /dev/net/tun --name vpn \
           -e USER=service_username -e PASS=service_password \
           azinchen/nordvpn

Route other containers through VPN:

docker run --net=container:vpn -d your/application

Also available from GitHub Container Registry: ghcr.io/azinchen/nordvpn

⁠Requirements

• Docker with --cap-add=NET_ADMIN and --device /dev/net/tun
• NordVPN service credentials or an access token (not regular account credentials)

⁠Getting Service Credentials

1. Log into your Nord Account Dashboard⁠
2. Click on NordVPN → Advanced Settings → Set up NordVPN manually
3. Go to the Service credentials tab
4. Copy the Username and Password shown there

Alternative — access token: instead of copying the service credentials, generate an access token (Nord Account Dashboard → NordVPN → Advanced Settings → Generate new token) and pass it as TOKEN; the container then fetches the service credentials from the NordVPN API at startup. If USER/PASS are also set, they take priority over the token.

⁠Docker Compose Example

services:
  vpn:
    image: azinchen/nordvpn:latest
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun
    environment:
      - USER=service_username
      - PASS=service_password
      # - TOKEN=access_token       # alternative to USER/PASS
      - COUNTRY=United States;CA
      - RANDOM_TOP=10
      - RECREATE_VPN_CRON=0 */6 * * *
      - NETWORK=192.168.1.0/24
    ports:
      - "8080:80"                  # host:container — use your app's listening port
    restart: unless-stopped

  app:
    image: nginx:alpine
    network_mode: "service:vpn"
    depends_on:
      - vpn
    restart: unless-stopped

⁠Environment Variables

⁠Credentials

NordVPN service credentials, set directly or fetched automatically with an access token — see Getting Service Credentials⁠ above.

⁠Server Selection

Pick which servers to connect to; filters combine to narrow the pool. See Server Selection⁠.

⁠OpenVPN Connection

Protocol, port, and traffic obfuscation. See Technologies⁠.

⁠Reconnection & Health Monitoring

Rotate servers on a schedule and verify the tunnel actually works. See Automatic Reconnection⁠.

⁠Local Network & VPN Gateway

Open the kill‑switch firewall for LAN access and downstream routing. See Local Network Access⁠ and VPN Gateway Mode⁠.

⁠Advanced

Low‑level settings; the defaults work for most setups.

⁠Issues

If you have any problems with or questions about this image, please contact me through a GitHub issue⁠ or email⁠.

Check the Troubleshooting⁠ and FAQ⁠ wiki pages first.