depends_on conditions, and keep retry logic in the app anyway.","html":"Every cold start of the notes-api stack had the same flaky first minute: the API started, tried Postgres, got ECONNREFUSED, and crashed. The depends_on: [db] in the file looked like it should have prevented it. It didn’t, because “started” and “ready” are different things, and Compose only knew about the first.
The short form says: start db before api.
services:\n api:\n depends_on:\n - dbCompose does exactly that: it starts the db container and then the api container, about a second apart. But Postgres needs several seconds after its process starts to initialise, more on the first run when it creates the database and runs your init scripts. The API connects during that window and is refused.
To wait for ready, Compose needs a way to test readiness. That’s a healthcheck.
\nA healthcheck is a command Docker runs inside the container on a schedule. Exit code 0 means healthy; anything else counts as a failure.
\n db:\n image: postgres:17\n environment:\n POSTGRES_USER: notes\n POSTGRES_PASSWORD: notes\n POSTGRES_DB: notes\n volumes:\n - pgdata:/var/lib/postgresql/data\n healthcheck:\n test: [\"CMD-SHELL\", \"pg_isready -U notes -d notes\"]\n interval: 10s\n timeout: 3s\n retries: 5\n start_period: 30s\n start_interval: 1spg_isready ships with the Postgres image and exits 0 once the server accepts connections. The timing fields:
interval: how often to run the check once the container is running normally.timeout: how long one check may take before it counts as failed.retries: consecutive failures before the container is marked unhealthy.start_period: a grace period after start during which failures don’t count toward retries.start_interval: how often to check during the start period, so a fast start is detected quickly instead of waiting a full interval.docker compose ps now shows (healthy) or (unhealthy) next to the status. When a check fails and you want to know why, the last few results, including their output, are stored on the container:
docker inspect notes-db-1 --format '{{json .State.Health}}'One thing healthchecks don’t do in plain Docker or Compose: they don’t restart an unhealthy container. The status is information, used by depends_on conditions and by you. Kubernetes is different, as you’ll see with liveness probes in section 5, where a failing check does trigger a restart. Knowing which tool acts on a failed check, and which only reports it, matters at 3 a.m.
The long form of depends_on lets you say what to wait for:
services:\n migrate:\n image: notes-api:dev\n command: [\"node\", \"dist/migrate.js\"]\n environment:\n DATABASE_URL: postgres://notes:notes@db:5432/notes\n depends_on:\n db:\n condition: service_healthy\n\n api:\n build: .\n image: notes-api:dev\n ports:\n - \"8080:3000\"\n environment:\n DATABASE_URL: postgres://notes:notes@db:5432/notes\n depends_on:\n db:\n condition: service_healthy\n restart: true\n migrate:\n condition: service_completed_successfullyThree conditions exist: service_started (the short form’s behaviour), service_healthy, and service_completed_successfully, which waits for a one-off container to exit with code 0. Here the migration runs once Postgres is healthy, and the API starts only after the migration succeeded. If the migration fails, api never starts, and you see why in docker compose logs migrate. restart: true means that if Compose restarts db (for example after you change its config), it restarts api too.
The API deserves a healthcheck too. The runtime image may be distroless with no curl, but it always has Node, and Node 24 has fetch built in. On node:24-slim, node is on the PATH; on distroless, call it by its full path, /nodejs/bin/node:
healthcheck:\n test: [\"CMD\", \"node\", \"-e\", \"fetch('http://localhost:3000/healthz').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))\"]\n interval: 10s\n timeout: 3s\n retries: 3In CI, docker compose up -d --wait returns only when every service with a healthcheck is healthy, and fails if one turns unhealthy. That’s the right way to start a stack before integration tests, instead of a sleep 15.
All of this covers the first start. Nothing stops Postgres from restarting at 3 p.m. on a Tuesday, and when you move to Kubernetes in section 4, there’s no depends_on at all: Pods start in whatever order they’re scheduled. So notes-api connects with a retry and backoff, and reports “not ready” on /readyz until the database answers. Healthchecks and conditions make the happy path fast; retries make the unhappy path survivable.
The stack now comes up in the right order every time. The last Compose lesson tidies up configuration and gives you a fast edit-and-reload loop.
\n","toc":[{"id":"sec-1","text":"What depends_on really waits for","level":2},{"id":"sec-2","text":"Healthchecks","level":2},{"id":"sec-3","text":"Waiting on conditions","level":2},{"id":"sec-4","text":"Retries still belong in the app","level":2}],"takeaways":["Short-formdepends_on only waits for the dependency’s container to start, not for it to be ready to serve.","A healthcheck tells Docker how to test a container; condition: service_healthy makes a dependent service wait for that test to pass.","condition: service_completed_successfully runs one-off jobs such as migrations before the app starts.","In exec form each argument is a separate list item; use CMD-SHELL when the test is a single shell command string.","Startup ordering covers only the first start, so the app must still retry database connections; Kubernetes has no depends_on at all."],"further":[{"title":"Control startup order in Compose","url":"https://docs.docker.com/compose/how-tos/startup-order/"},{"title":"Compose services reference (healthcheck)","url":"https://docs.docker.com/reference/compose-file/services/#healthcheck"},{"title":"docker compose up","url":"https://docs.docker.com/reference/cli/docker/compose/up/"}],"quiz":[{"q":"api has depends_on: [db] in short form. On a cold start the API logs ECONNREFUSED once, then works. Why?
db does start first. Starting isn’t the same as being ready."},{"text":"Short form waits for db’s container to start, not for Postgres to accept connections.","why":"Correct. Postgres needs a few seconds to initialise. Add a healthcheck and condition: service_healthy."},{"text":"The database password is wrong on the first attempt.","why":"A wrong password gives an authentication error, not a refused connection, and it wouldn’t fix itself."}],"answer":2},{"q":"Which healthcheck correctly tests Postgres readiness in the db service?
test: ["CMD-SHELL", "pg_isready -U notes -d notes"]","why":"Correct. CMD-SHELL runs the string with the container’s shell, and pg_isready exits 0 once the server accepts connections."},{"text":"test: ["CMD", "pg_isready -U notes -d notes"]","why":"Exec form treats the whole string as the program name, so Docker looks for a binary literally called pg_isready -U notes -d notes and the check always fails."},{"text":"test: ["CMD", "curl", "-f", "http://localhost:5432"]","why":"Postgres doesn’t speak HTTP, and the Postgres image doesn’t ship curl."},{"text":"test: ["CMD", "ping", "-c", "1", "db"]","why":"A ping proves the network works, not that Postgres is accepting queries."}],"answer":0},{"q":"A migrate service applies schema changes and exits. How should api depend on it?
condition: service_healthy","why":"A job that exits never becomes healthy, so api would wait for a state that never comes."},{"text":"condition: service_completed_successfully","why":"Correct. Compose waits for migrate to exit with code 0, and refuses to start api if it fails."},{"text":"condition: service_started","why":"That only waits for the migration to begin, so the API could start against a half-migrated schema."},{"text":"restart: always on migrate","why":"That restarts the job forever after it finishes; it doesn’t order anything."}],"answer":1},{"q":"Your stack uses healthchecks and service_healthy. Why should notes-api still retry failed database connections?
docker compose build.","why":"They run continuously while the container is up, at the configured interval."},{"text":"Retries are required for pg_isready to succeed.","why":"pg_isready runs inside the db container and has nothing to do with the API’s connection logic."},{"text":"Compose disables depends_on after the first minute.","why":"Nothing gets disabled. It’s simply a startup-time feature."},{"text":"The ordering only applies at startup; the database can restart later, and Kubernetes doesn’t order startup at all.","why":"Correct. A resilient app retries with backoff; startup ordering is a convenience on top, not a guarantee."}],"answer":3}],"exercise":{"kind":"spot-bug","language":"yaml","code":"services:\n api:\n build: .\n depends_on:\n - db\n environment:\n DATABASE_URL: postgres://notes:notes@db:5432/notes\n db:\n image: postgres:17\n environment:\n POSTGRES_USER: notes\n POSTGRES_PASSWORD: notes\n POSTGRES_DB: notes\n healthcheck:\n test: [\"CMD\", \"pg_isready -U notes -d notes\"]\n interval: 10s\n retries: 5","bugLines":[5,15],"title":"Healthy on paper","prompt":"With this compose.yaml, db shows (unhealthy) forever even though psql works fine, and the API still crashes on cold starts with ECONNREFUSED. Select the two lines to fix.
CMD), how many arguments does Docker see in that list?","Which form of depends_on only waits for the container to start?"],"explanation":"Line 15 uses exec form with one string, so Docker looks for a program literally named pg_isready -U notes -d notes and the check never passes. Use CMD-SHELL with the string, or split the arguments.
Line 5 uses the short form of depends_on, which only waits for db to start. Wait for the healthcheck instead:
api:\n depends_on:\n db:\n condition: service_healthy\n db:\n healthcheck:\n test: [\"CMD-SHELL\", \"pg_isready -U notes -d notes\"]