v1.2.2 - fix(deploy): v1.1.x upgrade path broke the engine - compose + docs + health guidance (#187)
🚨 The Problem (issue #187)
- v1.2.0 split Omnibus into web + engine containers, but v1.1.x deployments were single-container and pinned to :latest - the release "upgraded" them in place into a stack with NO engine service, so every scan/conversion/metadata/search job died with bare "fetch failed" and the health panel said "Engine unreachable"
- The published v1.2.1 images themselves are fine (the engine image is byte-identical to v1.2.0 except the baked version stamp) - this was an upgrade-path and docs failure, not a build failure
🧭 Fixes
- README.md + README-docker.md installation compose was STILL the v1.1.x single-container stack (no engine!) - replaced with the real three-service topology (web + omnibus-engine + redis, OMNIBUS_ENGINE_URL, shared NEXTAUTH_SECRET + volume mounts) and a prominent "Upgrading from v1.1.x?" callout; README-docker.md flows to the Docker Hub description on this build
- docker-compose.yml + docker-compose.postgres.yml still defaulted to the FROZEN :unified image tags from before the branch promotion (stuck at 1.1.0-beta.100 since July 14) - defaults flipped to :latest, with a comment documenting the :dev override
- Health check: an unreachable engine is now a red ERROR (was a cosmetic warning) whose message names the URL it tried and the classic cause - a pre-v1.2 compose file missing the omnibus-engine service - with exactly what to add
✅ Verification
- Root cause proven from registry evidence: engine :latest layers are identical to v1.2.0 except the 144-byte version layer; legacy archive/main-node-final compose confirmed engine-less on :latest; :unified tags confirmed frozen at rev 2886d3b
- tsc clean; vitest 376/376 (new test: unreachable engine -> error status, actionable message, DEGRADED overall)
- Compose YAML parses clean with :latest defaults in both profiles