You finished module 3 with a fifty-line bash script that brings Aurora Libros up. It works, but it describes how to reach the desired state: create the network, create the volume, start the database, wait in a loop, start the cache, the API and the web front end, each one with its fourteen lines of options.

Docker Compose turns that around. Instead of a sequence of orders, you write a file that states what the desired state is —four services, one network, one volume— and let Compose work out the steps. The file is called compose.yaml, it lives in the repository next to the code, it gets reviewed in a pull request, and it comes up with a single command.

In this lesson you will see exactly what problem Compose solves (and which one it does not), the bare minimum of YAML you need so the syntax never fights you, how Compose uses the concept of a project as a namespace, and you will write your first compose.yaml with two of the four Aurora Libros services.

1. From fifty imperative lines to forty declarative ones
2. Imperative versus declarative
3. What Docker Compose is and what it is not
4. Compose v2: a plugin of the Docker CLI
5. The minimum YAML you need
6. YAML syntax errors you are guaranteed to hit
7. Anatomy of a compose.yaml
8. The project as a namespace
9. Your first compose.yaml: database and cache
10. up, ps, logs, down: the full cycle

Take two fragments of the module 3 script, the database one and the cache one:

And now the same information in compose.yaml:

There is no docker network create: Compose creates a network for the project automatically. There is no docker volume create: declaring the volume is enough. There is no --name: the service name already identifies the container. And there is no execution order, because the file is not a sequence, it is a description.

The key word is reconciliation. When you run docker compose up -d a second time, Compose does not create anything again: it compares the configuration of each running container with the one the file declares and only recreates what has changed. If you edit the cache's memory and run up -d, the cache is recreated and the other three services never notice.

Compose is a tool for defining and running multi-container applications on a single Docker host. Its natural ground:

• Any team's development environment: git clone and docker compose up -d.
• Integration tests in CI, where you need a real, throwaway database.
• Reproducible demos and test environments.
• Small deployments on a single server, when high availability is not a requirement.

Compose is not a multi-node production orchestrator. It does not know how to spread containers across ten machines, it does not reschedule a service when the server hosting it dies, it does not do progressive deployments with automatic rollback, nor load balancing between replicas on different machines. All of that arrives in module 6 with Swarm and Kubernetes.

The good news is that the compose.yaml you write here is not throwaway work: the concepts —service, image, variables, volumes, health probes— are the same ones you will meet in Kubernetes with a different syntax.

Compose started life as a standalone program written in Python that you invoked with docker-compose (with a hyphen) and that read a docker-compose.yml file. That is the old syntax. Since Compose v2, rewritten in Go, it is a plugin of the Docker CLI and you invoke it as a subcommand: docker compose, no hyphen. The preferred file name today is compose.yaml, and the old version: "3.8" key on the first line is obsolete: if you write it, Compose ignores it and warns you. Forget it exists.

Check your installation:

If that command fails but docker-compose version works, you have v1: install the plugin (docker-compose-plugin in the Docker repositories) before going any further. Docker Desktop ships with it.

Compose looks for the file in the current directory and upwards, in this order of preference:

Always use compose.yaml. The others exist for compatibility.

YAML is a data serialization format designed to be read by people. You only need five ideas.

Indentation with spaces, never tabs. Hierarchy is expressed through indentation. Two spaces per level is the universal convention. A tab is a syntax error in YAML, no exceptions.

Maps (key-value pairs), separated by a colon and a space:

Lists, with a hyphen and a space. Every item at the same indentation level:

Nesting: maps inside maps and lists inside maps. That is how a whole compose.yaml is built: services is a map whose keys are service names, and the value of each one is another map with image, ports, and so on.

Scalars and quotes. YAML guesses the type: 5432 is an integer, true a boolean, 1.2 a float, postgres:16-alpine a string. You can use single or double quotes; double quotes interpret escape sequences (\n), single ones do not. The practical rule in Compose:

Comments: everything after # to the end of the line. Use them freely; a well-commented compose.yaml is living documentation.

For long strings, YAML offers two block styles: | keeps the line breaks and > turns them into spaces. You will see them in command and in healthcheck.

That last command is your safety net: docker compose config reads the file, validates it, resolves variables and hands you back the final configuration exactly as Compose understands it. Run it whenever something does not add up.

A Compose file has four commonly used top-level sections:

Only services is mandatory. The others exist because a volume or a network does not belong to a service: they are shared resources that several services use, and that is why they are declared separately and referenced from inside each service.

Every line of the file becomes real Docker objects you already know everything about: containers, bridge networks and volumes. Compose invents nothing new underneath; it talks to the same daemon and the same API you were using with docker run. You can still inspect it all with docker ps, docker network inspect or docker volume ls.

Compose groups everything it creates under a project. The default project name is that of the directory containing the file, in lowercase and with odd characters stripped. If your file is in ~/aurora-libros/, the project is called aurora-libros.

That name is used as a prefix:

On top of that, Compose labels every object with com.docker.compose.project=<project> and com.docker.compose.service=<service>. That is how it knows, on a machine with twenty containers, which ones are its own.

Prefixing has one very useful practical consequence: two different projects can use the same compose.yaml without stepping on each other. Three ways to set the project name, from highest to lowest priority:

Setting name: in the file is good practice: it guarantees the project is called the same thing even if somebody clones the repository into a folder with a different name.

