docker compose, and connect services by name over Compose’s default network.","html":"notes-api needs Postgres. You could start both with two docker run commands, a hand-made network and a page of flags, and then explain it all again to the next person who joins the team. Compose replaces that with one file in the repository that describes the whole stack, and one command that makes it real.
Create compose.yaml next to the Dockerfile:
name: notes\n\nservices:\n api:\n build: .\n image: notes-api:dev\n ports:\n - \"8080:3000\"\n environment:\n PORT: \"3000\"\n DATABASE_URL: postgres://notes:notes@db:5432/notes\n\n db:\n image: postgres:17\n environment:\n POSTGRES_USER: notes\n POSTGRES_PASSWORD: notes\n POSTGRES_DB: notesTwo services. api is built from the Dockerfile in this directory and tagged notes-api:dev; db uses the official Postgres 17 image, whose entrypoint creates the user and database from those three variables on first start. name: notes sets the project name, which prefixes everything Compose creates.
When a service has both build: and image:, Compose builds from the Dockerfile and tags the result with the image: name. That gives the local image a predictable name you can also run by hand, instead of the default name Compose would generate from the project and service names.
There’s no version: line. Compose v2 implements the Compose Specification, and if you copy an old file that starts with version: "3.8", Compose ignores it and warns that the attribute is obsolete. Delete it.
The command is docker compose, with a space. That’s Compose v2, a Docker CLI plugin. The old Python docker-compose with a hyphen has been retired for years, and tutorials that use it are out of date in other ways too.
docker compose up -d --build\ndocker compose ps\ndocker compose logs -f api\ncurl localhost:8080/readyzup builds the image if needed, creates a network, starts both containers and returns. --build forces a rebuild so code changes are picked up. /readyz now answers ready, because the API can reach the database.
docker compose ps shows the containers Compose created, named after the project, the service and a number: notes-api-1 and notes-db-1. The number exists because a service can run several identical containers. Every command takes service names, not container names, so you rarely type the full name.
A few more you’ll use daily:
\ndocker compose exec db psql -U notes -d notes # SQL shell in the db container\ndocker compose restart api # restart one service\ndocker compose down # stop and remove containers and networkup is declarative: it compares the file to what’s running and changes only the difference. Edit the API’s environment and run up -d again, and Compose recreates api while db keeps running. Kubernetes works on the same idea at a much larger scale; you’ll meet it in section 4.
Compose creates a network for the project, notes_default, and attaches every service to it. On that network, Docker’s DNS resolves each service name to its container. That’s why DATABASE_URL says @db:5432.
Notice that db has no ports: entry. The API reaches it over the project network; nothing on your laptop or your office network can. If you want to point a desktop SQL client at it, publish it on loopback only: "127.0.0.1:5432:5432".
For bigger stacks you can declare networks and attach each service only where it belongs. A database on a backend network can’t be reached by a web front end that only joins frontend:
services:\n web:\n networks: [frontend]\n api:\n networks: [frontend, backend]\n db:\n networks: [backend]\n\nnetworks:\n frontend:\n backend:For notes-api, the default network is enough. Reach for this when a stack has components that should never talk to each other.
\nCompose is excellent for three jobs: local development, integration tests in CI (start the stack, run the tests, tear it down), and small services that live on a single host. What it doesn’t do is spread containers across machines, move them when a machine dies, or roll out a new version gradually while watching health checks. Those are an orchestrator’s jobs, and they’re what Kubernetes does in section 4. The habits you build here carry straight over: declare the desired state in a file, let a tool make it so, and connect services by name.
\nOne problem remains. Run docker compose down, then up again, and every note is gone: Postgres stored its data in the container’s writable layer, which down deleted. The next lesson gives the database somewhere permanent to live.
compose.yaml declares services, networks and volumes; docker compose up creates whatever is missing and leaves the rest alone.","Compose v2 is the docker compose plugin; the top-level version: key is obsolete and should be removed.","Every service joins the project’s default network and is reachable by its service name, so the API connects to db:5432, not localhost.","Publish only the ports you need from the host; a database that only the API talks to needs no ports: entry at all."],"further":[{"title":"How Compose works","url":"https://docs.docker.com/compose/intro/compose-application-model/"},{"title":"Networking in Compose","url":"https://docs.docker.com/compose/how-tos/networking/"},{"title":"Compose file reference","url":"https://docs.docker.com/reference/compose-file/"}],"quiz":[{"q":"Inside the api container, which DATABASE_URL host reaches the Postgres service named db?
db, the service name, which Compose’s network DNS resolves to the database container.","why":"Correct. Services on the same Compose network find each other by service name."},{"text":"localhost, because both containers run on the same machine.","why":"Each container has its own network namespace. localhost inside api is the API container itself, where nothing listens on 5432."},{"text":"host.docker.internal, which always points at other containers.","why":"That name points at your host machine. It only works if the database port is published there, and it couples the app to your laptop."},{"text":"The database container’s IP address from docker inspect.","why":"It works until the container is recreated and gets a new IP. Names are stable; IPs aren’t."}],"answer":0},{"q":"You add version: "3.8" at the top of compose.yaml. What does current Docker Compose do with it?
version is obsolete.","why":"Correct. Delete the line; it does nothing."},{"text":"Downloads the matching Compose release.","why":"Compose never fetches itself based on the file. Your installed docker compose plugin is what runs."}],"answer":2},{"q":"Postgres in your Compose stack is only used by api. Which ports: setting should db have?
"5432:5432", so the API can reach it.","why":"The API reaches it over the Compose network without any published port. Publishing exposes it on every host interface."},{"text":""0.0.0.0:5432:5432", to be explicit about listening everywhere.","why":"That’s the same as the default and puts your database on the office Wi-Fi with a development password."},{"text":""5432", which publishes it on a random host port.","why":"Still reachable from the host network, just on a less obvious port."},{"text":"None at all; add "127.0.0.1:5432:5432" only if you need a local GUI client.","why":"Correct. Container-to-container traffic doesn’t need published ports, and loopback-only publishing keeps it off the network."}],"answer":3},{"q":"You change only the api service’s environment in compose.yaml and run docker compose up -d. What happens to the running db container?
db didn’t change, so it isn’t touched."},{"text":"It keeps running untouched; Compose only recreates services whose configuration changed.","why":"Correct. up reconciles each service against the file and leaves unchanged ones alone."},{"text":"It’s stopped and needs a separate docker compose start db.","why":"up doesn’t stop services that are already in the desired state."},{"text":"It’s paused while api restarts, then resumed.","why":"Compose doesn’t pause dependencies during a recreate."}],"answer":1}],"exercise":{"kind":"spot-bug","language":"yaml","code":"services:\n api:\n build: .\n ports:\n - \"8080:3000\"\n environment:\n DATABASE_URL: postgres://notes:notes@localhost:5432/notes\n db:\n image: postgres:17\n ports:\n - \"5432:5432\"\n environment:\n POSTGRES_USER: notes\n POSTGRES_PASSWORD: notes\n POSTGRES_DB: notes","bugLines":[7,11],"title":"Two Compose bugs, one connection","prompt":"With this compose.yaml, the API logs ECONNREFUSED 127.0.0.1:5432, and a colleague on the office Wi-Fi just connected to your database with the password notes. Select the two lines responsible.
api container, what does localhost refer to?","Does the API need a published port to reach the database over the Compose network?"],"explanation":"Line 7 points the API at localhost, which inside its container is the API itself. Use the service name: postgres://notes:notes@db:5432/notes.
Line 11 publishes Postgres on every host interface, so anyone on your network can reach it. The API doesn’t need it; containers talk over the project network. Remove the ports: block, or bind to loopback if you need a local SQL client:
ports:\n - \"127.0.0.1:5432:5432\"