With the file written, it is time to master the tool that interprets it. The Compose CLI has around twenty-five subcommands, but the workload is very unevenly spread: you will use five daily, another five often, and the rest in specific situations.

This lesson walks through them by family, always on top of the Aurora Libros compose.yaml from the previous lesson. Pay particular attention to two pairs that get confused endlessly: up versus start, and exec versus run.

1. Master table of subcommands
2. up: the command that reconciles
3. down and the danger of -v
4. start, stop, restart, pause, create
5. Observation: ps, logs, top, stats, events
6. One-off execution: exec versus run
7. Building and publishing: build, pull, push
8. Local scaling with --scale and its limits
9. Diagnosis: config and validation in CI
10. Selecting files and project: -f, -p, COMPOSE_FILE
11. Autocompletion and useful aliases

One command people forget and that is extremely useful: docker compose ls works from any directory and tells you which projects are up on the machine and with which file.

docker compose up is 80% of daily usage. It is not "start": it is bringing the real state to the declared state. On each run, for each service, Compose computes a digest of its configuration (the config-hash you saw in lesson 04-01) and decides:

That selectivity is what makes editing the cache's memory and running up -d recreate only the cache, without tearing down the database.

--wait is the option that turns Compose into an automation tool: without it, the command returns control as soon as the containers are started, and a CI script that launches tests immediately afterwards crashes into a database that is not accepting connections yet. With --wait, Compose does not return control until every health probe passes, and it exits with a non-zero code if any of them fails to.

Without -d, up leaves your terminal attached to the aggregated logs of every service and Ctrl+C stops the whole stack. That is handy for debugging a startup; dangerous if you forget about it in an SSH session.

A very useful case for --no-deps: recreating just the API without restarting the database.

down is the inverse of up: it stops and removes the project's containers and networks.

Burn the second row into your memory. docker compose down -v deletes the project's named volumes without asking: in Aurora Libros, that is the bookshop's entire catalog. It is exactly what you want when resetting a development environment and exactly what ruins a server if you type it out of habit. Two defenses: declare critical volumes as external: true (lesson 04-02) and never create a shell alias that includes -v.

The restart trap deserves an explicit warning: it does not re-read the file. If you change an environment variable and run docker compose restart aurora-api, the container restarts with the old configuration and you go mad wondering why the change is not being applied. To apply changes from the file, always up -d.

--services is gold for scripts: for s in $(docker compose ps --services); do ...; done.

Logs are the tool you will use most:

Compose colors and prefixes every line with the service name, so docker compose logs -f on the whole stack lets you watch a request flow through web → api → db. Remember from lesson 03-04 that you will only see what the processes write to stdout/stderr.

port answers "which host port is the web front end's 80 published on?", and it is indispensable when you let Docker assign random ports.

This is the distinction that causes the most confusion, and the answer is simple: exec enters a container that is already running; run creates a new one.

-T disables pseudo-TTY allocation: mandatory when you redirect the output to a file or chain pipes, or the dump will come out full of control characters.

--rm almost always. Without it, every run leaves a stopped container behind on the machine; after a week you have forty aurora-libros-aurora-api-run-a3f9c2 containers taking up space. And --no-deps when the task does not need the stack: without it, an innocent run brings up PostgreSQL and Redis for you.

The typical CI flow, which you will see in full in lesson 06-02, fits in three lines: docker compose build, docker compose push and, on the server, docker compose pull && docker compose up -d.

There is the first clash: a fixed host port cannot be shared between three replicas. There is only one 3000 on the machine. And if the service had container_name, it would fail even earlier, because two containers cannot share a name.

Remove the fixed publication and it works:

Docker's internal DNS returns all three addresses for the same name, and the client picks one. It is a rudimentary distribution —no health checking, no weights, no retries— good enough for local testing, not for production. Real load balancing, with its strategies and its handling of dead replicas, is lesson 06-06.

docker compose config reads every file involved, interpolates variables, merges overrides and prints the final configuration exactly as Compose understands it. It is your only way of seeing the truth.

In a CI pipeline, --quiet is the first check that should run, even before building anything:

Two warnings about config: it resolves variables, so its output can contain passwords in the clear (never dump it into a public log), and it shows the normalized result, with the short forms converted into long forms. That normalization is exactly what you need in order to understand what a merge of anchors or files actually did.

Global options go before the subcommand:

With several -f, Compose merges the files in the given order and the last one wins in case of conflict. The full merge mechanism, with its rules per key type, is lesson 04-06.

