Frank
90c4ac69a7
Fanned out 5 read-only doc-auditor subagents (one per service group) that fact-checked the knowledge base against the live system + repo config, researched official setup docs online, and verified progress. Applied: - All 34 broken links fixed (real pages / external URLs / correct relative paths); 0 broken links remain. No .AGENTTRASH links (the 4 mentions are accurate descriptive text, not links). - Fact-check fixes: Readarr retired (May 2026), Radarr v4->v6, Calibre 9.2.1 live, Calibre-Web 0.6.25 live, Copyparty v1.20.21, LLM index ncmoe 38 + 786432 ctx, frank-default-small active (not frank-pp-worker), Hermes/SearXNG/Grafana hostnames, Loki/Alloy local images, Observability diagram (Promtail->Alloy), VLLM retired note, DFlash status, benchmark live-drift notes, Homepage test count 116.
75 lines
2.5 KiB
Markdown
75 lines
2.5 KiB
Markdown
# Gluetun
|
|
|
|
Gluetun is a lightweight VPN client container. It connects to a VPN provider (WireGuard or OpenVPN) and shares that tunnel with other containers that attach to its network namespace.
|
|
|
|
**Host:** Dankclaw — **Docs:** https://github.com/qdm12/gluetun
|
|
|
|
## Facts (from research, primary source)
|
|
|
|
| Item | Value |
|
|
|------|-------|
|
|
| Image | `qmcgaw/gluetun:latest` |
|
|
| Capabilities | `NET_ADMIN` required |
|
|
| Device | `/dev/net/tun:/dev/net/tun` |
|
|
| Ports published | searxng's 8081 → 8080 lives here |
|
|
| Tunnel check | the `tun0` interface exists (the `:8000` server 404s on all paths) |
|
|
|
|
## Required Environment
|
|
|
|
```yaml
|
|
environment:
|
|
VPN_SERVICE_PROVIDER: "${VPN_SERVICE_PROVIDER}" # e.g. mullvad, protonvpn
|
|
VPN_TYPE: wireguard
|
|
WIREGUARD_PRIVATE_KEY: "${WIREGUARD_PRIVATE_KEY}" # from .env, never committed
|
|
```
|
|
|
|
- `VPN_TYPE` default is `openvpn`; WireGuard preferred when the provider supports it.
|
|
- Provider-specific variables come from the Gluetun wiki; set them in `.env`.
|
|
|
|
## Optional DNS (from research)
|
|
|
|
| Variable | Default | Purpose |
|
|
|----------|---------|---------|
|
|
| `DNS_UPSTREAM_RESOLVER_TYPE` | `dot` | DNS over TLS |
|
|
| `DNS_UPSTREAM_RESOLVERS` | `cloudflare` | upstream DoT providers |
|
|
| `DNS_CACHING` | `on` | cache queries |
|
|
| `BLOCK_MALICIOUS` | `on` | block malicious hostnames |
|
|
|
|
Warning from the wiki: do NOT set `DNS_UPSTREAM_PLAIN_ADDRESSES` to a LAN/bridge address — DNS queries leak out of the tunnel.
|
|
|
|
## Attaching a Container
|
|
|
|
The searxng unit reuses gluetun's network namespace:
|
|
|
|
```ini
|
|
[Container]
|
|
ContainerName=searxng
|
|
Network=gluetun.container
|
|
```
|
|
|
|
`Network=gluetun.container` also adds a systemd dependency on gluetun, so searxng starts after the tunnel.
|
|
|
|
## Boot Persistence
|
|
|
|
gluetun runs as the `gluetun` quadlet unit (see [[SearXNG]] for the full trio). It sets `WantedBy=default.target` and user linger is on, so the tunnel starts at boot. The WireGuard credentials live in `/opt/searxng/.env` (mode 0600). Deploy with `scripts/deploy-searxng-quadlet.sh dankclaw`.
|
|
|
|
## Verify the Tunnel
|
|
|
|
```bash
|
|
podman exec gluetun curl -s ifconfig.me
|
|
```
|
|
|
|
The returned IP must differ from the host IP.
|
|
|
|
## Gotchas
|
|
|
|
- The container that holds the published port must be the one with the ports mapping (gluetun).
|
|
- `restart: always` on gluetun so the tunnel reconnects after VPN drops.
|
|
- When gluetun restarts, attached containers inherit the new network state; searxng may need a restart to re-resolve DNS.
|
|
|
|
## See Also
|
|
|
|
- [[SearXNG]] — the consumer of the tunnel
|
|
- [[Dankclaw Stack]]
|
|
- Knowledge base: [[SearXNG]]
|