You are going to start small: just aurora-db and aurora-cache. The API and the web front end arrive in lesson 04-04, once you know how to declare dependencies and health probes.

You have deleted the module 3 containers so there are no name or port clashes. The aurora-data volume is still intact, but Compose will create its own prefixed one, so you will start with a clean database populated by db/init.sql.

Create ~/aurora-libros/compose.yaml:

Three details worth your attention:

• ./db/init.sql: relative paths are resolved from the file's directory, not from your cwd. That is why the $HOME of the bash script disappears and the file becomes portable.
• There is no networks:: Compose creates aurora-libros_default and connects both services there, with internal DNS —exactly like the user-defined aurora-net network you created by hand in lesson 03-05.
• There is no --name: you do not need one. The service name is the DNS name.

Validate before starting:

There it is, everything the declarative model promises: the network and the volume created on their own, with their project prefix, and both containers running. Not one line of docker network create.

Look at the SERVICE column: that is the name you will use in every command, not the container's. Check that these objects are plain Docker:

The logs, aggregated and color-coded per service:

Verify that init.sql ran and that DNS works between services:

Nine books —the original eight plus El Aleph— and the cache answering by its service name. Now the part no bash script ever gave you for free:

One command for the entire platform, and it cleans up the network too. The volume has not been deleted: down preserves data by design. Check it and bring everything back up:

The nine books are still there. And if you now run docker compose up -d a third time, you will see reconciliation in action:

Running, not Recreated: nothing has changed in the file, so Compose touches nothing. That is idempotency.

Using tabs to indent. The most frequent error and the most baffling, because visually you cannot tell. Configure your editor to insert spaces in .yaml files and turn on the display of invisible characters.

Writing version: "3.8" on the first line. It has been obsolete since Compose v2. Compose ignores it and prints a warning. Delete it.

Using docker-compose with a hyphen. That is v1, unmaintained since 2023. Everything you learn here works with docker compose; the other way round, it does not.

Believing that down deletes your data. It does not delete named volumes... unless you add -v. That -v is the most dangerous command in Compose and it gets a detailed treatment in lesson 04-03.

Running commands from another folder. Compose looks for the file from the current directory upwards. If you launch docker compose ps from /tmp it will find nothing, or worse, it will find another project. Use -f ~/aurora-libros/compose.yaml when you are not in the right place.

Forgetting that the project name depends on the folder. Two people who clone the repository into folders with different names get different projects. Set name: in the file.

Not quoting ports. - 8080:80 looks harmless, but it is exactly the kind of bug that costs you half an hour. Always quote them.

Tip: run docker compose config after every non-trivial edit. It is free, instant, and it saves you from bringing up a broken stack.

Exercise 1. The following fragment has five errors (either YAML syntax or Compose usage). Find them, explain each one and write the corrected version.

Exercise 2. Without deleting your current project, bring up a second isolated copy of the same stack under the project name aurora-tests, check that its containers, network and volume are independent, and explain why it fails if you change nothing else. Then remove the copy completely, volumes included.

Exercise 3. Prove with commands that Compose creates nothing magical: starting from the running project, obtain (a) the labels Compose has put on the cache container, (b) the real network name and the address range it hands out, and (c) the volume's path on the host.

Solution 1.

Solution 2.

Compose's isolation reaches containers, networks and volumes, but not the host's ports: there is only one 127.0.0.1:5432, and the original project already holds it. The cleanest fix is not to publish a port in the copy; the services talk to each other over the internal network just the same.

Two complete stacks on the same machine, each one with its own prefixed volume, without sharing a single byte. Full cleanup of the copy:

down -v does delete the project's named volumes. Here that is what you want; in the real project, almost never.

Solution 3.

That config-hash is the key to reconciliation: it is the digest of the declared configuration. When you run up -d, Compose recalculates it and only recreates the container if the hash has changed.

A user-defined bridge network and a local volume in the usual path. Compose is a convenience layer over the same API you already knew: everything you learned in module 3 is still valid for inspecting and debugging.

You have changed paradigm. A bash script describes how to reach the desired state and breaks if you run it twice; a compose.yaml describes what that state is, it is idempotent, and it lives versioned in Git next to the code. You know that Compose v2 is a plugin of the CLI (docker compose, no hyphen), that the file is called compose.yaml and that version: is obsolete. You have a grip on the YAML you need —spaces and never tabs, maps, lists, quotes around ports— and you recognize the six syntax errors you will hit over and over.

You understand that Compose organizes everything under a project that acts as a namespace: it prefixes containers, networks and volumes, labels them with com.docker.compose.* and lets two identical stacks live side by side on the same machine. And you have checked with your own hands that the network and the volume are created and destroyed on their own, that down respects your data, and that a repeated up -d recreates nothing because it compares the config-hash of what you declared with what is running.

Your two-service compose.yaml works, but it only uses a handful of keys. In the next lesson, Defining Services in Docker Compose, you will get the full practical reference: every block of a service —image and build, identity, execution, network and ports, data, health and dependencies, resources and restart, labels— with its exact equivalent among the docker run options you already know, plus the top-level volumes: and networks: blocks and YAML anchors to avoid repeating configuration. By the end of that lesson you will have the four Aurora Libros services declared in a single file.