How to Use Docker Port Mapping (with Docker Run & Docker Compose)

When you are running an application inside a Docker container, it is isolated from the host system and the outside world. By default, containerized applications cannot be accessed from the local machine or the external network unless you want to explicitly expose and map their ports. This is where the port mapping comes into play. 

Docker port mapping will connect a container’s internal port to another port on the host machine, which makes it possible for users, services, or other APIs to interact with the app. 

In this guide, we will explore how the Docker port mapping works, how to configure it using docker run and Docker Compose! 

Why Port Mapping is Needed in Docker

When an application is in the running state inside a Docker container, it uses the internal container ports to listen for requests. These ports are isolated and are not available to access directly from your host machine or external clients. 

Port mapping solves this exact problem by building a bridge between the two ports from the container and the host machine.  For example, mapping 8080:80 lets you access the Nginx container at http://localhost:8080, even though it’s running on port 80 inside the container.

Without the port mapping, the application would be locked out from the outside world. 

How Docker Port Mapping Works

Docker uses a network translation process to make the containers more accessible. 

1. Container Port – The port where the application inside the container is listening (e.g., 80 for a web server).
2. Host Port – The port on the host machine that forwards traffic to the container port (e.g., 8080).
3. Port Mapping Syntax – Defined as:
   hostPort:containerPort

Example:

docker run -p 8080:80 nginx

In this example, the container’s port 80 is being connected to the host’s 8080. So it shows that visiting the http://localhost:8080 on your browser will reach the Nginx server running inside the container.

Docker Run Command: Mapping Ports

Using the docker run command, you can start and control the container using the internal posts that are exposed to your host machine with different flags. The two of the most common flags are -p flag and the –publish-all (-P) flag.

Using -p Flag

The -p (or –publish) flag is mainly used to publish or map content from a specific container port to a host port. 

The -p (or –publish) flag maps a specific container port to a specific host port.

Syntax:

docker run -p <hostPort>:<containerPort> <image>

Example:

docker run -d -p 8080:80 nginx

• Maps host port 8080 → container port 80.
• You can now access Nginx at http://localhost:8080.

You can also map multiple ports:

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

Using –publish-all Flag (-P)

The –publish-all flag on the contrary would map all the exposed container ports to random host posts that are available at that time. 

Example:

docker run -d -P nginx

• Docker will assign a random high numbered port on the host for the container’s exposed port 80. 
• You can check the end mapping with docker ps
• Output would show the host port numbers. 

To summarise, you should: 

• Use the -p flag when you want full control over the ports that are mapped. 
• Use the -P when you’re fine with random mapping. 

Viewing and Inspecting Container Ports

After you are initializing the port mapping, you should confirm which host ports are connected to which container ports. With Docker, you can do so using these commands: 

1. Using docker ps

This command shows the list of running containers and their port mappings. 

Example:

docker ps

2. Using docker port

To check a specific ports mapping using: 

docker port <container_id_or_name>

Example:

docker port nginx-container

3. Using docker inspect

For more information, you can run:

docker inspect <container_id_or_name>

Inside the JSON output, look for the NetworkSettings → Ports section.

Example snippet:

“Ports”: {

  “80/tcp”: [

    {

      “HostIp”: “0.0.0.0”,

      “HostPort”: “8080”

    }

  ]

}

This shows container port 80 is mapped to host port 8080.

Docker Compose Port Mapping

When you are working with multi-container applications, Docker Compose is your best bet to define the port mappings in the docker-compose.yml file. The ports key is used to connect ports to the host ports. 

Syntax in docker-compose.yml

ports:

  – “hostPort:containerPort”

• hostPort → The port on your host machine.
• containerPort → The port inside the container where the service is running.

You can also set the container port and Docker will assign the host port itself. 

So, what are some examples of Docker Port Mapping?

1. Basic port mapping:

version: ‘3.8’

services:

  web:

    image: nginx

    ports:

      – “8080:80”

This maps host port 8080 to container port 80, making Nginx available at http://localhost:8080.

2. Multiple port mappings:

version: ‘3.8’

services:

  web:

    image: nginx

    ports:

      – “8080:80”

      – “443:443”

Here, both HTTP (80) and HTTPS (443) ports are mapped.

3. Random host port assignment:

version: ‘3.8’

services:

  app:

    image: myapp

    ports:

      – “80”

In this case, Docker assigns a random host port for container port 80. Run docker-compose ps to check the actual port mapping.

4. Mapping to a specific interface:

version: ‘3.8’

services:

  db:

    image: mysql

    ports:

      – “127.0.0.1:3306:3306”

This would map the MySQL’s ports 3306 but only the localhost, which makes it accessible from only the host machine. 

Best Practices for Port Mapping in Docker

To avoid any unnecessary issues and security threats, follow these best practices for Docker port mapping. 

• Use host ports that are not applicable by default, for example container port 80 to host instead of 8080. 
• Restrict the access to ports that are absolutely necessary. 
• Avoid random host port allocation. 
• Verify the host ports that are not already in use before mapping them. 
• Verify the host ports that are not already in use before mapping onto them. 
• Use Docker Compose for uniformity and consistency. 
• Do not expose services like databases to the internet unless absolutely crucial. 
• Use docker ps or docker-compose ps to confirm the mappings and troubleshoot. 

Common Errors in Port Mapping and How to Fix Them

Error	Cause	Solution
Bind for 0.0.0.0:8080 failed: port is already allocated	Host port already in use.	Stop the process using that port or map to a different host port (e.g., -p 8081:80).
Container running but app not accessible	Port not published to host.	Add -p hostPort:containerPort in docker run or ports in Compose.
Access denied from external network	Ports only bound to localhost.	Use 0.0.0.0:hostPort:containerPort if external access is required.
Confusion between hostPort and containerPort	Wrong order of values in mapping.	Ensure the format is hostPort:containerPort.
Random high port assigned	Used -P or just container port in Compose.	Use explicit -p or define hostPort:containerPort in Compose.

Conclusion – Docker Port Mapping 

Docker port mapping is an important concept that allows containerized applications usable for the outside world. Using port mapping, you can run web servers, databases, or APIs easily on your local machine and production environment.

FAQs