The compose.yaml from the previous lesson uses seven keys. The Compose specification defines more than sixty, but you do not need to memorize them: most are the direct translation of a docker run option you already mastered in module 3.

This lesson is the practical reference for a service, organized by blocks and applied to Aurora Libros. By the end you will have the four services declared in a single file. How they interact with each other is lesson 04-04, and environment variables get a lesson of their own, 04-05.

1. Master table: service keys and their docker run equivalent
2. Image and build: image and build
3. Identity: container_name and hostname
4. Execution: command, entrypoint, user, init and shutdown
5. Network and ports: ports, expose, networks, aliases
6. Data: volumes, tmpfs, read_only
7. Health and dependencies: healthcheck and depends_on
8. Resources and restart: restart and deploy.resources
9. Labels: labels
10. Top-level blocks: volumes: and networks:
11. YAML anchors and references to avoid repeating yourself
12. Aurora Libros: the four services declared

The only row without an equivalent is depends_on, and that is no accident: the relationship between services is exactly what docker run cannot express.

image takes a reference just like docker run: repository and tag (postgres:16-alpine) or, better for production, an immutable digest (postgres@sha256:9f3d0e...).

build tells Compose to build the image instead of pulling it. In short form it is just the context (build: ./api); in long form, everything you learned in module 2:

When both keys appear together, build rules at build time and image gives the result its name. It is the most useful combination: docker compose build tags the image with that name and docker compose push publishes it.

With build alone, if you leave out image, Compose tags the image as <project>-<service>.

container_name pins the exact name and disables project prefixing. It sounds convenient, which is why plenty of people set it; it has three serious drawbacks: it makes docker compose up --scale impossible (two containers cannot share a name), it prevents bringing up two projects from the same file on the same machine, and you do not need it, because services talk to each other using the service name. Set it only when something external —a legacy script, a monitoring agent— demands a specific name.

command and entrypoint accept a string form (command: node server.js, which goes through the shell) and a list form (["node", "server.js"], direct execution). Prefer the list: it is the exec form and it guarantees your process is PID 1 and receives SIGTERM, exactly as you saw in lesson 03-02. init: true inserts a minimal init as PID 1 that forwards signals and reaps zombies, useful when your process spawns children and does not clean them up. And stop_grace_period accepts units (10s, 1m30s): for PostgreSQL, which needs to close a checkpoint before dying, push it up to 30 seconds.

ports publishes a container port on the host. Short form, "[IP:]hostPort:containerPort[/protocol]":

The long form is wordier but explicit: - {target: 80, published: "8080", protocol: tcp, mode: host}, where target is the internal port, published the host one, and mode: ingress only makes sense in Swarm.

expose publishes nothing: it documents which ports the container listens on. It is informational, because inside a user-defined network every port between containers is already reachable.

networks connects the service to the networks declared in the top-level block. Without this key, the service goes to the project's default network.

A service can be on several networks at once —which is exactly what aurora-api will do in lesson 04-04— and aliases gives it extra DNS names, handy for migrating without touching the clients' code.

The short form is the source:target[:options] syntax of docker run -v, and the source decides the mount type:

The rule is the module 3 one: if the source starts with . or / it is a bind mount; if not, it is a named volume that must be declared in the top-level volumes: block. The long form is the equivalent of --mount:

One important difference: with the short form, if a bind's source does not exist, Docker creates an empty directory; with the long form it fails with a clear error and saves you from the classic "I mounted a directory where I expected a file".

read_only: true plus a couple of tmpfs entries is one of the cheapest hardening measures there is; the full topic is lesson 05-03.

Compose's healthcheck replaces or complements the Dockerfile's HEALTHCHECK:

Three ways to write test:

start_period is the key almost nobody uses and almost everybody needs: PostgreSQL takes a few seconds to accept connections the first time, and without that grace period the container is marked unhealthy before it ever had a chance to start.

depends_on in its short form —depends_on: [aurora-db, aurora-cache]— only guarantees startup order: Compose launches the PostgreSQL container, waits until the process is running and immediately launches the API. But PostgreSQL takes another five seconds to accept connections, so the API starts up against a database that is not answering yet. The long form solves exactly that:

The distinction between "started" and "ready" is what separates a compose.yaml that works on your machine from one that always works. It is developed in lesson 04-04.

restart accepts the same four docker run values with the same meaning: no (the default), always, on-failure[:n] and unless-stopped. Limits, on the other hand, live under deploy, a block that was originally exclusive to Swarm:

There is a classic confusion here worth clearing up: outside Swarm, docker compose does apply deploy.resources.limits. What gets ignored are replicas, placement, update_config and rollback_config, because they make no sense on a single host. And remember from lesson 03-07 that limits is a hard ceiling —exceeding the memory one means OOM and exit code 137— whereas reservations is a soft guarantee that influences who gives up memory under pressure.

It also accepts a list form (- "key=value"). Use reverse DNS notation in the keys so you do not clash with other tools'. They are there for filtering (docker ps --filter "label=..."), and many tools in the ecosystem —automatic reverse proxies, metrics agents— are configured exclusively through labels.

