4.2.10.1 EXPOSE Port Docs

EXPOSE port docs is the role EXPOSE plays purely as documentation: communicating, directly within the Dockerfile itself, exactly which ports an application uses and ideally what purpose each one serves, available to anyone reading the file or inspecting the resulting image's metadata.

Reading Exposed Ports From an Image's Metadata

The ports declared through EXPOSE are stored as part of an image's configuration and can be retrieved without needing to read the original Dockerfile at all.

docker inspect myapp:1.0 --format '{{json .Config.ExposedPorts}}'

This reveals exactly what ports the image's author declared, useful for anyone who only has access to the built image, not its source.

Why Accurate Documentation Through EXPOSE Matters

Because EXPOSE carries no enforcement, its only value comes from being accurate — an outdated or incomplete set of EXPOSE declarations actively misleads anyone relying on it to configure networking or firewall rules correctly.

EXPOSE 8080

If the application was later changed to also expose a metrics endpoint on a different port, and the Dockerfile was never updated to reflect that, this documentation becomes incomplete and potentially misleading.

Verifying EXPOSE Matches Actual Behavior

Periodically confirming that an application's actual listening ports match what is declared through EXPOSE helps keep this documentation trustworthy over time.

docker run --rm myapp:1.0 ss -tlnp

Comparing the ports this reveals against the Dockerfile's EXPOSE declarations is a direct way to catch documentation that has drifted out of sync with reality.

Annotating Purpose Alongside Each Port

Adding a brief comment alongside each EXPOSE instruction clarifies what each port is actually for, information that the instruction alone does not convey.

EXPOSE 8080
# Internal-only health check endpoint
EXPOSE 8081

Why This Documentation Role Matters

Treating EXPOSE declarations as documentation worth actively maintaining, rather than a one-time formality, ensures this readily available metadata remains a trustworthy source of information for anyone configuring how a container is deployed and networked.