Port mapping with -p flag in Docker - Commands & Configuration

Introduction

A container runs in its own isolated network and its ports are not accessible from your computer by default. The -p flag maps a port on your host machine to a port inside the container so you can reach the app running inside it.

When you run a web server in a container and want to open it in your browser on your computer.

When you run a database container and want your app on the host to connect to it.

When you need to expose multiple services from the same container on different host ports.

When you want to test a containerized API from tools like Postman or curl on your machine.

When you run multiple containers with the same internal port and need to map each to a different host port.

Commands

Runs an nginx container in detached mode and maps port 8080 on the host to port 80 inside the container. Opening http://localhost:8080 in your browser will show the nginx welcome page.

Terminal

docker run -d -p 8080:80 nginx

Expected Output

a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890

→

-p 8080:80 - Maps host port 8080 to container port 80 (format: host:container)

→

-d - Runs the container in the background

Lists running containers to confirm the port mapping is active and the container is healthy.

Terminal

docker ps

Expected Output

CONTAINER ID   IMAGE   COMMAND                  CREATED         STATUS         PORTS                  NAMES

a1b2c3d4e5f6   nginx   "/docker-entrypoint.…"   5 seconds ago   Up 4 seconds   0.0.0.0:8080->80/tcp   relaxed_morse

Shows all port mappings for the container, confirming which host ports are forwarded to which container ports.

Terminal

docker port relaxed_morse

Expected Output

80/tcp -> 0.0.0.0:8080

Key Concept

If you remember nothing else from this pattern, remember: the -p flag format is always host_port:container_port — left side is your machine, right side is inside the container.

Common Mistakes

Reversing the port order to container:host instead of host:container

Docker maps the wrong direction — the container port becomes the host port, causing connection failures.

Always write -p host_port:container_port, e.g. -p 8080:80 to reach container port 80 via host port 8080.

Using a host port already in use by another process

Docker fails to start the container with a 'port is already allocated' error.

Choose a free host port or run 'lsof -i :PORT' to check if a port is in use before mapping.

Forgetting to publish ports and wondering why the container is unreachable

Without -p, the container port is only accessible inside the Docker network, not from the host.

Always add -p host:container when you need to access a containerized service from outside.

Summary

Use -p host_port:container_port to expose a container service to your host machine.

The PORTS column in 'docker ps' shows 0.0.0.0:8080->80/tcp confirming the mapping is active.

Use 'docker port container_name' to inspect all active port mappings for a running container.