EXPOSE vs -p / --publish

Words used on this page

port

A number that, together with an IP address, identifies one listening program on a machine.

EXPOSE

A Dockerfile instruction that records in the image's configuration which ports the application is expected to listen on. It opens and forwards nothing. docker run --expose does the same at run time.

publish (-p, --publish)

A docker run option that creates a forwarding rule from a port on the host to a port in the container. It is set when the container is created.

host port and container port

In -p 8080:3000, 8080 is the port on the host that you connect to and 3000 is the port the application listens on inside the container.

-P, --publish-all

Publishes every exposed port to a random high port on the host. This is how EXPOSE can change what a docker run does.

bind address

The IP address a program listens on. 0.0.0.0 means every IPv4 address the machine has; 127.0.0.1 means the machine itself only.

loopback (127.0.0.1, localhost)

The address a machine uses to talk to itself. Inside a container it is the container's own loopback, separate from the host's.

NAT

Network address translation: rewriting a packet's address on the way through. Docker's firewall rules use it to send traffic for a host port to the container's own address and port.

userland proxy (docker-proxy)

A small Docker process that listens on the published host port and relays connections to the container. It runs alongside the firewall rules and is on by default.

ephemeral port

A high port number handed out on request. -P, and -p with only a container port, use one for the host side.

One exposed port and one published port, side by side

Quoted from the publish and expose filter example in Docker's docker container ls reference, not reproduced: Docker is not installed on the machine this page was checked on, and the reference does not say which Docker version produced the output. It also leaves out the container ID that each docker run -d prints. --expose is the run-time equivalent of a Dockerfile EXPOSE line. Both containers run top, which serves nothing, so the output shows what Docker set up, not whether anything would answer.

Command

docker run -d --publish=80 busybox top
docker run -d --expose=8080 busybox top
docker ps -a
docker ps --filter publish=80

Output · as shown in Docker docs: docker container ls (publish and expose filters)

$ docker run -d --publish=80 busybox top
$ docker run -d --expose=8080 busybox top

$ docker ps -a

CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS                   NAMES
9833437217a5        busybox             "top"               5 seconds ago       Up 4 seconds        8080/tcp                dreamy_mccarthy
fc7e477723b7        busybox             "top"               50 seconds ago      Up 50 seconds       0.0.0.0:32768->80/tcp   admiring_roentgen

$ docker ps --filter publish=80

CONTAINER ID        IMAGE               COMMAND             CREATED              STATUS              PORTS                   NAMES
fc7e477723b7        busybox             "top"               About a minute ago   Up About a minute   0.0.0.0:32768->80/tcp   admiring_roentgen

How to read it

• 8080/tcp with no arrow is the container that was only exposed. Docker recorded the port and forwards nothing to it. An image's EXPOSE line on its own gives you exactly this.
• 0.0.0.0:32768->80/tcp is the published container. Read it right to left: container port 80 is reachable through host port 32768 on every IPv4 address of the host. --publish=80 named only the container port, so Docker picked an ephemeral host port.
• 0.0.0.0 includes the host's public addresses. A current Engine publishes to 0.0.0.0 and [::] by default, and since 27.0.1 gives both the same ephemeral port, so the PORTS column can list a second, bracketed [::] entry for the same mapping.
• The publish=80 filter matched only the published container. To check one container, docker port <container> lists its mappings in the form 80/tcp -> 0.0.0.0:32768, and prints nothing for ports that were only exposed.
• To prove a request gets through, you need a real server listening on 0.0.0.0 inside the container and a request from the host, such as curl http://localhost:<host port>.