Context
Surfaced during the writing of the Deployment Cookbook (#10800). The repo currently lacks canonical infrastructure-as-code artifacts for containerizing the Knowledge Base and Memory Core MCP servers.
The Problem
External operators are forced to independently derive the Dockerfile and docker-compose.yml topology, risking misconfigurations (e.g., exposing SQLite files improperly, incorrect network bridges to Chroma).
The Architectural Reality
We run Node.js processes for KB and MC alongside a Python-based Chroma DB. These need isolated filesystems but shared network routing.
The Fix
Author reference Dockerfile and docker-compose.yml artifacts in a new deploy/ or infrastructure/ directory to serve as a baseline for operators.
Acceptance Criteria
Out of Scope
Publishing pre-built images to a container registry.
Contract Ledger (T3)
Per canonical specification in learn/agentos/contract-ledger.md. Authored 2026-05-06 via batch-Ledger-upgrade pass on cookbook follow-ups (#10801-#10805) — proposed by @neo-opus-4-7 (systemic gap A2A) and explicitly delegated to body-incorporation by @neo-gemini-3-1-pro per ticket-create-workflow §11 Authorship Respect delegation pattern.
| Target Surface |
Source of Authority |
Proposed Behavior |
Fallback / Edge Case |
Docs |
Evidence |
Reference container artifacts: deploy/Dockerfile.kb + deploy/Dockerfile.mc (or single Dockerfile with build args) + deploy/docker-compose.yml |
#10801, parent #9999, surfacing PR #10806 cookbook Section 2 (Container Packaging — recommended two-images sidecar pattern) |
Reference Dockerfiles use Node.js base image + appropriate entrypoints (node ai/mcp/server/knowledge-base/Server.mjs for KB; symmetric for MC). Reference docker-compose.yml orchestrates shared Chroma (with persistent volume + healthcheck) + dual MCP servers (private network) + reference reverse proxy upstream (cross-link to #10803). Internal network: Chroma reachable only from MCP server containers (no external port exposure); MCP servers reachable from reverse proxy only. Chroma host/port consumed via NEO_CHROMA_HOST/NEO_CHROMA_PORT per #10808 ergonomics direction. |
Single-image-two-processes shape supportable via build args (operator preference for resource consolidation). Stand-alone development variant of docker-compose.dev.yml with relaxed networking + bind-mounts for hot-reload (separate from production-shape compose file). Tmpfs-mode option for Chroma when used as test fixture (cross-link to #10805). |
Update learn/agentos/DeploymentCookbook.md Section 2 (Container Packaging) — replace "(Note: Reference Dockerfile and docker-compose.yml artifacts are pending under #10801)" with link to the now-shipped artifacts. Cross-link from SharedDeployment.md deployment-mechanics section. |
L2 — docker compose up brings the stack to healthy state; curl http://localhost:<KB_PORT>/healthcheck and curl http://localhost:<MC_PORT>/healthcheck both return status: healthy against the dockerized stack. Manual verification documented in PR body. Empirical regression-catch: induce a deliberate misconfiguration (e.g., wrong Chroma host) and confirm healthcheck flags it. |
Origin Session ID: 88a6ed3a-b1b9-461a-aaf3-7c9984bd12e7
Retrieval Hint: Deployment Cookbook gap surfacing
Context
Surfaced during the writing of the Deployment Cookbook (#10800). The repo currently lacks canonical infrastructure-as-code artifacts for containerizing the Knowledge Base and Memory Core MCP servers.
The Problem
External operators are forced to independently derive the
Dockerfileanddocker-compose.ymltopology, risking misconfigurations (e.g., exposing SQLite files improperly, incorrect network bridges to Chroma).The Architectural Reality
We run Node.js processes for KB and MC alongside a Python-based Chroma DB. These need isolated filesystems but shared network routing.
The Fix
Author reference
Dockerfileanddocker-compose.ymlartifacts in a newdeploy/orinfrastructure/directory to serve as a baseline for operators.Acceptance Criteria
Dockerfile.kbandDockerfile.mc(or a unified container approach) authored.docker-compose.ymlauthored demonstrating the shared Chroma + dual MCP server topology.Out of Scope
Publishing pre-built images to a container registry.
Contract Ledger (T3)
Per canonical specification in
learn/agentos/contract-ledger.md. Authored 2026-05-06 via batch-Ledger-upgrade pass on cookbook follow-ups (#10801-#10805) — proposed by @neo-opus-4-7 (systemic gap A2A) and explicitly delegated to body-incorporation by @neo-gemini-3-1-pro perticket-create-workflow §11Authorship Respect delegation pattern.deploy/Dockerfile.kb+deploy/Dockerfile.mc(or singleDockerfilewith build args) +deploy/docker-compose.ymlnode ai/mcp/server/knowledge-base/Server.mjsfor KB; symmetric for MC). Referencedocker-compose.ymlorchestrates shared Chroma (with persistent volume + healthcheck) + dual MCP servers (private network) + reference reverse proxy upstream (cross-link to #10803). Internal network: Chroma reachable only from MCP server containers (no external port exposure); MCP servers reachable from reverse proxy only. Chroma host/port consumed viaNEO_CHROMA_HOST/NEO_CHROMA_PORTper #10808 ergonomics direction.docker-compose.dev.ymlwith relaxed networking + bind-mounts for hot-reload (separate from production-shape compose file). Tmpfs-mode option for Chroma when used as test fixture (cross-link to #10805).learn/agentos/DeploymentCookbook.mdSection 2 (Container Packaging) — replace "(Note: ReferenceDockerfileanddocker-compose.ymlartifacts are pending under #10801)" with link to the now-shipped artifacts. Cross-link fromSharedDeployment.mddeployment-mechanics section.docker compose upbrings the stack to healthy state;curl http://localhost:<KB_PORT>/healthcheckandcurl http://localhost:<MC_PORT>/healthcheckboth returnstatus: healthyagainst the dockerized stack. Manual verification documented in PR body. Empirical regression-catch: induce a deliberate misconfiguration (e.g., wrong Chroma host) and confirm healthcheck flags it.Origin Session ID: 88a6ed3a-b1b9-461a-aaf3-7c9984bd12e7 Retrieval Hint: Deployment Cookbook gap surfacing