Configuration handoff

Long-running Privateerr shares files with Gluetun at startup and uses its authenticated API during recovery. Gluetun owns the tunnel; rewriting a file alone does not reconfigure a running tunnel.

1. Privateerr installs its two image-owned integration scripts.
2. It validates and reuses the saved WireGuard configuration and PIA settings when recovery is enabled, or generates fresh settings.
3. Its startup healthcheck allows Gluetun to start.
4. Gluetun's wrapper reads the matching metadata and configures recovery authentication.
5. Gluetun starts the tunnel; network-sharing download clients start after it is healthy.
6. During sustained failure, Privateerr applies a candidate through the API and saves it after settings readback and tunnel-health confirmation.

Creating configuration files once with both PRIVATEERR_KEEPALIVE=false and PRIVATEERR_AUTO_RECOVER=false writes the VPN pair without installing or changing integration scripts. Follow the configuration-only procedure and stop other Privateerr containers writing to the same directory first.

Why the metadata exists

wg0.conf contains WireGuard settings; privateerr.env supplies the matching PIA server identity needed for forwarding. Its generation timestamp does not change when a valid saved pair is reused. Age alone does not make a healthy connection stale. Keep both real files private.

Understand readiness and retained files

For long-running startup, Privateerr's readiness marker means it installed the scripts and produced or validated the saved pair. It does not certify tunnel health or future recovery write access; Gluetun has its own healthcheck.

The supervisor retains .privateerr-pending/ and .privateerr-commit/ beside the two files when an update or save needs reconciliation. If publication fails, the running tunnel may already use newer settings than the saved files. Preserve those directories, repair the reported storage problem, and allow reconciliation. Do not delete retained state or run another writer. See storage diagnostics.

Important variables

Set credentials, region policy, recovery flag, and the shared key in the private deployment .env. Keep PIA_CONNECT=false and PRIVATEERR_KEEPALIVE=true for recovery. Gluetun uses VPN_SERVICE_PROVIDER=custom.

See region changes, recovery timing and authentication, and the Privateerr configuration reference for complete settings. Generated Compose comments explain behavior and units.

Mount the shared directory

Share the complete Gluetun configuration directory read/write: Privateerr mounts it at /gluetun; Gluetun mounts the same directory at /gluetun and /tmp/gluetun. Directory mounts support atomic replacement and retain recovery state. Privateerr's UID 0 needs write/traverse access; Gluetun needs read/execute access to the scripts. Only one supervisor may own the two files.

Privateerr replaces scripts/gluetun-entrypoint-wrapper.sh and scripts/qbittorrent-port-forwarding.sh from its image on long-running startup. Keep operator scripts under other names. A preserved custom GLUETUN_ENTRYPOINT_WRAPPER must satisfy the recovery contract.

Keep Privateerr on the project network, outside Gluetun's namespace, so it can contact PIA during an outage. Keep Gluetun's control and health endpoints internal.