feature: Ward Gateway Service (Local-First Clinical Path)

docs/docker-compose-usage-and-troubleshooting.md

@@ -14,6 +14,8 @@ From repo root:
 docker compose up -d
 ```
 
+Ward gateway services (`ward-gateway-db`, `ward-gateway-redis`, `ward-gateway-rabbitmq`, `ward-gateway-api`) use Compose profiles and **do not** start with the command above. Use `--profile ward-gateway` or see §10.
+
 Check status:
 
 ```bash
@@ -177,6 +179,7 @@ This repo uses named volumes for persistent data:
 - `minio_data`
 - `prometheus_data`
 - `grafana_data`
+- `ward_pg_data` (ward gateway PostgreSQL — only created when ward profile is used)
 
 ### Why your data still exists after restart
 - `docker compose up -d --force-recreate` recreates containers, but volumes remain.
@@ -316,3 +319,63 @@ Note: if you accidentally create a typo folder like `dashbpards`, Grafana provis
 
 This avoids unnecessary full resets and speeds up local development.
 
+---
+
+## 10) Compose profiles (ward gateway stack)
+
+Several services in `docker-compose.yml` declare a **profile** so they are optional:
+
+```yaml
+profiles: ["ward-gateway", "full"]
+```
+
+Affected services: `ward-gateway-db`, `ward-gateway-redis`, `ward-gateway-rabbitmq`, `ward-gateway-api`.
+
+### Why ward services do not start with `docker compose up`
+
+`docker compose up` (no `--profile`) only starts services **without** a profile. The central stack (`postgres`, `redis`, `kafka`, etc.) has no profile and starts normally. Ward services are gated behind `ward-gateway` or `full`.
+
+Symptom: `docker compose ps` shows no `ward-gateway-*` containers after a plain `docker compose up -d`.
+
+### How to start the ward stack
+
+```bash
+# Ward gateway infrastructure + API (port 5081)
+docker compose --profile ward-gateway up -d
+
+# Central + ward together
+docker compose --profile full up -d
+```
+
+Persist the profile in your environment so you do not need the flag every time:
+
+```bash
+export COMPOSE_PROFILES=ward-gateway
+# or add to a repo-root .env file: COMPOSE_PROFILES=ward-gateway
+```
+
+### Ward service ports (host)
+
+| Service | Host port | Purpose |
+|---|---|---|
+| `ward-gateway-db` | 5437 | PostgreSQL `vigilcare_ward` |
+| `ward-gateway-redis` | 6383 | Threshold cache |
+| `ward-gateway-rabbitmq` | 5675 / 15675 | Local paging (AMQP / management UI) |
+| `ward-gateway-api` | 5081 | Gateway HTTP API |
+
+Connection strings in `VigilCare.WardGateway/appsettings.json` use these host ports when running `dotnet run` locally against Dockerized dependencies.
+
+### Verification
+
+```bash
+docker compose --profile ward-gateway ps
+curl -sS -o /dev/null -w "%{http_code}\n" http://localhost:5081/health/ready
+```
+
+Phase 21 verification script already uses the correct profile:
+
+```bash
+./scripts/run-phase21-verification.sh
+# internally: docker compose --profile ward-gateway up -d
+```
+