obmp-docker/docs/handoff/00-HANDOFF-BRIEF.md

Handoff brief — OpenBMP greenfield deployment work

From: Claude (chat instance) working with Sam on deployment/portability. To: Claude (VSCode instance) working directly in the obmp-docker Gitea repo. Date: 2026-07-20.

We don't share memory. This packet is the bridge. Sam is the channel between us.

---

One-paragraph summary

Sam is standing the obmp-docker stack up on a new WSL2 host (NWE-LT02, Ubuntu 24.04), separate from the dev lab, to shake out greenfield-portability problems before prod. Over this session we built a deploy.sh wrapper around the repo's existing setup.sh that reconciles host-specific .env values before provisioning, plus supporting docs. We hit and fixed a long chain of deployment artifacts (details in 02-FINDINGS.md). The stack is now finally pulling images and coming up on a native docker daemon after the big blocker — Docker Desktop's cross-VM bind-mount failure — was resolved by switching to native docker-in-WSL. Current open thread: Grafana came up without its expected customizations, and we're not sure the repo checkout is on the right branch. That's where you come in — you can see the repo directly.

---

What this session produced (lives in Sam's chat outputs, not the repo yet)

A deploy.sh + docs bundle intended to drop into the repo root. Sam has these files; they are NOT yet committed to the repo (that's a decision for you + Sam):

• deploy.sh — interactive greenfield deploy wrapper (see 01-DEPLOY-SCRIPT.md)
• DEPLOYMENT-TYPES.md — the three deployment types, locked
• PORTABILITY-FINDINGS.md — everything that broke and why
• router-bmp-config.md — IOS-XR BMP config reference
• README.md — bundle overview

If you want to integrate these into the repo, coordinate branch/placement with Sam. They were written against the repo's current setup.sh, .env.example, and docker-compose.yml as pasted into chat.

---

THE OPEN QUESTION FOR YOU (highest priority)

Grafana is up but its customizations are missing. Sam expected them to be "part of the repo." Then Sam raised the real doubt: "did I even pull the correct branch?"

You can answer this directly — you have the repo. Please determine:

1. What branch/commit is the working checkout on? git branch --show-current && git log --oneline -5 && git status

2. Is the Grafana provisioning committed, and on which branch? The stack provisions Grafana from obmp-grafana/provisioning/ (setup.sh copies it to ${OBMP_DATA_ROOT}/grafana/provisioning/, bind-mounted into the container). Check whether dashboards/datasources actually exist in the tree, and on which branch:

   git ls-tree -r --name-only HEAD -- obmp-grafana/provisioning/
   git branch -a
   git ls-tree -r --name-only origin/main -- obmp-grafana/provisioning/
   # and any feature branch you've been working on
   

3. Were the Grafana customizations ever committed as code, or did they only ever exist as UI state in a grafana.db (i.e. hand-built, never exported to provisioning)? This is the crux: "supposed to be in the repo" may have been intent, not reality. You'd know — did you commit dashboard JSON?

The fork:

• On wrong branch → check out the right one, redeploy; provisioning returns.
• Right branch, provisioning present but not loading → permissions/timing; docker compose restart grafana after confirming files are in /var/openbmp/grafana/provisioning/.
• Provisioning never committed → the customizations were UI-only; they need exporting to the repo now so future greenfield deploys reproduce them. This is itself a portability finding.

---

Immediate deployment state (as of handoff)

• Host: WSL2, Ubuntu 24.04.4, NWE-LT02, 22 vCPU / ~15 GB RAM.
• Daemon: native docker-ce 29.6.2 (NOT Docker Desktop — that was the bug). docker info confirms Operating System: Ubuntu 24.04.4 LTS.
• OBMP_DATA_ROOT=/var/openbmp (native ext4, /dev/sdg).
• Deploy command in use: ./deploy.sh --wsl --scope full-stack --auth local
• Stack was pulling images and progressing past the volume-mount failure that blocked every earlier attempt.
• Grafana reachable at http://<wsl-ip>:3000/grafana/, login admin/openbmp.

See 02-FINDINGS.md for the full list of what broke and how it was fixed, and 03-NEXT-STEPS.md for what remains.