Ports, names, and detached mode

Long-running containers

hello-world quits instantly, but real workloads are servers that run forever. Start one properly:

docker run -d --name web nginx

• -d: detached mode. The container runs in the background and you get your prompt back. Without it, your terminal is glued to the container's output
• --name web: a human name for the container. Otherwise Docker invents one like jolly_wozniak, and every later command (docker logs web, docker stop web) is easier with a name you chose
• nginx: a tiny, extremely common web server image

The container is now serving a web page. But if you open http://localhost in a browser, you get nothing. Why?

Publishing ports

A port is a number from 0 to 65535 that the operating system uses to route incoming network traffic. Every server program claims a port when it starts, and the OS delivers each arriving connection to whichever program claimed the port it was addressed to. That rule is how one machine can run a web server, a database, and ssh at once without their traffic mixing. (A numbered door on a big building is a fine mental picture, but the mechanism is just that routing rule.)

nginx claims port 80, but that is port 80 inside the container's isolated network, which your browser cannot reach.

The -p flag fixes that by forwarding: traffic arriving at a chosen port on your machine is relayed to a port inside the container:

docker run -d --name web -p 8080:80 nginx

Read -p 8080:80 as host:container, left is your machine, right is inside. Traffic hitting localhost:8080 on your laptop is forwarded to port 80 in the container. Now http://localhost:8080 shows the nginx welcome page.

The order trips everyone up at first. Left side: the port outside traffic uses on your machine. Right side: the port the app inside is listening on.

Two containers, one image, one port conflict

Ports explain the first error every Docker user hits. Start two nginx containers:

docker run -d --name web1 -p 8080:80 nginx   # works
docker run -d --name web2 -p 8080:80 nginx   # fails

The second fails with bind: address already in use. The operating system allows exactly one program to claim a given host port, and host 8080 is already taken by the forwarding for web1. The fix is a different host port:

docker run -d --name web2 -p 8081:80 nginx   # works

Note what did not change: both containers still listen on 80 inside, because each container has its own isolated network. Container ports can repeat across containers. Host ports cannot.