echo6-docs/vault/runbooks/meshai-prod-compose-override.md

---
title: meshai prod compose override (cutover state + MeshCore radio)
type: runbook
tags:
  - mesh
aliases: []
related:
  - [[meshai-region-routing-plan]]
  - [[meshcore-transport]]
  - [[meshai]]
  - [[meshai-config-hot-apply]]
  - [[SESSION-HANDOFF-meshai-test]]
updated: 2026-07-13
---

# meshai prod compose override

Backup + restore for `docker-compose.override.yml` on **CT 108** (the [[meshai]]
production host). This file is **untracked and prod-only** — it exists nowhere
but `/home/zvx/meshai/work/docker-compose.override.yml`, is not in the public
`zvx-echo6/meshai` repo, and carries no git trace. If the deploy tree is
re-cloned or wiped, production silently reverts to shadow-mode alerts and loses
the MeshCore radio. This runbook is its durable copy.

Docker Compose auto-merges `docker-compose.override.yml` over the committed
`docker-compose.yml`, so both settings below are live without any extra flag.

## Verbatim contents (as of 2026-07-07)

```yaml
services:
  meshai:
    environment:
    - MESHAI_CUTOVER_CATEGORIES=earthquake_event,geomagnetic_storm,rf_propagation_alert,avalanche_warning,avalanche_watch,weather_warning,weather_statement,work_zone,road_incident,road_closure,traffic_congestion,stream_flow,wildfire_declared,wildfire_incident,wildfire_closed
    devices:
    - /dev/meshcore-rak:/dev/meshcore-rak
```

## What each line does

- **`MESHAI_CUTOVER_CATEGORIES`** — the staged-cutover switch consumed by
  `meshai/notifications/cutover.py` (`is_cutover()`). Each hazard category is
  migrated onto the shared formatter+decider pipeline in shadow-only mode first
  (old handler broadcasts live; new code dry-runs and logs mismatches to
  `/app/data/shadow/<category>.jsonl`). Adding a category name here **flips it
  live** onto the new formatter+decider and stops the shadow comparison. The
  list above is effectively the full hazard set → the all-native cutover is
  complete in prod. Empty/unset = nothing cut over (pure shadow bake).
  Note: the three `wildfire_*` categories are *also* force-enabled directly in
  code (`NATIVE_ALWAYS_DECIDE` in `cutover.py`) regardless of this var, because
  the fire decider itself is the dedup/cooldown gate.
- **`devices: /dev/meshcore-rak`** — passes the RAK4631 MeshCore USB radio on
  the utility host into the container at a stable udev symlink path. Without it
  the container cannot see the MeshCore hardware (see [[meshcore-transport]]).

Both are [[deployment]] state (cutover progress + host-specific device path), which
is why they live in an override rather than the committed public compose file.

## Restore

```bash
# from root@utility (100.64.0.5); zvx has no sudo on CT 108
pct exec 108 -- bash -lc 'cat > /home/zvx/meshai/work/docker-compose.override.yml <<"EOF"
services:
  meshai:
    environment:
    - MESHAI_CUTOVER_CATEGORIES=earthquake_event,geomagnetic_storm,rf_propagation_alert,avalanche_warning,avalanche_watch,weather_warning,weather_statement,work_zone,road_incident,road_closure,traffic_congestion,stream_flow,wildfire_declared,wildfire_incident,wildfire_closed
    devices:
    - /dev/meshcore-rak:/dev/meshcore-rak
EOF'
# then rebuild/recreate so the merge takes effect
pct exec 108 -- bash -lc 'cd /home/zvx/meshai/work && docker compose up -d'
```

Verify after restore: `docker exec meshai printenv MESHAI_CUTOVER_CATEGORIES`
returns the list, and `docker exec meshai ls -l /dev/meshcore-rak` shows the
device inside the container.