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

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