48-Hour Field Notes: The Port the Repo Never Opened

Description and use

Implemented a runtime contract and checker to ensure generated Docker and compose files match the repository’s actual port and host configuration, preventing silent deployment failures.

Problem

Generated Docker and compose files introduced a port mismatch that caused runtime failures while tests passed, leading to a silent deployment bug.

Outcome

The checker prevented a silent deployment bug by enforcing consistency between generated ops files and the repository’s actual runtime configuration.

Workflow

• 1. Identify port mismatch between generated Dockerfile/compose and application defaults.
• 2. Create a runtime contract JSON specifying expected http_bind_port, host, probe_url, forbidden_ports, and postgres_transport details.
• 3. Write a Python script that scans Dockerfiles, compose files, and scripts for port declarations using regex.
• 4. Compare found ports against the contract; flag any mismatches or forbidden ports.
• 5. Run the checker before CI builds to fail the build if inconsistencies are detected.
• 6. Adjust generated files or contract as needed to resolve mismatches.
• 7. Re-run CI to confirm build passes and runtime matches contract.

Evidence

I stopped asking for a better patch and wrote a file the patch had to lose against. The contract is boring on purpose.

Source

Hour 18 I wired a checker that walks generated compose files, Dockerfiles, and shell probes, then fails if a literal host, port, or scheme disagrees with the contract.

Source