Port Mapping (-p flag)

Imagine you run a business from home. You have a home phone line, but you want customers to call your work line.

Solution: Call forwarding.

When someone calls your work number, the phone company forwards the call to your home line.

Port mapping is call forwarding for network traffic.

When someone connects to your host on port 8080, Docker forwards that connection to the container’s port 80.

From the outside, it looks like the host is running a web server on port 8080. But actually, the host is just forwarding traffic to the container.

When you run:

docker run -d -p 8080:80 nginx

Here’s what Docker does:

Step 1: Container listens on port 80

Inside its network namespace, nginx binds to port 80.

Step 2: Host sets up iptables rule

Docker adds an iptables rule on the host:

“If traffic arrives on port 8080, forward it to 172.17.0.2:80” (assuming the container’s IP is 172.17.0.2).

Step 3: Traffic flows

When a client connects to host-ip:8080:

1. Packet arrives at host on port 8080
2. iptables rule matches and rewrites the destination to 172.17.0.2:80
3. Packet is forwarded through the bridge to the container
4. Container receives it on port 80
5. Container responds
6. Response goes back through the bridge to the host
7. Host forwards it to the client

From the client’s perspective, they connected to the host. They have no idea a container is involved.

Basic mapping:

docker run -p 8080:80 nginx

• 8080 = host port
• 80 = container port

Access at http://localhost:8080

Map to a specific host interface:

docker run -p 127.0.0.1:8080:80 nginx

Only accessible from localhost, not from external IPs.

Let Docker choose a random host port:

docker run -p 80 nginx

Docker picks an available port on the host (like 32768) and maps it to the container’s port 80.

Find the assigned port:

docker ps

Or:

docker port <container-name> 80

Map multiple ports:

docker run -p 8080:80 -p 8443:443 nginx

Maps host port 8080 → container port 80, and host port 8443 → container port 443.

Map UDP ports:

docker run -p 5353:53/udp my-dns-server

By default, -p maps TCP. Add /udp for UDP.

See mapped ports:

docker ps

Look at the PORTS column:

PORTS
0.0.0.0:8080->80/tcp

This means: host port 8080 (on all interfaces: 0.0.0.0) maps to container port 80.

See iptables rules:

sudo iptables -t nat -L -n

Look for rules in the DOCKER chain. You’ll see NAT rules that forward traffic to container IPs.

Test from outside:

curl http://localhost:8080

You should get nginx’s welcome page.

What if port 8080 is already in use?

docker run -p 8080:80 nginx
# Error: Bind for 0.0.0.0:8080 failed: port is already allocated

Docker checks if the host port is available. If not, the container fails to start.

Solution: Use a different host port, or stop the process using port 8080.

---