Practice brief

Container Networking Fundamentals Exercises

The TaskFlow API has been running alone since Module 5. In Module 8 you add a Postgres database container and connect the two using a Docker network. This is the first time TaskFlow has multiple services, and it is the foundation for the Compose setup in Module 11.

Build from scratch

8.1 Build from scratch

~25-35 min

Connect the API to a Database Container

The TaskFlow API currently runs without a database — it keeps tasks in memory, which means all data disappears when the container stops. In this exercise you will start a Postgres container, create a Docker network for the two services to communicate on, and pass the database connection URL to the API as an environment variable. After this, the API and the database can reach each other by container name. No IP addresses. No host port forwarding between containers.

Done when

A taskflow-net network exists
A postgres container named taskflow-db is running on taskflow-net
The taskflow-api container is running on taskflow-net with DATABASE_URL set
The API can reach the database by container name

Try it yourself first. Open the guided path if you get blocked.

Step 1 — Create a custom Docker network

docker network create taskflow-net

docker network create makes a new bridge network. Bridge is the default type — containers on the same bridge network can reach each other by container name. You are naming this network taskflow-net so it is easy to identify as belonging to this project. Run docker network ls to confirm it appears in the list.

Step 2 — Start the Postgres container on the network

docker run -d --name taskflow-db --network taskflow-net -e POSTGRES_PASSWORD=secret -e POSTGRES_DB=taskflow postgres:16-alpine

This starts Postgres 16 on the Alpine variant, which is smaller than the full Debian image. --network taskflow-net puts it on the network you just created. --name taskflow-db gives it a name that other containers can use as a hostname. The two -e flags set the database password and create the taskflow database. Postgres will not start without a password set.

Step 3 — Remove the existing API container

docker rm -f taskflow-api

The existing taskflow-api container is on the default bridge network, not taskflow-net. Docker does not let you move a running container to a different network without re-creating it. Remove it first, then start it fresh on the correct network in the next step.

Step 4 — Start the API container on the same network

docker run -d --name taskflow-api --network taskflow-net -p 8000:8000 -e DATABASE_URL=postgres://postgres:secret@taskflow-db:5432/taskflow taskflow-api

--network taskflow-net puts the API on the same network as the database. -e DATABASE_URL passes the connection string. Notice the hostname in the URL is taskflow-db — the container name of the Postgres container. Docker's built-in DNS resolves container names to their IP addresses on a custom network. This is why --name matters: it becomes the hostname. No port forwarding between containers is needed.

Step 5 — Verify the containers can see each other

docker exec taskflow-api ping -c 2 taskflow-db

ping sends two packets from the API container to the database container using the name taskflow-db. If you see replies, Docker DNS resolved the name and the network is working. If ping is not installed in the image, use nc -zv taskflow-db 5432 instead — that checks whether the Postgres port is reachable.

Step 6 — Check that the API is still responding

curl http://localhost:8000/health

Even with a database now in the picture, the health endpoint should still respond. If it does not, run docker logs taskflow-api to see what happened. The most common issue at this stage is a typo in the DATABASE_URL — check that the password and database name match the -e flags you used when starting taskflow-db.

Break-fix

8.2 Break-fix

~15-25 min

The Containers That Cannot Find Each Other

A teammate set up the TaskFlow API and Postgres containers, but the API keeps crashing with a connection error — it cannot reach taskflow-db. They started both containers with docker run, both are showing as Up in docker ps, and the DATABASE_URL looks correct. But the API cannot find the database by name. Reproduce this failure, figure out why containers on the default network cannot find each other by name, and fix it.

Reproduce this

docker rm -f taskflow-api taskflow-db
docker run -d --name taskflow-db -e POSTGRES_PASSWORD=secret -e POSTGRES_DB=taskflow postgres:16-alpine
docker run -d --name taskflow-api -p 8000:8000 -e DATABASE_URL=postgres://postgres:secret@taskflow-db:5432/taskflow taskflow-api
docker logs taskflow-api

You're done when

You can explain why containers on the default bridge network cannot resolve each other by name
After your fix, docker exec taskflow-api ping -c 2 taskflow-db succeeds

Show investigative hints

Both containers are running and healthy on their own. The problem is only about communication. Run docker inspect taskflow-api and docker inspect taskflow-db and look at the Networks section — what network is each container on?
The default bridge network does not support DNS resolution by container name. That is a feature of custom networks you create with docker network create.
The fix is to put both containers on the same custom network. You will need to remove and re-create them with --network pointing to the same network name.

Show diagnosis and fix rationale

Containers on Docker's default bridge network do not get automatic DNS by container name. The API can use the hostname taskflow-db only when both containers are attached to the same user-defined network. Create a custom network, remove the broken containers, and re-create both containers with --network set to that network.