Every named volume you use in a service must be declared at the top:

external: true is the ultimate protection for critical data: Compose assumes the volume exists and not even down -v touches it. If it does not exist, up fails instead of silently creating an empty one.

Networks follow the same pattern:

internal: true is the key that holds up the segmentation in lesson 04-04: containers on that network have no route to the outside, nor the outside to them. A database in there cannot download anything from the Internet even if somebody manages to run code inside it.

When four services share a restart policy, logging setup and labels, copying it four times is asking for them to drift apart. YAML offers anchors (&), references (*) and map merging (<<:), and Compose adds the x- extension keys, which it ignores when processing the file:

Two limits worth knowing: anchors only work within the same file (they do not cross several -f), and <<: merges at the first level, not deeply: if the anchor brings labels and the service also defines labels, the service's replaces the anchor's entirely, it does not blend them. Always check the result with docker compose config.

With everything above, here is the complete file. The credentials are still written by hand —that gets fixed in lesson 04-05— and there is a single network; segmentation arrives in 04-04.

Fifty lines of imperative bash have turned into a declarative, versionable, readable file, and along the way it has gained things the script never had: health probes on all four services, log rotation and consistent labels. Validate it and bring it up:

All four services healthy. That they started in the right order is luck, because there is not a single depends_on yet; that gets fixed in lesson 04-04.

Setting container_name out of habit. It breaks scaling and the coexistence of projects, and it adds nothing: services talk to each other using the service name.

Using a named volume without declaring it at the top. Compose fails with service refers to undefined volume. Bind mounts need no declaration; named volumes do.

Expecting a bare depends_on to wait until the service is ready. It only waits until it starts. Without condition: service_healthy you will still have startup races.

Defining a healthcheck without start_period. The service gets marked unhealthy during its normal startup and drags down everything that depends on it.

Writing test: curl -f http://localhost/health in an Alpine image. curl does not come installed in the official Alpine images; wget does. A healthcheck that invokes a nonexistent binary always fails, and the symptom —unhealthy with no further clues— is very misleading.

Tip: start every new service with image, restart and healthcheck, and add the rest only when you need it. A compose.yaml full of keys nobody can explain is just as bad as a bash script.

Exercise 1. Translate this command into a Compose service, without leaving out a single option, and explain where each one goes:

Exercise 2. The x-common block of the Aurora Libros file includes labels. Add to aurora-db a label of its own, com.auroralibros.component: "database", and check with docker compose config what happens to the inherited label. Explain the result and propose a fix.

Exercise 3. Declare a volume aurora-backups pointing at an external volume that already exists called aurora-backup-store, mount it read-only in aurora-db at /backups, and prove that docker compose down -v does not delete it.

Solution 1.

--name is deliberately dropped (the service name already identifies the container), --network becomes networks, the limits move down into deploy.resources.limits, --stop-timeout turns into stop_grace_period with units, and the arguments after the image become command in list form.

Solution 2. Adding labels: { com.auroralibros.component: "database" } to the aurora-db service:

The com.auroralibros.project label has vanished: <<: merges only at the first level, and since the service defines its own labels key, it replaces the inherited map entirely. The fix is a second anchor for the label contents:

Now config shows both. General rule: whenever you merge anchors, always verify with docker compose config; what you think is inherited and what actually is do not always match.

Solution 3. After docker volume create aurora-backup-store, add the mount to aurora-db and the external declaration:

down -v has deleted aurora-libros_aurora-data, which belonged to the project, but aurora-backup-store is still there: being external, Compose treats it as borrowed and does not manage it. That is the mechanism to use for any volume whose loss would be unacceptable.

You now have the complete reference for a Compose service, and above all the mental map that holds it together: nearly every key is a docker run option under another name, and only depends_on expresses something the imperative CLI could not say. You know when to use image and when build —and why often both together—, why container_name is almost always redundant, how command, entrypoint, user, init, stop_signal and stop_grace_period translate, and the two forms —short and long— of ports and volumes, with the nuance that the long one fails instead of creating an empty directory when the bind source does not exist.

You have a firm grip on the whole healthcheck block, including the start_period that keeps a service that is merely starting up from being marked as sick, and you know the difference between the three depends_on conditions: service_started, service_healthy and service_completed_successfully. You know restart has the same four values as always and that deploy.resources.limits does apply outside Swarm. You declare volumes and networks in the top-level blocks, you shield critical data with external: true, you isolate with internal: true, and you avoid repetition with x-/&/*/<<: anchors, knowing that the merge is shallow. And you have the compose.yaml with the four Aurora Libros services declared.

In the next lesson, Docker Compose Commands, you will move from the file to the CLI: the complete lifecycle (up and its reconciliation, down and the danger of -v, start, stop, restart, pause), observation (ps, logs, top, stats, events), the essential difference between exec and run, building and publishing, local scaling with --scale and why it clashes with fixed ports, and selecting files and projects with -f, -p and COMPOSE_FILE.