Privateerr 🏴‍☠️

Privateerr packages and ships the unmodified Private Internet Access (PIA) manual connection scripts in a lightweight Alpine Docker image. It generates WireGuard configuration and server metadata for Gluetun or another compatible VPN client. Its optional supervisor refreshes stale settings after sustained tunnel outages.

🦜 Parrot says: Found this useful? Drop a ⭐ an' help another crew find the map.

─── ⛧ ───

🕵️ VPN in Tartarus? Summon the network necromancers in

Choose a task 🧭

Generate configuration only: use the repository, or run Docker directly without Git or Make.
Run the supplied stack: start Privateerr, Gluetun, and qBittorrent with automatic recovery.
Develop or test Privateerr: work on source without using a production deployment.

Gluetun owns the tunnel, firewall, DNS, and port lease. Privateerr generates settings and can refresh them after a sustained outage; it does not manage containers.

Prepare a checkout

You need an active PIA subscription, Git, Make, and Docker with Compose. Source builds also need Buildx and the pinned PIA submodule. Run these commands from the directory where you want the checkout:

git clone --recurse-submodules https://github.com/scottgigawatt/privateerr.git
cd privateerr
cp example.env .env

Set PIA_USER and PIA_PASS in the private .env. Use your PIA VPN username (p or P followed by seven digits), not your email address. Keep PIA_VPN_PROTOCOL=wireguard and PIA_CONNECT=false. Review host paths, user/group IDs, time zone, and ports. The example enables port forwarding and selects an eligible region automatically.

[!WARNING] Keep .env, generated VPN files, backups, and private logs out of Git and public reports. Generation replaces saved files; preserve needed state and stop any supervisor writing the destination first.

If a build reports a missing pia-manual-connections/LICENSE, initialize the pinned submodule.

Generate a WireGuard configuration ⚡

In this source revision, setting both PRIVATEERR_KEEPALIVE=false and PRIVATEERR_AUTO_RECOVER=false selects one-shot generation without installing or changing Gluetun scripts. After preparing the checkout, run:

make run-privateerr

This builds the checked-out source and exits after writing:

File	Purpose
`config/gluetun/wireguard/wg0.conf`	WireGuard configuration
`config/gluetun/wireguard/privateerr.env`	Matching PIA server metadata

Confirm that the command exits successfully with Generation complete. and both files exist. File generation alone does not establish a working tunnel. Without Make, use the published-image Compose command.

Using Docker directly

This route needs only Docker and an active PIA subscription. Start in a new directory outside an existing checkout or deployment:

mkdir privateerr-generation &&
  cd privateerr-generation &&
  umask 077 &&
  touch .env

Open .env and replace these placeholders with your PIA VPN username (p or P followed by seven digits) and password. Docker's --env-file reads values literally: do not add shell quotes or copy the Compose-oriented example.env:

PIA_USER=YOUR-PIA-VPN-USERNAME
PIA_PASS=YOUR-PIA-PASSWORD

[!IMPORTANT] Privateerr 2.3.1 installs Gluetun scripts under config/gluetun/scripts/ even in one-shot mode. Before using a published image, check its release notes for one-shot script isolation; otherwise, build this source with the Make command above.

Run generation from that directory. It replaces saved VPN files, so preserve any needed state and stop other writers first:

docker run --rm --pull always \
  --cap-drop ALL \
  --security-opt no-new-privileges:true \
  --env-file .env \
  --env VPN_PROTOCOL=wireguard \
  --env PIA_CONNECT=false \
  --env DISABLE_IPV6=no \
  --env DIP_TOKEN=no \
  --env AUTOCONNECT=true \
  --env PIA_PF=true \
  --env PIA_DNS=true \
  --env PRIVATEERR_AUTO_RECOVER=false \
  --env PRIVATEERR_KEEPALIVE=false \
  --volume "$(pwd)/config/gluetun:/gluetun" \
  ghcr.io/scottgigawatt/privateerr:latest

Docker creates missing shared directories. Existing directories must allow container UID 0 to write and traverse them with all capabilities dropped. Confirm Generation complete. and the two files listed above under config/gluetun/wireguard/. Keep the credential file and generated state private.

Start Privateerr with Gluetun 🐳

The supplied stack requires amd64 or arm64 because of its qBittorrent image. Privateerr itself also supports arm/v7.

Complete the checkout and .env setup above.
Generate a shared recovery API key:
```
openssl rand -hex 24
```
Set PRIVATEERR_GLUETUN_API_KEY in .env to that value. Review qBittorrent's storage paths, user/group IDs, and Web UI port.
Pull the published images and start the three services:
```
make up
```

Check status and Privateerr's logs:

make ps
docker compose logs --tail 100 privateerr

Confirm Automatic recovery enabled and then Gluetun tunnel is healthy. Privateerr's container healthcheck proves startup readiness, not current tunnel health. Open qBittorrent on the configured host port (8080 by default), obtain its initial password from local container logs, and change it in the Web UI. Keep those logs private.

Long-running Privateerr installs both integration scripts into the shared config/gluetun/scripts/ directory before reporting ready, even with recovery disabled. No script copying is needed. UID 0 needs write and traverse access to the shared paths. The two installed filenames are replaced at startup; keep custom scripts under other names. Recreate all three services together when updating images.

Use make up-build for a source build. Direct Compose startup is available without Make. Buccaneerr stays out of normal startup; its live tests deliberately interrupt a disposable VPN.

Select a PIA region 🧭

Automatic selection is the default. To pin a region, set PIA_AUTOCONNECT=false and PIA_PREFERRED_REGION=YOUR-CHOSEN-PIA-REGION-ID in .env, replacing the placeholder with a PIA region id.

With curl and jq installed on the host, run make list-pia-regions to see all region IDs and port-forwarding support.

Recovery-enabled startup reuses valid saved files; changing these values alone does not replace a healthy connection. Follow the safe regeneration procedure.

Find commands and image channels ⚙️

Use make help for commands and the maintenance reference for backup and cleanup boundaries. Use latest for stable releases or edge for successful main builds; see image channels for exact tags and digests.

scottgigawatt/privateerr

Measured star growth

About

README.md