azinchen/nordvpn

By azinchen

•Updated 11 days ago

NordVPN Docker Client

Image

1M+

Overview Tags

azinchen/nordvpn repository overview

⁠NordVPN OpenVPN Docker Container

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

Prefer WireGuard? This has a sibling project, azinchen/nordvpn-wg⁠ — the same auto-routing NordVPN container over WireGuard (NordLynx). Both share the same configuration model and feature set.

⁠✨ 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⁠)
📵 IPv6 Firewall — Built-in chains default to DROP (details⁠)
🧱 iptables Compatibility — Auto-selects nft or legacy backend (details⁠)
🚪 VPN Gateway Mode — Route downstream networks out through the tunnel with FORWARD_FROM=... (details⁠)

📖 Full documentation on the Wiki⁠ — configuration guides, examples, troubleshooting, FAQ, and architecture.

⁠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 (not regular account credentials)

⁠Getting Service Credentials

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

Note: These are different from your regular NordVPN login credentials.

⁠Docker Compose Example

services:
  vpn:
    image: azinchen/nordvpn:latest
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun
    environment:
      - USER=service_username
      - PASS=service_password
      - COUNTRY=United States;CA
      - RANDOM_TOP=10
      - RECREATE_VPN_CRON=0 */6 * * *
      - NETWORK=192.168.1.0/24
    ports:
      - "8080:8080"
    restart: unless-stopped

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

More examples: Docker Compose⁠ · Docker Run⁠

⁠Environment Variables

Variable	Details
USER	Required — NordVPN service credentials username.
PASS	Required — NordVPN service credentials password.
PUID	User ID for the nordvpn process. Default: `912`
PGID	Group ID for the nordvpn process. Default: `912`
COUNTRY	Filter by countries: names, codes, IDs, or server hostnames (list⁠). Semicolon‑separated.
CITY	Filter by cities: names, IDs, or server hostnames (list⁠). Semicolon‑separated.
GROUP	Filter by server group (list⁠).
TECHNOLOGY	OpenVPN protocol (list⁠). Default: `openvpn_udp`
RANDOM_TOP	Randomize top N servers. Default: `0`
PORT	Force a specific port for the VPN connection. Must be supported by the server. Default: auto
RECREATE_VPN_CRON	Server switching schedule (cron). Default: disabled
CHECK_CONNECTION_CRON	Health monitoring schedule (cron). Default: disabled
CHECK_CONNECTION_URL	URLs to test connectivity; semicolon‑separated. Default: `https://www.google.com`
CHECK_CONNECTION_ATTEMPTS	Connection test retry count. Default: `5`
CHECK_CONNECTION_ATTEMPT_INTERVAL	Seconds between retries. Default: `10`
NETWORK	LAN/inter‑container CIDRs to allow; semicolon‑separated. Default: none
FORWARD_FROM	Downstream CIDRs allowed to route OUT through the tunnel (gateway mode). Traffic must arrive already SNATed into these nets. Semicolon‑ or comma‑separated. Default: none
NORDVPNAPI_IP	API bootstrap IPs (semicolon‑separated). Default: `104.16.208.203;104.19.159.190`
XOR_KEY	XOR scramble obfuscation key for `openvpn_xor_*` technologies. Default: NordVPN's built-in key
OPENVPN_OPTS	Additional OpenVPN parameters.
NETWORK_DIAGNOSTIC_ENABLED	Enable network diagnostics on connect. Default: `false`
HEALTHCHECK_ENABLED	Enable the Docker `HEALTHCHECK` probe (checks `tun0` + connectivity via `CHECK_CONNECTION_URL`). When `false`, the container always reports healthy. Default: `false`

⁠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.

Tag summary

Recent tags

Content type

Image

Digest

sha256:eab3411e1…

Size

14.9 MB

Last updated

11 days ago

docker pull azinchen/nordvpn