docs(ops): dormant services documentation refresh - #792
Merged
Merged
Conversation
Add new Model Management section documenting up-model-management, down-model-management, and health-dormant targets introduced in PR #791. Update Preflight section to document bringup-layered now including the model-management layer between minimal and workers. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…RY.md Register port 8200 (GPU Orchestrator) and port 8074 (Transcribe Backend) in the Core Services tier. Update the 8200-8999 range example to include GPU Orchestrator alongside Archon. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Document health endpoints, additional APIs, NATS subjects, and availability notes for model-registry (8110), gpu-orchestrator (8200), and transcribe-backend (8074). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…nd to services-catalog Add full catalog entries for the three formerly-dormant services activated in PRs #787-791. Includes ports, APIs, NATS subjects, dependencies, compose profiles, and lifecycle notes. Updates Quick Reference health endpoint listing. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
📝 WalkthroughWalkthroughAdded three services (Model Registry, GPU Orchestrator, Transcribe Backend) to docs and orchestration: ports, health endpoints, NATS topics, compose profiles, port-collision note; added Model Management Make targets and layered bring-up ordering plus showtime verification targets. Changes
Sequence Diagram(s)sequenceDiagram
participant Dev as Developer/Make
participant Orch as docker-compose (Orchestration)
participant Docker as Docker Engine
participant MR as Model Registry
participant GPU as GPU Orchestrator
participant Workers as Workers
participant Agents as Agents
participant Monitor as Monitoring
rect rgba(100,149,237,0.5)
Dev->>Orch: make bringup-layered
Orch->>Docker: start minimal services
Orch->>Docker: start model-management (MR, GPU)
Docker->>GPU: detect NVIDIA runtime (optional)
Docker->>MR: expose /health
Docker->>GPU: expose /health, /metrics
Orch->>Docker: wait/check health-dormant statuses
Orch->>Docker: start Workers
Orch->>Docker: start Agents
Orch->>Monitor: start monitoring
Orch->>Dev: emit showtime artifacts (links, JSON)
end
Estimated Code Review Effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (1)
pmoves/docs/operations/SERVICE_HEALTH_ENDPOINTS.md (1)
45-63: Clarify Docker health-status behavior for GPU Orchestrator and Transcribe Backend.Since these services currently expose HTTP health endpoints but lack compose
healthcheckblocks, add a short note to prevent confusion when operators seerunninginstead ofhealthyin container status outputs.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@pmoves/docs/operations/SERVICE_HEALTH_ENDPOINTS.md` around lines 45 - 63, Add a short clarifying note under both "GPU Orchestrator" and "Transcribe Backend" explaining that although each service exposes an HTTP health endpoint (health path `/healthz`), the Docker Compose files do not include a `healthcheck` block, so `docker ps` may show the container as "running" rather than "healthy"; reference the service names ("GPU Orchestrator", "Transcribe Backend") and the health path `/healthz`, and suggest either adding a Compose `healthcheck` or noting that operators should query the HTTP endpoint directly to verify health.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.claude/context/services-catalog.md:
- Around line 124-138: The Model Registry entry currently lists "Ports: 8110"
which collides with the BoTZ VPN MCP Server also documented as 8110; either
change the Model Registry port to a non-conflicting value (update the "Ports:
8110" line and any Compose/service config associated with the Model Registry) or
add an explicit conflict note clarifying profile separation (mentioning that
Model Registry uses compose profile "orchestration" and should not be exposed
when BoTZ VPN MCP Server is active) so operators know which service owns 8110;
update the "Ports: 8110" line or add a sentence like "Port 8110 collides with
BoTZ VPN MCP Server — ensure only one profile exposes this port or change one
service's port" and ensure any referenced NATS/Compose profile info remains
consistent with the change.
In `@pmoves/docs/operations/MAKE_TARGETS.md`:
- Line 28: Update the GPU-detection command in MAKE_TARGETS.md to match the
Makefile: replace the documented `docker info --format '{{json .Runtimes}}' |
grep nvidia` with the exact command used in the implementation `docker info
--format '{{json .Runtimes}}' | grep -qi nvidia` so the docs and the Makefile
(the GPU detection logic) stay in sync.
In `@pmoves/docs/operations/PORT_REGISTRY.md`:
- Line 15: The table row currently reads "8200-8999 | Orchestration Services |
GPU Orchestrator 8200, Archon 8181" but Archon 8181 falls outside the 8200-8999
range; update that row so the example matches the range by either replacing
"Archon 8181" with an in-range instance (e.g., "Archon 8281" or another
identifier between 8200–8999) or change the displayed range to include 8181 (for
example "8100-8999") so the example and range are consistent.
---
Nitpick comments:
In `@pmoves/docs/operations/SERVICE_HEALTH_ENDPOINTS.md`:
- Around line 45-63: Add a short clarifying note under both "GPU Orchestrator"
and "Transcribe Backend" explaining that although each service exposes an HTTP
health endpoint (health path `/healthz`), the Docker Compose files do not
include a `healthcheck` block, so `docker ps` may show the container as
"running" rather than "healthy"; reference the service names ("GPU
Orchestrator", "Transcribe Backend") and the health path `/healthz`, and suggest
either adding a Compose `healthcheck` or noting that operators should query the
HTTP endpoint directly to verify health.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: a845e662-a979-48ee-89de-bce9eb2ab598
📒 Files selected for processing (4)
.claude/context/services-catalog.mdpmoves/docs/operations/MAKE_TARGETS.mdpmoves/docs/operations/PORT_REGISTRY.mdpmoves/docs/operations/SERVICE_HEALTH_ENDPOINTS.md
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@pmoves/docs/operations/MAKE_TARGETS.md`:
- Around line 265-268: Update the documentation for the make target
bringup-layered to avoid claiming readiness gating; change the wording that
currently says the model-management layer "ensures model-registry and
(optionally) gpu-orchestrator are ready before dependent workers start" to
something like "starts model-registry and (optionally) gpu-orchestrator before
workers" to match the Makefile behavior (the make target bringup-layered simply
runs up-model-management then up-workers sequentially without health checks or
polling), and ensure any “Model management ready” wording is removed or
rephrased to reflect that docker compose up -d only starts services and does not
wait for actual service readiness.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 5a6915a1-ac69-4fc5-bed8-75a2c35bf8dd
📒 Files selected for processing (3)
.claude/context/services-catalog.mdpmoves/docs/operations/MAKE_TARGETS.mdpmoves/docs/operations/PORT_REGISTRY.md
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@pmoves/docs/operations/MAKE_TARGETS.md`:
- Line 36: Update the documentation line that currently reads "Reports
per-service: `healthy` / `running` (no healthcheck) / `starting` / `FAIL` /
`SKIP`" to reflect the actual output of the make target; change it to state that
make health-dormant emits `OK` / `STARTING` / `FAIL` / `SKIP`, and note that
both `healthy` and `running` map to `OK` so operators won’t confuse the expected
output when matching smokes or runbooks. Target the text mentioning `make
health-dormant` / the "Reports per-service" status list and replace the labels
and mapping explanation accordingly.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 09c9f929-89ae-41a9-9140-f3af729a575c
📒 Files selected for processing (1)
pmoves/docs/operations/MAKE_TARGETS.md
4 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
MAKE_TARGETS.mddocumentingup-model-management,down-model-management, andhealth-dormanttargets (PR fix(make): harden dormant model-management lifecycle targets #791)bringup-layereddocumentation showing model-management layer in the deterministic bring-up sequencePORT_REGISTRY.mdSERVICE_HEALTH_ENDPOINTS.mdservices-catalog.mdwith ports, APIs, NATS subjects, dependencies, and compose profilesCloses documentation gaps from PRs #787-790 (dormant service activation) and PR #791 (Makefile lifecycle hardening).
Test plan
PORT_REGISTRY.md(grep -E '^\| [0-9]+' | awk -F'|' '{print $2}' | sort | uniq -d).claude/context/nats-subjects.mdbringup-layeredlayer ordering matches actual Makefile🤖 Generated with Claude Code
Summary by CodeRabbit