docs(rollout): add SPA-rollout runbook to prevent two-build LB skew (MAPPS-315) #369

Merged

Claude-Run merged 1 commit from docs/MAPPS-315-spa-rollout-runbook into main

2026-06-26 09:13:20 +02:00

Claude-Run commented

2026-06-26 09:11:47 +02:00

Member

Captures the procedure that keeps the load balancer from serving two different mokosh-www builds at once, the root cause behind the MAPPS-315 sidebar/Settings inconsistency.

The skew happens when the LB fronts more than one replica pulling a floating :latest tag: a rolling restart re-pulls the new digest on one replica while the other lags on the old one, so navigation differs per request (missing/extra ADMIN section, /settings misroute in the stale bundle) until the second restart lands. The /settings route is already declared, so its misroute is a stale-bundle symptom, not a missing route.

The fix lives in the deployment repo (NiceGuyIT/docker, per dev-docs/milestone-1-handoff.md): pin a versioned :vX.Y.Z image tag per deploy in docker/server/<host>/mokosh-apps/compose-variables.yml (mirroring nc-01's existing pin) so a rollout flips every replica to the same immutable digest in lockstep. The runbook documents the pin, the pull-then-up lockstep sequence, and a curl loop that verifies every replica returns the same _mokosh_config.js build_sha. Indexed in dev-docs/README.md.

This satisfies AC3 (the runbook) in mokosh-apps; AC1/AC2 execute against the deployment repo per the runbook, and AC4 needs no code change.

#MAPPS-315

Captures the procedure that keeps the load balancer from serving two different mokosh-www builds at once, the root cause behind the MAPPS-315 sidebar/Settings inconsistency. The skew happens when the LB fronts more than one replica pulling a floating `:latest` tag: a rolling restart re-pulls the new digest on one replica while the other lags on the old one, so navigation differs per request (missing/extra ADMIN section, `/settings` misroute in the stale bundle) until the second restart lands. The `/settings` route is already declared, so its misroute is a stale-bundle symptom, not a missing route. The fix lives in the deployment repo (`NiceGuyIT/docker`, per dev-docs/milestone-1-handoff.md): pin a versioned `:vX.Y.Z` image tag per deploy in `docker/server/<host>/mokosh-apps/compose-variables.yml` (mirroring nc-01's existing pin) so a rollout flips every replica to the same immutable digest in lockstep. The runbook documents the pin, the pull-then-up lockstep sequence, and a curl loop that verifies every replica returns the same `_mokosh_config.js` `build_sha`. Indexed in dev-docs/README.md. This satisfies AC3 (the runbook) in mokosh-apps; AC1/AC2 execute against the deployment repo per the runbook, and AC4 needs no code change. #MAPPS-315

Claude-Run added 1 commit

2026-06-26 09:11:47 +02:00

docs(rollout): add SPA-rollout runbook to prevent two-build LB skew (MAPPS-315)

Check / fmt + clippy + tests (pull_request) Successful in 1m18s

Details

Create release / Create release from merged PR (pull_request) Has been skipped

Details

d0c84980b3

Captures the procedure that keeps the load balancer from serving two different mokosh-www builds at once, the root cause behind the MAPPS-315 sidebar/Settings inconsistency.

The skew happens when the LB fronts more than one replica pulling a floating `:latest` tag: a rolling restart re-pulls the new digest on one replica while the other lags on the old one, so navigation differs per request (missing/extra ADMIN section, `/settings` misroute in the stale bundle) until the second restart lands. The `/settings` route is already declared, so its misroute is a stale-bundle symptom, not a missing route.

The fix lives in the deployment repo (`NiceGuyIT/docker`, per dev-docs/milestone-1-handoff.md): pin a versioned `:vX.Y.Z` image tag per deploy in `docker/server/<host>/mokosh-apps/compose-variables.yml` (mirroring nc-01's existing pin) so a rollout flips every replica to the same immutable digest in lockstep. The runbook documents the pin, the pull-then-up lockstep sequence, and a curl loop that verifies every replica returns the same `_mokosh_config.js` `build_sha`. Indexed in dev-docs/README.md.

This satisfies AC3 (the runbook) in mokosh-apps; AC1/AC2 execute against the deployment repo per the runbook, and AC4 needs no code change.

#MAPPS-315