Repair a Docker Compose Application
A three-service Compose stack (web + api + postgres) comes up, but the web app shows “database connection failed.” Several independent problems are planted: a wrong DB hostname, an incorrect env var, a missing shared network, and a readiness race. Fix them all.
Learning objectives
- Bring the stack up
- Diagnose why web can’t reach the database
- Fix hostname, env, network, and readiness issues
- Validate the app returns healthy
Before you start
Required software: Docker Engine 24+ with Compose v2
Prerequisites: Docker Compose path (or Fundamentals)
- Download and unzip the lab.
- Start it:
docker compose up -d. - Load the app URL from the README — it will report a DB error.
Instructions
Full instructions are part of Individual Pro
Unlock the step-by-step instructions, the solution guide, validation scripts, and downloadable files.
Hints
💡 “could not translate host name”
In Compose, services reach each other by service name on a shared network. Check that the app’s DB host matches the postgres service name AND that both are on the same network.
💡 It connects sometimes, fails on cold start
That’s a readiness race: the DB isn’t accepting connections yet when the app starts. depends_on alone doesn’t wait for readiness — add a healthcheck + condition: service_healthy.
Validate your work
From the lab folder, run:
bash validation/validate.shThe script reads only your local Docker state, never transmits data off your machine, and returns a status code:
0— Lab successfully completed1— Validation failed2— Required dependency missing3— Lab environment not running4— Configuration error5— Validation timed out
Note: validation targets Linux first. On Docker Desktop (macOS/Windows) some host-level checks (e.g. disk usage) may report differently; each script documents its limitations.
Solution
The full solution + troubleshooting explanation is available to Individual Pro members. Try to solve it first — that’s where the learning is.
Reset the lab
docker compose down -v && docker compose up -dfrom the original lab files restores the starting (broken) state.
Interview questions
- Why doesn’t `depends_on` guarantee the database is ready?
- How do containers resolve each other by name in Compose?
- What are two ways to make a service wait for a dependency to be healthy?
Finished this lab?
Sign in to record your completion and track progress across the path. Completion is recorded server-side.