✦ For everyone, free.

Practical knowledge for real and everyday life

Home

4.2.10.5 EXPOSE Compose Docs

A focused guide to EXPOSE Compose Docs, connecting core concepts with practical Docker and container operations.

EXPOSE compose docs covers how EXPOSE declarations interact with, and are sometimes effectively duplicated by, port configuration in a docker-compose.yml file, and why it is still worth keeping the Dockerfile's own EXPOSE declarations accurate even when Compose handles the actual port publishing.

EXPOSE Still Documents the Image, Compose Handles Publishing

Even when a project uses docker compose to manage port publishing, the underlying image's own EXPOSE declarations remain useful documentation, independent of however the image happens to be run.

EXPOSE 8080

services:
  app:
    build: .
    ports:
      - "3000:8080"

The Compose file's ports section is what actually publishes the port; the Dockerfile's EXPOSE declaration documents it regardless of how the image is eventually deployed, including outside of Compose entirely.

Compose Can Reference EXPOSE Without Republishing

Within the same Compose-defined network, other services can reach a container's exposed port directly without it needing to be published to the host at all, relying on Compose's internal networking rather than the EXPOSE declaration itself, which remains purely informational.

services:
  app:
    build: .
    expose:
      - "8080"
  worker:
    build: ./worker

The expose key here in Compose mirrors the Dockerfile instruction's effect — documenting intent — while still relying on Compose's internal networking, not EXPOSE itself, for actual reachability between services.

Why Compose's Own Expose Key Exists Separately

Compose provides its own expose key partly for documentation consistency at the Compose file level and partly because a Compose file might define services in ways that don't directly map to a single Dockerfile's declarations, such as when using a pre-built image without its own visible Dockerfile.

services:
  cache:
    image: redis:7
    expose:
      - "6379"
Why Maintaining Both Matters

Keeping EXPOSE accurate in the Dockerfile and the corresponding ports or expose configuration accurate in Compose ensures consistent, non-conflicting documentation regardless of which file someone consults to understand a service's networking.

Related content