Episode 6: The Invisible City (Port Mapping)

Jack finally did it. He followed the "Secret Scroll," built the room, and moved his app inside. He can see the app running on the terminal screen inside the room. He’s proud.

Rose is standing outside in the hallway (your laptop's OS) with her phone out, trying to access the app's website. "Jack, it’s not working," she shouts. "The building exists, the room is running, but I can't see the site!"

Jack realizes the problem: He built a room with no doors and no windows. The app is alive, but it’s trapped in an Invisible City.

The Tech: Network Isolation & The Portal

By default, Docker is obsessed with security. When a container starts, it gets its own private IP address and its own set of "ports" (think of these as specific mail slots for data).

• The Container Port: The mail slot inside the room (e.g., Port 80 for a web server).

• The Host Port: The mail slot on your laptop (the "Apartment Building" exterior).

If you don't explicitly connect them, they stay isolated. Your browser on the laptop has no idea how to find Port 80 inside that specific container. To fix this, we use Port Mapping— which is essentially drilling a hole through the wall to create a Portal.

How the Portal Works (-p)

When we run the container, we use a special flag: -p. I used to get the order of these numbers mixed up all the time. The secret is to remember: Host : Container (Outside : Inside).

docker run -p 8080:80 my-fastapi-app

• 8080 (The Outside Door): This is what you type into your browser (localhost:8080).

• 80 (The Inside Door): This is where the app is actually listening inside the container.

Docker acts like a bridge. When a request hits your laptop at 8080, Docker grabs it and throws it through the portal into the container's Port 80.

Why I used to fail at this (The 0.0.0.0 Trap)

In Episode 3, we added a weird command to our start-up: --host 0.0.0.0.

I used to think 127.0.0.1 (localhost) was enough. But here’s the technical catch: inside a container, localhost means "only look inside this room." By setting it to 0.0.0.0, you are telling the app: "Listen to any traffic coming through the walls from the outside world."

Without 0.0.0.0 inside and -p outside, your app remains an island.

The Quest: Bridge the Gap

Your Mission: It’s time to actually see your FastAPI app live in your browser.

1. The Run: Open your terminal and run your image from Episode 5, but add the portal flag. docker run -p 8000:80 my-hero-app (Note: If your FastAPI is set to port 80 inside the Dockerfile, use 80. If it's 8000, use 8000:8000).

2. The Test: Open Chrome or Firefox and go to http://localhost:8000.

3. The Verification: If you see your "Hello World" or your FastAPI docs, the portal is open.

The Challenge: Open a second terminal window while the app is running and type docker ps. Look at the column labeled PORTS.

• What does it show? You should see something like 0.0.0.0:8000->80/tcp.

• The Question: If you stop this container and try to run a second one on the same port 8000, what happens? (Spoiler: The "Apartment Building" doesn't like two rooms sharing the same mailbox!)