SearXNG docs: document quadlet boot-persistence for the trio

Update SearXNG, Gluetun, and Valkey to describe the quadlet units instead of
compose: searxng sets Network=gluetun.container, the units install to
~/.config/containers/systemd/, and scripts/deploy-searxng-quadlet.sh deploys
them. Add a Boot Persistence section to the Stack doc. Correct the Gluetun
tunnel check (the :8000 server 404s; verify tun0 instead) and note the pinned
10.89.2.0/24 subnet.
This commit is contained in:
Frank committed 2026-08-18 23:42:45 -07:00
1 parent 71fe8c008f
commit f488382b08
4 files changed
+51 -24

No files matched your search

+22 -9
View File
@@ -16,17 +16,30 @@ SearXNG is a privacy-respecting metasearch engine. It aggregates results from ma
## VPN Routing (critical)
All SearXNG outbound traffic exits through the Gluetun VPN container. The container attaches to Gluetun's network namespace:
All SearXNG outbound traffic exits through the Gluetun VPN container. The searxng unit sets `Network=gluetun.container`, which makes it reuse gluetun's network namespace:
```yaml
services:
searxng:
network_mode: "service:gluetun"
depends_on:
- gluetun
```ini
[Container]
ContainerName=searxng
Network=gluetun.container
```
Port publishing happens on the **gluetun** service, not on searxng. See [[Gluetun]] and the knowledge base page [[VPN Routing for SearXNG]] (KB Pattern 2 is the one used here).
Port publishing happens on the **gluetun** unit, not on searxng. See [[Gluetun]] and the knowledge base page [[VPN Routing for SearXNG]] (KB Pattern 2 is the one used here).
## Boot Persistence (Quadlet)
The trio runs as quadlet units, not podman-compose, so it starts at boot. The unit files live in `searxng/quadlet/` and install to `~/.config/containers/systemd/`.
| Unit file | Service | Role |
|-----------|---------|------|
| `searxng.network` | `searxng-network.service` | DNS-enabled bridge, subnet pinned to 10.89.2.0/24 |
| `gluetun.container` | `gluetun.service` | WireGuard tunnel; publishes 8081:8080 |
| `searxng-valkey.container` | `searxng-valkey.service` | Valkey cache, alias `valkey` |
| `searxng.container` | `searxng.service` | Reuses gluetun's netns; publishes no port |
gluetun and valkey join the searxng network. searxng reuses gluetun's netns and reaches valkey by name on that network. Each unit sets `WantedBy=default.target`. User linger is on, so the units start at boot.
Deploy with `scripts/deploy-searxng-quadlet.sh dankclaw`. It copies the units, daemon-reloads, enables them, and starts them in dependency order.
## settings.yml Keys
@@ -75,7 +88,7 @@ Two lists control access:
The whole homelab LAN `192.168.0.0/24` is in both lists. This lets local agents and browsers poll the JSON API without tripping the 4-per-hour limit. `deploy.sh` copies the file into place on each deploy.
Access SearXNG through Caddy (`search.dankclaw.local`). A direct request on the published port has no `X-Forwarded-For` header. The bot-detection cannot resolve the client and returns 429. The podman bridge subnet is in `trusted_proxies` so Caddy's request is trusted. The bridge CIDR is assigned dynamically by rootless podman. Pin the network (`podman network create` with a fixed `--subnet`) for a stable value.
Access SearXNG through Caddy (`search.dankclaw.local`). A direct request on the published port has no `X-Forwarded-For` header. The bot-detection cannot resolve the client and returns 429. The searxng network subnet 10.89.2.0/24 is in `trusted_proxies` so Caddy's request is trusted. The subnet is pinned in `searxng.network`, so the value stays stable across reboots.
## Gotchas