obmp-docker/docs/PORTABILITY-FINDINGS.md

# Portability findings — what breaks on a greenfield deploy

Every artifact hit while standing this stack up on a fresh host (WSL2
`NWE-LT02`, Ubuntu 24.04, native docker-ce 29.x — 2026-07), ordered roughly as
encountered. Each one is something a clean deploy has to survive; most are now
handled automatically by `deploy.sh`/`setup.sh`. Kept as a checklist for the
next new host and as the rationale for the deploy tooling.

## 1. Bind-mounted volumes need pre-existing source dirs
`docker-compose.yml` binds `${OBMP_DATA_ROOT}/postgres/{data,ts}` with
`type:none,o:bind`. Docker will not create these; if absent, Postgres fails
with `no such file or directory`. `setup.sh` creates them — the error only
appears when setup.sh wasn't run on the target. deploy.sh double-checks the
dirs exist after setup.sh.

## 2. Stale HOST_IP survives a copied .env
A `.env` copied from another host carries that host's `HOST_IP`; setup.sh
validation only checks non-empty/not-"changeme", so the stale IP passes and
gets rendered into `gobgpd.conf` and the Grafana root URL. **This is the core
reason deploy.sh exists** — it reconciles HOST_IP (and warns when the .env
value isn't a local address) *before* setup.sh renders anything.

## 3. A populated .env is not a deployed host
The same copied .env had late-stage artifacts (Authelia secrets) while
early-stage host state (Postgres dirs) was missing — proof that setup.sh
completed on a *different* host. Run setup.sh per target, always.

## 4. WSL: HOST_IP is the NAT address; routers can't reach it
`hostname -I` in WSL returns the VM's NAT address — it changes on
`wsl --shutdown` and physical routers cannot reach it. Routers must target the
**Windows LAN IP**, forwarded into WSL via `netsh portproxy`
(`scripts/wsl-portproxy.ps1`). deploy.sh separates "router-facing IP:port"
from HOST_IP and auto-detects the Windows LAN IP via powershell.exe interop.

## 5. Cold-start contention masquerades as component bugs
Bringing the whole stack up at once crash-looped Kafka on a preflight
"writable" check that was actually resource contention, not permissions.
deploy.sh stages the bring-up: infra (zookeeper/kafka) -> psql -> core ->
feeders.

## 6. Size for BMP burst, not steady state
Generic docs say the collector is light — true, and misleading: the store
saturates under burst (full table x monitored sessions, Postgres write
amplification). See docs/DEPLOYMENT-TYPES.md for the full model.

## 7. Ports 5000 and 3000 are crowded
The collector's 5000 and Grafana's 3000 are commonly already occupied.
deploy.sh runs a port-collision preflight before touching anything. The
router-facing BMP port default moved 5000 -> **1790** (the IANA BMP port);
the collector still listens on 5000 inside the container.

## 8. Docker Desktop breaks host bind mounts on WSL (the big one)
Symptom: Postgres mount fails `no such file or directory` on a path `ls`
shows exists. Cause: Docker Desktop runs the daemon in its own WSL distro
(`docker-desktop` VM), so host bind mounts resolve against *that* filesystem,
not the distro you ran compose from. No mkdir fixes it. **Fix: native
docker-in-WSL** — disable Desktop's WSL integration, install docker-ce,
`systemctl enable --now docker`, and confirm
`docker info | grep 'Operating System'` does not say Docker Desktop.
deploy.sh detects Docker Desktop and warns/refuses.

### 8b. Desktop residue splits the mount namespace
After installing native docker, the CLI couldn't reach `/run/docker.sock`
even though dockerd held it — a stale mount-namespace split left by Desktop.
`wsl --shutdown` and reopening the distro cleared it.

## 9. Grafana customizations must live in the repo, not grafana.db
Dashboards hand-built in the UI exist only in that host's `grafana.db` and
vanish on a greenfield deploy. All dashboards are now committed as JSON under
`obmp-grafana/dashboards/` and setup.sh syncs both provisioning YAML *and*
dashboard JSONs to the data root. If you edit a dashboard in the UI, export
and commit the JSON.

## 10. Blanket `chmod -R 777` on the data root breaks Postgres re-deploys
setup.sh's lab-permissive chmod over an *existing* data tree made
`psql_server.key` world-accessible; Postgres refuses to boot
(`FATAL: private key file ... has group or world access`) and the whole core
cascades down. Fresh installs never hit it (the key is generated after the
chmod) — it is strictly a re-deploy bug. setup.sh now skips `postgres/`
(the image entrypoint owns those perms) and re-tightens the key/cert to 0600
if a previous run already clobbered them.

## 11. docker-ce 29 rejects Docker API < 1.40 — old pinned clients break
telegraf 1.28's `[[inputs.docker]]` hardcodes Docker API version 1.24, which
docker-ce >= 29 refuses (`client version 1.24 is too old`). Every
per-container stack metric silently never reached InfluxDB; the stack
dashboards sat empty while `disk`/`postgresql_*` inputs worked fine.
`DOCKER_API_VERSION` env is ignored (version pinned in code) — the fix is
telegraf >= 1.30, which negotiates the API version (telegraf/Dockerfile now
pins 1.33). Watch for the same failure in any other tooling that talks to the
daemon with an old vendored client.

## 12. OPEN: router-side automation still targets the old lab's values
`cml/proxmox_bmp_config.py` sends routers at `HOST_IP` port `5000`, and
`cml/xrd-node-definition.yaml` bakes in `10.40.40.202:5000` — both correct on
the old native-Linux dev lab, wrong on a WSL host (finding 4: routers must
target the router-facing address, and the port default is now 1790). Fold
`ROUTER_FACING_IP`/`ROUTER_FACING_PORT` from `.env` into that tooling when
the 5000-vs-1790 decision lands. See docs/router-bmp-config.md.