[AZ-1123] Document docker-compose.perf.yml port playbook

Co-authored-by: Cursor <cursoragent@cursor.com>

_docs/02_document/deployment/containerization.md

@@ -14,7 +14,36 @@
 | postgres | postgres:16 | 5433:5432 | Database (host port 5433 chosen to avoid conflicts with sibling-project Postgres instances on dev laptops) |
 | api | Custom (Dockerfile) | 18980:8080, 18981:8081 | Application |
 
-## Volumes
+## Compose overlays (dev / test / perf)
+
+The default `docker-compose.yml` publishes Postgres on host port **5433** so tools on the host can reach the DB. On multi-repo dev laptops another local Postgres container may already bind 5433, producing `address already in use` when starting the stack.
+
+| Use case | Compose files | Postgres host port |
+|----------|---------------|-------------------|
+| Default local dev | `docker-compose.yml` | 5433:5432 |
+| Integration tests (Step 11) | `docker-compose.tests.yml` only | **None** — internal compose network only |
+| Perf tests / dev API without host DB (Step 15) | `docker-compose.yml` + `docker-compose.perf.yml` | **None** — overlay clears the publish |
+
+### Perf overlay (`docker-compose.perf.yml`)
+
+Unsets the postgres port mapping so only the API port (18980) is published to the host. Postgres remains reachable as `postgres:5432` inside the compose network (same as integration tests).
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.perf.yml up -d --build
+```
+
+File contents:
+
+```yaml
+services:
+  postgres:
+    ports: !reset []
+```
+
+Use this when Step 15 (`scripts/run-performance-tests.sh`) or manual perf probing against `https://localhost:18980` must run while another project owns host port 5433.
+
+Integration tests do **not** use this overlay — `scripts/run-tests.sh` starts `docker-compose.tests.yml` alone, which never publishes postgres to the host.
+
 
 | Mount | Container Path | Purpose |
 |-------|---------------|---------|

_docs/02_document/tests/environment.md

@@ -8,6 +8,7 @@
 | Database | PostgreSQL 16 (Docker container) | Fresh DB per test run (migrations auto-applied) |
 | Test Runner | Custom console app (SatelliteProvider.IntegrationTests) | Docker container on same network |
 | Orchestration | docker-compose.tests.yml | Waits for API health before starting tests |
+| Perf orchestration | docker-compose.yml + docker-compose.perf.yml | See [containerization.md](../deployment/containerization.md) — host port 5433 conflict playbook |
 
 ## Network Topology
 
@@ -45,6 +46,8 @@
 **Hardware dependencies found**: None
 **Execution method**: `docker-compose -f docker-compose.yml -f docker-compose.tests.yml up --build --abort-on-container-exit`
 
