Mapping Host Ports: Connecting Your Docker Containers

Previously in this course, we learned about managing container states and how to control the lifecycle of a process. Up until now, our containers have been "black boxes"—running tasks, but unreachable from the outside world.

In this lesson, we break that isolation. We will learn how to perform port mapping, allowing you to route traffic from your host machine directly into a specific container.

Understanding Port Binding from First Principles

Every Docker container runs in its own network namespace. By default, this provides excellent security: a process inside the container can listen on port 80, but that port is invisible to your host machine (and the rest of the world).

Port mapping is the process of telling the Docker daemon: "Take requests sent to this specific port on my host and forward them to this specific port inside the container."

Think of the container as an office building. The container has its own internal room numbers (ports). To let visitors in, you need to provide a door on the building's exterior (the host port) that leads to a specific office inside. Without a mapping, the office remains inaccessible, regardless of whether the service is running.

Worked Example: Exposing a Web Server

To see this in action, we’ll use the nginx image, a popular lightweight web server. By default, Nginx listens on port 80 inside the container. We will map this to port 8080 on your host machine.

Run the following command in your terminal:

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

Breaking down the command:

• -d: Runs the container in "detached" mode (background).
• -p 8080:80: This is our port mapping. The format is host_port:container_port.
• --name web-server: Gives our container a friendly identifier.
• nginx: The image we are running.

Verifying Service Accessibility

Once the command executes, Docker creates a socket on your host's network interface at port 8080. You can verify this by opening your web browser and navigating to http://localhost:8080. You should see the default "Welcome to nginx!" page.

If you are curious about what’s happening under the hood, run:

Bash
docker ps

Look for the PORTS column. You will see 0.0.0.0:8080->80/tcp, confirming that the host is listening on 8080 and forwarding to 80.

Hands-on Exercise

It is time to practice mapping ports with a different service.

1. Stop and remove your existing web-server container (refer back to our lesson on removing containers if you need a refresher).
2. Launch a new container using the python:3.9-slim image.
3. Run a simple HTTP server inside that container that listens on port 9000.
4. Map your host port 9090 to the container port 9000.
5. Hint: Use docker run -p 9090:9000 -it python:3.9-slim python3 -m http.server 9000 to execute this in one go.
6. Navigate to http://localhost:9090 in your browser to confirm success.

Common Pitfalls

While docker run -p is straightforward, beginners often run into these three issues:

• Port Conflicts: If you try to map 8080:80 while another process (like a local Tomcat or Node.js server) is already using port 8080 on your host, the container will fail to start. You will see an EADDRINUSE error. Simply choose a different host port (e.g., -p 8081:80).
• Binding to Wrong Interfaces: By default, -p 8080:80 binds to all interfaces (0.0.0.0). If you are on a public network and only want to allow local connections, use -p 127.0.0.1:8080:80.
• Confusing Host vs. Container Ports: Remember the order: Host first, Container second. If you swap them, you’ll be trying to map the container's port to your host, which is not how the Docker daemon operates.

FAQ

Q: Can I map one host port to multiple container ports? A: No, a single host port can only be bound to one container port at a time. However, you can map multiple ports for a single container, like -p 80:80 -p 443:443.

Q: Do I need to stop the container to change the port mapping? A: Yes. Port mappings are defined at the moment of container creation. You must remove the container and run it again with the updated -p flags.

Q: How do I know which port the application inside the container is using? A: You usually need to consult the documentation for the image (e.g., Docker Hub). Some images also specify EXPOSE instructions in their Dockerfile, which act as documentation for which ports the application intends to use.

Recap

In this lesson, we moved beyond isolated containers. You learned that:

1. Port mapping uses the -p host:container syntax to bridge network namespaces.
2. The host port is the access point on your machine, while the container port is the internal service port.
3. We can verify our work using docker ps and by testing access via localhost.

Up next, we will explore Container Isolation, where we’ll pull back the curtain on how Docker uses Linux namespaces to keep your processes and files separated from your host system.