Running ProtonVPN in ZimaOS

Insight & Feedback
,
5

Yep, you were very close, and the fact it “worked once” is a huge clue: your compose is valid, but now ZimaOS is rejecting the import because of one of these common issues:

Why it won’t import now (most likely causes)

  1. YAML indentation / formatting got broken
  • ZimaOS’s compose importer is more strict than normal docker-compose.
  • If you pasted it without proper spacing, it can reject it.
  1. You included a raw WireGuard private key in a web UI
  • Some platforms sanitize or reject values containing +, /, or =.
  • Even though Docker would accept it, the UI import validator might fail.
  1. Blank env vars
  • You currently have:
    • - TZ=
    • - UPDATER_PERIOD=
  • Some UIs fail validation when required fields are blank (even if Docker would allow it).

The fix: use the “safe” version of your compose

This version avoids UI-import issues, removes blank env vars, and uses the recommended Gluetun env names for ProtonVPN WireGuard.

Important: In a public forum post, you MUST remove the private key before posting.

services:
  gluetun:
    image: qmcgaw/gluetun:latest
    container_name: gluetun
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
    ports:
      - "8888:8888/tcp"
      - "8388:8388/tcp"
      - "8388:8388/udp"
    volumes:
      - /DATA/AppData/gluetun:/gluetun
    environment:
      - VPN_SERVICE_PROVIDER=protonvpn
      - VPN_TYPE=wireguard

      # ProtonVPN WireGuard config
      - WIREGUARD_PRIVATE_KEY=PUT_YOUR_KEY_HERE
      - WIREGUARD_ADDRESSES=10.2.0.2/32

      # strongly recommended
      - TZ=Australia/Sydney
      - SERVER_COUNTRIES=Australia

Why this version imports reliably

  • Quotes around ports (some validators require it)
  • No empty values (TZ and UPDATER_PERIOD were blank)
  • Uses a standard server selector so Gluetun actually connects

Most important ProtonVPN detail

ProtonVPN has two different logins:

What Gluetun needs:

  • Proton “WireGuard config” private key (from Proton VPN app / dashboard)

What does NOT work:

  • Your normal Proton account password
  • Your “regular Proton login user/pass”

You’re doing WireGuard so you’re on the right track.

After it imports: the quickest way to confirm it’s working

Once deployed, check Gluetun logs.

You should see something like:

  • “Wireguard connected”
  • “Public IP: xxx.xxx.xxx.xxx”
  • and no constant reconnect loops.

Next step (ARR stack routing)

Once Gluetun is stable, the easiest way to route an app through it is:

network_mode: "service:gluetun"

Example (qBittorrent behind VPN):

  qbittorrent:
    image: lscr.io/linuxserver/qbittorrent
    network_mode: "service:gluetun"
    depends_on:
      - gluetun
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Australia/Sydney
    volumes:
      - /DATA/AppData/qbittorrent:/config
      - /DATA/Downloads:/downloads

Final tip (very ZimaOS-specific)

If you “uninstalled” Gluetun but kept the old container name or network, the UI sometimes gets stuck.

Fix: change this:

container_name: gluetun

to:

container_name: gluetun2

Import again, if that works, it confirms ZimaOS had a name conflict.

If you want, paste what exact error ZimaOS shows during “import” (even just screenshot text), and I’ll write the exact corrected compose that will definitely deploy on ZimaOS.

1 Like
PROTON VPN sous ZimaOS