+**Performance tests** (Step 15 / `scripts/run-performance-tests.sh`): start the API with the perf overlay when host port 5433 is occupied — `docker compose -f docker-compose.yml -f docker-compose.perf.yml up -d --build`. Details: [containerization.md](../deployment/containerization.md#compose-overlays-dev--test--perf).
+
 | Property | Value |
 |----------|-------|
 | Execution mode | Sequential (one test at a time) |

_docs/02_tasks/_dependencies_table.md

@@ -261,6 +261,7 @@ Step 9 cycle 8: 5 tasks queued (AZ-812 = 3 pts Region DTO rename, AZ-808 = 3 pts
 Step 9 cycle 8b: folded into cycle 8 as step 1 (AZ-812). Section retained in dependency table for traceability.
 Step 9 cycle 9: 2 tasks created (AZ-1074 = 5 pts, AZ-1075 = 3 pts) — total 8 pts. gRPC TileStream for route-based progressive tile delivery.
 Step 9 cycle 10: 1 task created (AZ-1113 = 2 pts) — REST 400 error message sanitization (F-AZ795-1/2, F-AZ810-1). Child of AZ-795.
+Step 9 cycle 11: 1 task created (AZ-1123 = 1 pt) — document `docker-compose.perf.yml` host-port conflict playbook (cycle 10 retro action).
 
 ## Coverage Verification
 

_docs/02_tasks/done/AZ-1123_perf_compose_docs.md

@@ -0,0 +1,69 @@
+# Document docker-compose.perf.yml host-port playbook
+
+**Task**: AZ-1123_perf_compose_docs
+**Name**: Document docker-compose.perf.yml host-port conflict playbook
+**Description**: Document when and how to use the perf compose overlay so Step 11/15 gates do not fail on host port 5433 conflicts.
+**Complexity**: 1 points
+**Dependencies**: None (builds on `docker-compose.perf.yml` added cycle 10)
+**Component**: deployment docs, test environment docs
+**Tracker**: AZ-1123 (https://denyspopov.atlassian.net/browse/AZ-1123)
+**Epic**: None
+
+## Problem
+
+Cycle 9–10 autodev integration and performance gates failed with `5433: address already in use` when a sibling Postgres container occupied the host port. Operators fixed it ad hoc with `docker-compose.perf.yml`, but deployment docs still describe only the default compose file.
+
+## Outcome
+
+- Operators and agents can find the host-port conflict playbook without reading cycle metrics or deploy reports.
+- Perf harness startup command is documented next to integration-test orchestration.
+
+## Scope
+
+### Included
+- `_docs/02_document/deployment/containerization.md` — compose overlays section (default dev, integration-only, perf overlay)
+- `_docs/02_document/tests/environment.md` — cross-link and perf execution compose command
+
+### Excluded
+- Changing `docker-compose.yml` or `docker-compose.perf.yml` behavior
+- CI/Woodpecker pipeline changes
+- README changes (unless required for AC)
+
+## Acceptance Criteria
+
+**AC-1: Containerization playbook**
+Given `containerization.md` is the deployment reference
+When an operator reads the compose overlays section
+Then it explains the 5433 conflict symptom, when to use `docker-compose.perf.yml`, and the exact `docker compose -f docker-compose.yml -f docker-compose.perf.yml up` command
+
+**AC-2: Test environment cross-link**
+Given `environment.md` describes test orchestration
+When an operator runs performance tests locally
+Then the doc names the perf compose overlay and points to `containerization.md` for details
+
+**AC-3: Integration vs perf distinction**
+Given both integration and perf harnesses exist
+When the docs are read
+Then integration tests are documented as using self-contained `docker-compose.tests.yml` (no host postgres port) separately from the perf overlay pattern
+
+## Unit Tests
+
+| AC Ref | What to Test | Required Outcome |
+|--------|-------------|-----------------|
+| — | Documentation-only task | N/A |
+
+## Blackbox Tests
+
+| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
+|--------|------------------------|-------------|-------------------|----------------|
+| — | — | — | — | — |
+
+## Constraints
+
+- Documentation only — no production behavior change
+
+## Risks & Mitigation
+
+| Risk | Mitigation |
+|------|------------|
+| Docs drift from compose files | Quote actual file names and commands from repo |

_docs/03_implementation/batch_01_cycle11_report.md

@@ -0,0 +1,16 @@
+# Batch Report
+
+**Batch**: 1
+**Tasks**: AZ-1123
+**Date**: 2026-06-25
+**Cycle**: 11
+
+## Task Results
+
+| Task | Status | Files Modified | Tests | AC Coverage | Issues |
+|------|--------|---------------|-------|-------------|--------|
+| AZ-1123 perf compose docs | Done | containerization.md, environment.md | N/A (docs only) | 3/3 | None |
+
+## Code Review Verdict: PASS (documentation-only)
+
+## Next Batch: All tasks complete

_docs/03_implementation/implementation_report_perf_compose_docs_cycle11.md

@@ -0,0 +1,20 @@
+# Implementation Report — Perf Compose Documentation (Cycle 11)
+
+**Cycle**: 11
+**Tasks**: AZ-1123 (1 SP)
+**Feature slug**: perf_compose_docs
+
+## Summary
+
+Documented `docker-compose.perf.yml` host-port conflict playbook in deployment and test environment docs. No code or compose behavior changes.
+
+## Deliverables
+
+| Artifact | Change |
+|----------|--------|
+| `deployment/containerization.md` | Compose overlays table + perf overlay command |
+| `tests/environment.md` | Perf orchestration row + cross-link |
+
+## Verification
+
+Documentation-only — AC verified by review against `docker-compose.perf.yml` and `docker-compose.tests.yml` on disk.

_docs/_autodev_state.md

@@ -2,13 +2,13 @@
 
 ## Current Step
 flow: existing-code
-step: 9
+step: 11
-name: New Task
+name: Run Tests
 status: in_progress
 sub_step:
   phase: 1
-  name: gather-description
+  name: test-run
-  detail: "awaiting cycle 11 task choice"
+  detail: "doc-only cycle 11 — sanity gate"
 retry_count: 0
 cycle: 11
 tracker: jira
@@ -19,4 +19,3 @@ cycle: 10
 step_16_deploy: completed
 step_16_5_release: skipped (no release harness)
 step_17_retrospective: completed
-verdict: cycle_complete_operator_deploy