Docker Compose Ports

Docker Compose Ports: A Complete Guide to Mapping Container Networking

If you’ve spent any time writing YAML for containerized applications, you’ve almost certainly run into the ports key. Getting docker compose ports configuration right is one of the most common early stumbling blocks for developers moving from docker run to a multi-service docker-compose.yml file, and small mistakes here can silently break connectivity between your host machine, your containers, and the outside world. This guide walks through exactly how port mapping works in Compose, the syntax variations you’ll encounter, and the troubleshooting steps that resolve the vast majority of real-world issues.

What Docker Compose Ports Actually Do

At its core, the ports directive in a Compose file tells Docker to forward traffic from a port on your host machine to a port inside a specific container. Without this mapping, a service running inside a container is only reachable from other containers on the same Docker network — not from your host’s browser, curl, or any external client.

Docker Compose ports work through Docker’s internal networking layer, which uses iptables rules (on Linux) or a userland proxy to route packets. When you define a mapping like 8080:80, Docker creates a rule that says “anything arriving on host port 8080 gets forwarded to port 80 inside this container.” This is distinct from container-to-container communication, which happens automatically over the Compose-created network using service names as hostnames — no port publishing required for that internal traffic.

Host Port vs Container Port

The mapping format is always HOST:CONTAINER. This trips up a surprising number of engineers, especially those coming from Kubernetes or other orchestrators where the convention can differ. If your application listens on port 3000 inside the container but you want to access it via localhost:3000 on your machine, you write:

services:
  web:
    image: node:20-alpine
    ports:
      - "3000:3000"

If you wanted to expose that same internal port 3000 as port 8080 on your host, you’d write "8080:3000" instead. The left side is always what you type into your browser or curl command; the right side is always what your application code is actually bound to.

Docker Compose Ports Syntax: Short vs Long Form

Compose supports two syntaxes for defining ports, and knowing when to use each one matters as your stack grows more complex.

Short Syntax

The short syntax is a simple string or list of strings in HOST:CONTAINER format, optionally including a protocol:

ports:
  - "8080:80"
  - "8443:443"
  - "53:53/udp"

This is the form most tutorials use because it’s compact and readable. For the majority of docker compose ports use cases — a web app, an API, a database exposed for local development — the short syntax is all you need.

Long Syntax

The long syntax, introduced to give more explicit control, uses a mapping structure per port:

ports:
  - target: 80
    published: 8080
    protocol: tcp
    mode: host

This form is useful when you need to be explicit about mode (host vs ingress, relevant in Swarm deployments) or when generating Compose files programmatically, since each field is unambiguous. For local development and most single-host deployments, the short syntax remains the more common and more maintainable choice.

Binding to a Specific Host Interface

By default, Compose binds published ports to all network interfaces (0.0.0.0), which means the service is reachable from any network your host is connected to — including, potentially, the public internet if your firewall isn’t configured carefully. You can restrict this by specifying an IP address:

ports:
  - "127.0.0.1:5432:5432"

This binds the mapping only to localhost, which is a good default for databases and internal tooling you never want reachable from outside the machine.

Common Docker Compose Ports Patterns

A few patterns come up repeatedly across real projects, and it’s worth knowing them before you hit the problem they solve.

Random host port allocation — omit the host port entirely (- "80") and Docker will pick an available ephemeral port, which you can then look up with docker compose port <service> 80. Useful for CI environments running many parallel instances.

Multiple ports on one service — list as many mappings as needed; there’s no practical limit for a typical application.

Range mappings — "5000-5010:5000-5010" maps a contiguous range, handy for services that need several adjacent ports (some legacy protocols, or apps with a hardcoded port-search range).

UDP alongside TCP — if a service needs both, list them separately, since each mapping is protocol-specific: "53:53/tcp" and "53:53/udp".

Reusing the same container port across services — this is fine as long as the host ports differ; container ports are isolated per-container by design.

A database setup is a good concrete example of these patterns in action. If you’re standing up Postgres locally, the Postgres Docker Compose setup guide walks through binding the database port to localhost only, which avoids accidentally exposing your database to your local network. The same pattern applies to any PostgreSQL Docker Compose deployment where you want local access without external exposure.

Docker Compose Ports vs Expose

A frequent source of confusion is the difference between ports and expose. Both appear in Compose files, and both relate to networking, but they do very different things.

expose documents that a container listens on a given port, and makes that port reachable to other containers on the same Docker network — but it does not publish anything to the host. ports, by contrast, does both: it enables container-to-container communication (since Docker Compose ports on the same network can already reach each other by service name regardless of expose or ports) and it publishes the port to the host machine.

When to Use Expose Instead of Ports

