# 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 |