One surprising detail: when you use -f, the base directory for relative paths becomes that of the first file. If your files are spread around, --project-directory lets you set it explicitly.

And the equivalent environment variable, useful for not repeating -f a hundred times a day:

With completion switched on, docker compose logs -f aur<TAB> offers you the project's real services: no more mistyped names.

That last comment is not a joke: most data losses with Compose come from a short alias somebody wrote with -v "to clean up quickly".

Using restart expecting it to apply changes from the file. It does not. A change in the compose.yaml → up -d, always.

Confusing stop with down. stop keeps the containers, down removes them along with the network. If after a down you expected to find the container stopped, it is not there.

Typing down -v out of habit. It deletes the named volumes and the data with them. Think about it every single time.

Forgetting --rm in run. Every execution leaves a stopped container behind. Clean up the accumulated ones with docker compose rm -f.

Running exec with redirection and no -T. The pseudo-TTY inserts control characters and corrupts dumps and binary files.

Putting -f after the subcommand. Global options go before it; the error the CLI returns does not always make that clear.

Tip: when something does not behave as you expect, the diagnostic order is docker compose config (what does Compose understand?), docker compose ps (what is running?) and docker compose logs (what does the service say?). In that order you solve almost everything.

Exercise 1. With the stack up, change aurora-cache's memory limit from 256M to 320M and apply it without the other three services restarting. Prove with commands that only the cache was recreated and that the new limit is in effect.

Exercise 2. Write a verify.sh script suitable for CI that: validates the file, brings the stack up waiting until it is healthy, runs the API tests in a throwaway container, prints the state of the four services and cleans up everything, volumes included, returning the tests' exit code.

Exercise 3. Without shutting the stack down, obtain: (a) the number of keys in Redis, (b) the first three catalog titles in alphabetical order, and (c) a dump of the books table into the host file ~/books.sql. Explain which option is indispensable in the third case and why.

Solution 1.

Edit the limit in the compose.yaml (limits: { memory: 320M, cpus: "0.5", pids: 100 }) and apply it:

There is reconciliation: Recreated only on the cache, Running on the other three because their config-hash did not change. Verification:

The cache is four seconds old and the others still show their twenty-two minutes. And 335544320 bytes is exactly 320 MiB. Careful: recreating a container is not restarting it, it is destroying it and creating another one; any data not held in a volume is lost. In Redis, that means an empty cache, which is harmless here because /books repopulates it from the database.

Solution 2.

Four important decisions: --quiet validates before spending time building; --wait with --wait-timeout guarantees the tests do not start against a database that is not answering yet and fails with a non-zero code if it never does; --rm --no-deps on the tests avoids leaving junk behind and does not bring up dependencies that are already healthy; and down -v is correct and desirable here, because this is a throwaway environment. Notice that $? is saved before the cleanup commands: otherwise the exit code the script returns would be down's, and the pipeline would always come out green.

Solution 3.

In the third case -T is indispensable. Without it, Compose allocates a pseudo-TTY to the command and the output stream stops being clean binary: line breaks get translated and control sequences slip in, so the resulting .sql may not be importable again. The rule is simple: if you are not going to read the output with your own eyes, use -T.

You now handle the full CLI. You know that up is not "start" but "reconcile": it compares each service's configuration digest with the declared one and recreates only what changed, which lets you tweak a limit and touch a single container. You know its decisive options —-d, --build, --pull, --force-recreate, --no-deps, --remove-orphans and above all --wait, which waits for the health probes to pass and fails if they do not. And you are clear on what each variant of down deletes, with -v flagged in red.

You tell start/stop/restart/pause apart from up/down, with the trap that restart does not re-read the file. You observe with ps (including --services and --format json), logs, top, stats, events and port. And you have internalized the key difference: exec enters what is already running, run creates a new container, with --rm so you do not pile up junk, --no-deps so you do not bring up half the stack, and -T when you redirect the output. You build and publish with build/pull/push, you scale locally with --scale knowing that it clashes with fixed ports and with container_name, you validate with config --quiet in CI, and you control which file and which project you are using with -f, -p and COMPOSE_FILE.

In the next lesson, Multi-Container Applications, all of this goes into service of the definitive assembly: the Aurora Libros architecture with two segmented networks —a frontend one and a backend one marked as internal—, Compose's DNS and the table of who talks to whom and over which port, startup order solved with depends_on and condition: service_healthy using pg_isready and redis-cli ping, a migration service with service_completed_successfully, and the retry-with-backoff pattern you still need even with all of the above in place. By the end, the fifteen onboarding steps will be down to two.