Supervisor developer overview 🧶
Privateerr's standard-library Python program coordinates PIA configuration generation and sustained-outage recovery. It runs in the existing Privateerr container, outside Gluetun's network namespace, so it can still reach PIA when the tunnel fails.
Understand the responsibilities¶
| Component | Responsibility | Source |
|---|---|---|
| Configuration | Validate environment settings and generation/recovery modes | docker/privateerr/config.py |
| HTTP client | Bound authenticated control requests, health probes, and catalog downloads | docker/privateerr/client.py |
| JSON validation | Narrow external values before inspecting their fields | docker/privateerr/data.py |
| Connection settings | Validate matching generated files and finish interrupted publication | docker/privateerr/settings.py |
| Filesystem diagnostics | Probe storage and explain failures without exposing configuration contents | docker/privateerr/diagnostics.py |
| Supervisor | Select endpoints, manage generation, and reconcile recovery state | docker/privateerr/supervisor.py |
| Generator | Invoke upstream PIA scripts, bound their output, and prepare matching metadata | docker/privateerr/generation.py |
| Logging | Format UTC records and redact upstream credentials before output | docker/privateerr/log.py |
| Script installer | Install image-owned Gluetun scripts before long-running startup readiness | docker/privateerr/scripts.py |
| Gluetun wrapper | Load saved metadata and configure the existing API and health listener | docker/gluetun/gluetun-entrypoint-wrapper.sh |
| Forwarding hook | Synchronize qBittorrent with Gluetun's port lease | docker/gluetun/qbittorrent-port-forwarding.sh |
The Python package starts through python3 -m privateerr. The image starts that command directly; supervisor.main() validates configuration, protects new files, installs shutdown handlers, and starts the supervisor. The Python reference documents the source contracts.
Keep the integration small¶
Keep upstream PIA scripts and Gluetun-local hooks in shell. Privateerr and Buccaneerr start their Python programs directly. Recovery state, deadlines, response validation, and candidate reconciliation belong in Python. Do not add a production web server, package dependency, Docker socket, or container lifecycle controller to solve a problem already handled through Gluetun's existing API.
The production image retains UID 0 for upstream scripts while the example drops all Linux capabilities and enables no-new-privileges. Read container hardening before changing generation or namespace configuration.
Understand startup modes¶
The supplied Compose example enables the built-in recovery supervisor. In a custom deployment, PRIVATEERR_AUTO_RECOVER defaults to false; recovery settings are validated only when enabled. Config.one_shot requires both keepalive and recovery disabled. This mode creates matching VPN files and exits without installing or changing Gluetun scripts. See configuration-only generation.
Select a development task¶
The base docker-compose.yml runs only the three published runtime images. Optional overlays select local builds or the Buccaneerr validator; Compose file selection explains the combinations, image names, and shared project identity. Including the test file activates live validation without a profile and can interrupt the VPN. Use a disposable checkout and follow the testing procedure for prerequisites, expected results, and cleanup.
Keep environment contracts, file paths, and port-forwarding ownership stable. Follow the architecture before changing startup or persistence, and run the relevant validation before updating a pull request.