Docs: add Docker Compose runtime guide

FILE_INDEX.md

@@ -39,6 +39,8 @@ https://github.com/Open-Factory-Initiative/Factory-Intelligence-Platform
 - `docs/GOVERNED_ACTIONS.md` — recommendation and approval model
 - `docs/API_DESIGN.md` — initial API shape
 - `docs/TESTING.md` — unit/integration/contract/e2e strategy
+- `docs/runtime/DOCKER_COMPOSE.md` — Docker Compose runtime guide
+- `docs/runtime/TROUBLESHOOTING.md` — local runtime troubleshooting guide
 - `docs/DEVELOPMENT.md` — local development workflow
 - `docs/DOCUMENTATION.md` — documentation standards
 - `docs/OBSERVABILITY.md` — logging/metrics/traceability direction

README.md

@@ -113,6 +113,10 @@ curl http://localhost:8000/health
 docker compose -f infra/docker/docker-compose.yml down
 ```
 
+Use `docker compose down` for normal shutdown. Use
+`docker compose -f infra/docker/docker-compose.yml down -v` only when you
+intentionally want to delete FIP named volumes, such as local Postgres data.
+
 Some Compose services are still landing in follow-up issues. Until then,
 contributors can run the API and Workbench directly for focused development:
 
@@ -134,6 +138,10 @@ http://127.0.0.1:3000
 
 - `docs/DEMO_RUNBOOK.md` - current Docker/Demo-Factory runtime direction and
   transition notes.
+- `docs/runtime/DOCKER_COMPOSE.md` - detailed Docker Compose startup,
+  shutdown, rebuild, logs, health-check, and reset commands.
+- `docs/runtime/TROUBLESHOOTING.md` - Docker daemon, port, Postgres,
+  connector, API, and Workbench troubleshooting.
 - `docs/demo/OPERATIONS_WORKBENCH_DEMO_RUNBOOK.md` - Workbench runtime notes
   for the operator console.
 - `docs/demo/MANUFACTURER_DEMO_RUNBOOK.md` - manufacturer discussion framing.
@@ -149,6 +157,7 @@ http://127.0.0.1:3000
 Run these before opening a pull request:
 
 ```bash
+docker compose -f infra/docker/docker-compose.yml config
 make lint
 make typecheck
 make test

apps/web/README.md

@@ -46,6 +46,10 @@ NEXT_PUBLIC_API_BASE_URL=http://127.0.0.1:8001 npm run dev
 
 ## Runtime Direction
 
+Use `../../docs/runtime/DOCKER_COMPOSE.md` for the detailed local runtime guide
+and `../../docs/runtime/TROUBLESHOOTING.md` when Docker, API, or Workbench
+startup fails.
+
 Start Demo-Factory separately from its sibling checkout:
 
 ```bash
@@ -58,6 +62,10 @@ Start FIP from this repository:
 ```bash
 cd ../Factory-Intelligence-Platform
 docker compose -f infra/docker/docker-compose.yml up --build
+docker compose -f infra/docker/docker-compose.yml ps
+docker compose -f infra/docker/docker-compose.yml logs -f
+curl http://localhost:8000/health
+docker compose -f infra/docker/docker-compose.yml down
 ```
 
 For focused Workbench development before all Compose services land, run the API
@@ -88,6 +96,8 @@ electronic-signature, or compliance claim.
 
 ## Related Docs
 
+- `../../docs/runtime/DOCKER_COMPOSE.md`
+- `../../docs/runtime/TROUBLESHOOTING.md`
 - `../../docs/demo/OPERATIONS_WORKBENCH_DEMO_RUNBOOK.md`
 - `../../docs/demo/MANUFACTURER_DEMO_RUNBOOK.md`
 - `../../docs/demo/TROUBLESHOOTING.md`

docs/DEMO_RUNBOOK.md

@@ -5,6 +5,10 @@
 This runbook replaces the old in-repo generated-data demo path as the current
 runtime direction for the Factory Intelligence Platform.
 
+For detailed Docker Compose startup, shutdown, rebuild, logs, health-check,
+reset, expected URL, and troubleshooting commands, use
+`docs/runtime/DOCKER_COMPOSE.md` and `docs/runtime/TROUBLESHOOTING.md`.
+
 Demo-Factory is now the separate local source/simulation repository. FIP should
 consume external Demo-Factory protocol data through read-only connectors, then
 normalize readings into FactoryEvents for Process Sentinel, the API, and the
@@ -46,6 +50,10 @@ curl http://localhost:8000/health
 docker compose -f infra/docker/docker-compose.yml down
 ```
 
+Use `docker compose down` for normal shutdown. Use
+`docker compose -f infra/docker/docker-compose.yml down -v` only when you
+intentionally want to delete FIP named volumes such as local Postgres data.
+
 The Compose runtime is being built across the Dockerized runtime epic. Some
 services may be placeholders until the child issues for API/web images,
 connector worker, Postgres-backed runtime storage, Sentinel worker, and Compose