If a service — say, an internal API or a Redis cache — only needs to be reached by other services in the same stack, you generally don’t need ports at all. Compose automatically allows any container on the same network to reach any other container’s listening ports using the service name as the hostname, whether or not you declare expose. The expose key is largely documentation at that point; it doesn’t grant access that wasn’t already there, but it does communicate intent clearly to anyone reading the file.

This distinction matters for security posture: every port you publish with ports is a port reachable from outside the container boundary, subject to your host firewall rules. Every port you leave unpublished stays inside the isolated Docker network, invisible to anything outside it. The Redis Docker Compose guide is a good reference for a service that, in most stacks, should never need a published port at all — only other containers in the same Compose project need to reach it.

Ports in Multi-Container Stacks

In a typical multi-service stack — a web frontend, an API backend, and a database — best practice is to publish only the frontend’s port to the host. The API and database communicate with each other and with the frontend over the internal Docker network, using service names, with no ports entries required for either. This keeps your attack surface minimal: only the one entry point your users actually need to reach is exposed at all.

Troubleshooting Docker Compose Port Conflicts

The most common error you’ll encounter is some variation of “port is already allocated” or “address already in use.” This happens when the host port you’ve specified is already bound by another process — another Compose project, a locally running dev server, or a leftover container from a previous run.

docker compose up
# Error response from daemon: driver failed programming external connectivity
# on endpoint web: Bind for 0.0.0.0:8080 failed: port is already allocated

Finding What’s Using a Port

On Linux or macOS, you can identify the culprit with:

lsof -i :8080

Or, if you suspect it’s a stale Docker container rather than a host process:

docker ps --filter "publish=8080"

If it’s an old container from a previous Compose run that never shut down cleanly, stopping the stack properly resolves it — the Docker Compose Down guide covers the difference between down and stop, and why down is usually what you want when you’re trying to fully release ports and networks between runs.

Changing the Host Port Without Touching Application Code

The simplest fix, when you don’t control what else is running on your machine, is just to change the host side of the mapping in your Compose file — the container-internal port never needs to change:

ports:
  - "8081:80"   # host changed, container stays on 80

If you’re actively debugging a stack and want to see exactly what’s happening on the network layer as containers start and stop, the Docker Compose Logs guide is useful alongside port troubleshooting, since connection refusals often show up in application logs before the port-binding error even surfaces.

Security Considerations for Docker Compose Ports

Every published port is a potential entry point, so it’s worth treating ports as a security-relevant configuration, not just a connectivity convenience.

Bind development-only services (databases, admin panels, debug endpoints) to 127.0.0.1 rather than 0.0.0.0.

Avoid publishing ports you don’t actually need externally — prefer expose or no declaration at all for internal-only services.

Combine port mappings with proper secrets management so that even a service you do expose isn’t leaking credentials — see the Docker Compose Secrets guide for handling this correctly rather than passing credentials through plain environment variables.

If you’re deploying to a VPS and need a reverse proxy in front of multiple Compose stacks, only the proxy itself typically needs a published port (80/443); everything behind it can stay on the internal network.

Review firewall rules on the host separately from Docker’s own port publishing — Docker manages iptables directly on Linux by default, which can bypass certain firewall tools (like UFW) unless explicitly configured to cooperate with them.

For official, authoritative detail on how Docker’s networking and port publishing model works under the hood, the Docker networking documentation and the Compose file reference are the primary sources worth bookmarking.

FAQ

Does Docker Compose ports work the same way as docker run -p?
Yes — the ports key in a Compose file is functionally equivalent to the -p flag in docker run. Compose simply lets you declare these mappings declaratively across multiple services in one file instead of typing flags for each container individually.

Can two services in the same Compose file publish the same host port?
No. Each host port can only be bound once at a time. Two services can use the same container port without conflict, but their host ports must be unique, or Compose will fail to start the second service.

Why can I reach my container from another container but not from my browser?
This almost always means the port is declared with expose but not ports, or the ports entry is missing entirely. Container-to-container traffic on the same Docker network doesn’t require a published port, but host-to-container traffic does.

Do I need to publish a port if I’m putting a reverse proxy in front of my app?
Generally no, for the backend services themselves. Only the reverse proxy container needs a published port (typically 80/443); it reaches the backend services over the internal Compose network using their service names.

Conclusion

Docker Compose ports are simple in concept — map a host port to a container port — but the details around syntax, interface binding, expose vs ports, and security posture are where real-world configurations go wrong. Get in the habit of asking, for every service, whether it actually needs to be reachable from outside the Docker network at all. If it doesn’t, leave it unpublished. If it does, bind it as narrowly as possible and keep the mapping explicit in your Compose file so the next person reading it understands exactly what’s exposed and why.