docs/DEVELOPMENT.md

@@ -58,6 +58,10 @@ git checkout -b feat/read-only-runtime-slice
 The current direction is a Docker Compose runtime that consumes external
 Demo-Factory protocol data through read-only connectors.
 
+Use `docs/runtime/DOCKER_COMPOSE.md` as the detailed runtime guide and
+`docs/runtime/TROUBLESHOOTING.md` for Docker daemon, port conflict, Postgres,
+connector, API, and Workbench failures.
+
 Start Demo-Factory separately from a sibling checkout:
 
 ```bash
@@ -76,6 +80,10 @@ curl http://localhost:8000/health
 docker compose -f infra/docker/docker-compose.yml down
 ```
 
+Use `docker compose down` for normal shutdown. Use
+`docker compose -f infra/docker/docker-compose.yml down -v` only when you
+intentionally want to delete FIP named volumes such as local Postgres data.
+
 Some Compose services are still landing through the Dockerized runtime epic. For
 focused API or Workbench development before the full composed stack is
 available, run:

docs/LEARNING_LOG.md

@@ -22,6 +22,67 @@ This file should be updated by Codex after each meaningful change.
 ### What to learn next
 ```
 
+## 2026-05-26 - Docker Compose runtime documentation
+
+### What changed
+
+Added `docs/runtime/DOCKER_COMPOSE.md` and
+`docs/runtime/TROUBLESHOOTING.md` as the detailed local runtime references for
+running FIP alongside the separate Demo-Factory source stack.
+
+### Why it matters
+
+Contributors now have one place for startup, shutdown, rebuild, logs,
+health-check, reset, expected URL, and troubleshooting commands while the
+Dockerized runtime epic lands service by service.
+
+### How it works
+
+The runtime docs keep the dependency order explicit: start Demo-Factory first,
+then start FIP. Demo-Factory provides local development source fixtures, while
+FIP consumes those sources through read-only connectors, normalizes readings
+into FactoryEvents, and exposes API and Workbench views over platform state.
+
+### How to run it
+
+```bash
+cd ../Demo-Factory
+docker compose up -d --build
+
+cd ../Factory-Intelligence-Platform
+docker compose -f infra/docker/docker-compose.yml up --build
+docker compose -f infra/docker/docker-compose.yml ps
+docker compose -f infra/docker/docker-compose.yml logs -f
+curl http://localhost:8000/health
+docker compose -f infra/docker/docker-compose.yml down
+```
+
+Use `docker compose -f infra/docker/docker-compose.yml down -v` only when
+intentionally deleting FIP named volumes such as local Postgres data.
+
+### How to test it
+
+```bash
+.venv/bin/python -m pytest services/simulator/tests/test_docker_compose_runtime_docs.py
+docker compose -f infra/docker/docker-compose.yml config
+make test
+make lint
+make typecheck
+cd apps/web && npm test
+```
+
+### Key files
+
+- `docs/runtime/DOCKER_COMPOSE.md`
+- `docs/runtime/TROUBLESHOOTING.md`
+- `services/simulator/tests/test_docker_compose_runtime_docs.py`
+
+### What to learn next
+
+Use these runtime docs as the command baseline while adding Postgres-backed
+storage, service images, connector workers, scheduled Sentinel execution, and
+Compose smoke tests in the remaining Dockerized runtime issues.
+
 ## 2026-05-26 - Runtime documentation direction cleanup
 
 ### What changed

docs/TESTING.md

@@ -86,6 +86,39 @@ state. It is retained for compatibility while the Compose smoke path is being
 introduced. Prefer the Docker/Demo-Factory runtime path for new documentation
 and issue work.
 
+## Docker Compose Runtime Checks
+
+Detailed runtime commands live in `docs/runtime/DOCKER_COMPOSE.md`, with
+troubleshooting in `docs/runtime/TROUBLESHOOTING.md`.
+
+Validate the FIP Compose file without starting containers:
+
+```bash
+docker compose -f infra/docker/docker-compose.yml config
+```
+
+Start Demo-Factory before FIP when validating the local runtime:
+
+```bash
+cd ../Demo-Factory
+docker compose up -d --build
+```
+
+Start, inspect, and stop FIP:
+
+```bash
+cd ../Factory-Intelligence-Platform
+docker compose -f infra/docker/docker-compose.yml up --build
+docker compose -f infra/docker/docker-compose.yml ps
+docker compose -f infra/docker/docker-compose.yml logs -f
+curl http://localhost:8000/health
+docker compose -f infra/docker/docker-compose.yml down
+```
+
+Use `docker compose down` for normal shutdown. Use
+`docker compose -f infra/docker/docker-compose.yml down -v` only when a test or
+manual reset intentionally deletes FIP named volumes.
+
 ## Backend Testing
 
 Current tools:

docs/runtime/DOCKER_COMPOSE.md

@@ -0,0 +1,164 @@
+# Docker Compose Runtime
+
+## Purpose
+
+This document is the current local runtime guide for running the Factory
+Intelligence Platform alongside the separate Demo-Factory source stack.
+
+Target runtime flow:
+
+```text
+Demo-Factory protocols
+-> FIP read-only connector worker
+-> FactoryEvent ingestion and storage
+-> Process Sentinel worker
+-> FastAPI API
+-> Next.js Workbench
+```
+
+The Dockerized runtime is being built across epic #232. Some FIP services may
+remain placeholders until the child issues for Postgres-backed storage, service
+images, connector worker, Sentinel worker, Workbench/API wording, and Compose
+smoke tests land. Keep using the commands below as the shared local runtime
+shape while those pieces are added.
+
+## Dependency Order
+
+Start Demo-Factory first. It is the local development source fixture for
+industrial-style protocol data. Demo-Factory validation is not production
+validation evidence and must not be used to claim validated GxP use,
+electronic signatures, compliance status, or production readiness.
+
+Then start FIP. FIP should consume Demo-Factory protocol data through read-only
+connectors, normalize readings into FactoryEvents, and expose API and
+Workbench views over platform state.
+
+## Start Demo-Factory
+
+From a sibling checkout:
+
+```bash
+cd ../Demo-Factory
+docker compose up -d --build
+```
+
+Useful Demo-Factory checks:
+
+```bash
+docker compose ps
+docker compose logs -f
+```
+
+## Start FIP
+
+From this repository:
+
+```bash
+cd ../Factory-Intelligence-Platform
+docker compose -f infra/docker/docker-compose.yml up --build
+```
+
+Use `--build` when Dockerfiles, dependency files, or Compose service
+configuration changed. If you only need to restart existing containers without
+rebuilding images, use:
+
+```bash
+docker compose -f infra/docker/docker-compose.yml up
+```
+
+## Inspect FIP
+
+List containers and their health:
+
+```bash
+docker compose -f infra/docker/docker-compose.yml ps
+```
+
+Follow logs for all FIP services:
+
+```bash
+docker compose -f infra/docker/docker-compose.yml logs -f
+```
+
+Follow one service when troubleshooting:
+
+```bash
+docker compose -f infra/docker/docker-compose.yml logs -f postgres
+```
+
+Check API health when the API container is available:
+
+```bash
+curl http://localhost:8000/health
+```
+
+Validate the Compose file without starting containers:
+
+```bash
+docker compose -f infra/docker/docker-compose.yml config
+```
+
+## Expected Local URLs
+
+| Surface | URL | Notes |
+| --- | --- | --- |
+| API health | `http://localhost:8000/health` | FastAPI health endpoint once the API service is in Compose. |
+| OpenAPI docs | `http://localhost:8000/docs` | FastAPI interactive API docs. |
+| Workbench | `http://localhost:3000` | Next.js Operations Workbench once the web service is in Compose. |
+| Workbench protocol diagnostics | `http://localhost:3000/protocol-diagnostics` | UI for read-only connection and mapping diagnostics. |
+| Connection profiles API | `http://localhost:8000/connection-profiles` | Read/list configured connection profiles. |
+| Connection test API | `POST http://localhost:8000/connection-profiles/{profile_id}/test` | Read-only diagnostic endpoint; must not write to protocol sources. |
+
+## Stop FIP
+
+Stop and remove FIP containers and networks while keeping named volumes:
+
+```bash
+docker compose -f infra/docker/docker-compose.yml down
+```
+
+Use this for normal shutdown. It keeps local Postgres data and other named
+volumes so the next startup can reuse state.
+
+## Reset FIP Volumes
+
+Reset FIP volumes only when intended:
+
+```bash
+docker compose -f infra/docker/docker-compose.yml down -v
+```
+
+Use `down -v` only when you intentionally want to delete named volumes, such as
+resetting local Postgres data or clearing a broken local runtime state. Do not
+use it when you need to preserve ingested events, connection profiles, or other
+state for debugging.
+
+## Rebuild After Dependency Changes
+
+When service dependencies or Dockerfiles change, rebuild FIP:
+
+```bash
+docker compose -f infra/docker/docker-compose.yml up --build
+```
+
+If a future issue adds multiple service images and only one service needs a
+rebuild, prefer rebuilding that service by name once it exists:
+
+```bash
+docker compose -f infra/docker/docker-compose.yml up --build api
+```
+
+## Safety Boundary
+
+The local runtime remains read-only toward external industrial-style sources.
+FIP must not perform industrial writeback, arbitrary tag writes, MQTT command
+publishing, BACnet writes, product disposition, QMS/MES integration, or
+production CAPA creation.
+
+Demo-Factory is a local development source fixture. It is useful for protocol
+integration and smoke testing, but it is not production validation evidence.
+
+## Troubleshooting
+
+Use `docs/runtime/TROUBLESHOOTING.md` for Docker daemon, port conflict,
+Postgres, connector, API, and Workbench failures.