Aurora Libros is declared and parameterized, but in real life the same platform gets brought up in three different ways: on the developer's laptop, on the continuous integration runner and on the server. The differences are few —build instead of pull, expose or hide certain ports, higher limits— and the temptation is to duplicate the file.

Duplicating it is the worst path: two files diverge within a week. Compose offers two complementary mechanisms to avoid that: profiles, which activate optional services on demand, and override files, which merge on top of a common base.

1. Profiles: services you do not always want
2. Profiles and dependencies: the rules
3. The automatic override: compose.override.yaml
4. Explicit overrides with several -f
5. The merge rules
6. !reset and !override: replacing instead of merging
7. The Aurora Libros strategy: base, development and production
8. extends: reusing definitions across projects
9. include:: composing files from several teams
10. File and project naming conventions

A service with the profiles: key is not brought up unless its profile is active. It is how you keep optional tooling in the same file without it getting in the way.

A service can belong to several profiles (profiles: [tools, ci]), and it is activated if any of them is active.

With Adminer up, http://localhost:8081 gives you a web interface for exploring the catalog without installing anything on your machine. And COMPOSE_PROFILES=tools in your local .env turns the profile on permanently for you, without affecting anybody else.

A very practical use of a profile for one-off tasks:

There are three behaviors worth being clear about here, because they are a source of surprises:

The two important rows: naming a profiled service activates it implicitly —docker compose up -d adminer just works— and docker compose down leaves profiled services orphaned if you do not repeat the profile. It is the number one cause of "I ran down and there are still containers".

Design rule: base services must never depend on a profiled service. The dependency always runs the other way.

If a file called compose.override.yaml (or .yml) exists next to the compose.yaml, Compose loads and merges it automatically, without you having to say anything.

It is the perfect mechanism for the development environment: the compose.yaml describes the platform neutrally and the override adds what only makes sense on your machine. And since the override is ignored on the server —where other explicit files are used— there is no risk of a debugging port ending up in production.

When you pass files with -f, the automatic override stops being loaded: you are in charge.

Compose reads the files in the given order and merges each one over the accumulated result: the last one wins. Order matters and is a classic source of errors; if you swap the files around, the base file overwrites the specific one.

Relative paths are resolved against the first file's directory, unless you use --project-directory. If your overrides live in a subdirectory, keep that in mind:

What happens when merging depends on each key's type:

The distinction between the first two rows and the third explains 90% of the surprises. An example:

environment has been merged (NODE_ENV survives, LOG_LEVEL is replaced) and ports has been concatenated (both ports). Lists concatenating is convenient for adding, but it means you cannot remove a port or a volume from an override... except with what comes next.

Compose v2.24 introduced two YAML tags that solve exactly that problem:

!reset empties the inherited key (and with null it removes it entirely), and !override replaces the value instead of merging it. They are the only clean way to remove in an override what the base adds, and they do away with the old workaround of maintaining two nearly identical base files.

The recommended structure is three files with clearly separated responsibilities:

The base is the one from lesson 04-04, with one added rule: nothing environment-specific. No build, no debugging ports, no NODE_ENV pinned by hand.

The details of code bind mounts and automatic reloading are lesson 04-07; what matters here is where that configuration lives: in the override, never in the base.

Note three decisions: the image version is mandatory (:?), because deploying latest is deploying anything at all; build: !reset null guarantees the server never builds; and ports: !reset [] removes the inherited 3000, it does not add to it.

Always verify a deployment before running it:

Where overrides merge whole files, extends imports one specific service, even from another file or project:

The depends_on limitation is deliberate: a dependency only makes sense inside the project that defines it. Use extends for configuration templates (base image, user, restart policy) and YAML anchors for repetition within the same file.

include: goes one step further: it pulls in complete Compose files, with their services, networks and volumes, as if they had been written in yours.

The difference from -f is important: with several -f the files are merged (they are expected to talk about the same services), whereas include aggregates independent files that contribute services of their own. Each included file keeps its own path and variable context, which lets the payments team maintain their compose.yaml without coordinating with the platform one. In exchange, service names have to be unique across the whole set.

And a project name per environment, so two stacks can coexist on the same machine without stepping on each other:

Two complete stacks, with containers, networks and volumes prefixed differently, not sharing a single piece of data. The only thing that remains global to the machine is the published ports: that is why the development override uses 8080 and the production one 80.

To avoid typing the -f a hundred times a day, pin the set in the environment:

Swapping the order of the -f. -f compose.prod.yaml -f compose.yaml makes the base overwrite production. The specific one goes last, always.

Expecting an override to remove a port. Lists are concatenated. To remove, !reset or !override.

Running down without repeating the profile. Profiled services keep running. Repeat --profile or use --remove-orphans.

Putting build in the base file. A server will end up building the image instead of pulling the version you tested. build belongs in the development override.

Deploying without pinning the image tag. latest in production means two servers may be running different code. Use ${AURORA_API_VERSION:?...}.

Assuming extends brings the dependencies along. It does not import depends_on: you have to redeclare it in the extending service.

Tip: before any deployment, run docker compose -f ... config and read it. Thirty seconds of reading keeps you from deploying a debugging port open to the Internet.

Exercise 1. Create a compose.override.yaml that, for aurora-api, changes LOG_LEVEL to debug, adds port 9229 and mounts ./api/src. Without bringing anything up, prove with docker compose config that the inherited NODE_ENV survives, that there are two ports and that the volume appears alongside the base ones.

Exercise 2. Add an adminer service under the tools profile and answer with commands: (a) does it show up in docker compose ps --services without the profile?, (b) what happens if you name it explicitly in up without --profile?, and (c) what happens when you run docker compose down without the profile? Propose the correct way to bring everything down.

Exercise 3. Write a compose.prod.yaml that completely removes the API's port 3000 publication, requires the AURORA_API_VERSION variable and prevents building on the server. Prove with config that the result contains neither build nor port 3000, and that it fails clearly if the version is not defined.

Solution 1.

You can see the three rules in action: environment is a map, so NODE_ENV survives and only the matching key is replaced; ports and volumes are lists, so they get concatenated. Notice too that config has normalized the relative path ./api/src into an absolute one: that normalization is exactly what makes a pre-deployment review trustworthy.

Solution 2.

(a) Without the profile, the service is not even considered. (b) Naming it activates it implicitly: you do not need --profile if you ask for it by name. (c) And here is the surprise: after docker compose down, adminer is still alive, because down without the profile does not take it into account. It is an orphaned container still holding port 8081 and still able to reach the database.

Solution 3.

The image is pinned to a specific tag, neither build nor port 3000 shows up —!reset removed them, something a plain redefinition would not have achieved with lists— and without the variable the deployment fails before touching anything, with a message that says what to do. That early failure is exactly what you want in a pipeline: better a red config --quiet than a server serving an unexpected version.

A single project now serves three environments without duplicating a single service. Profiles give you optional services on demand —adminer and mailhog under tools, seed under data— activatable with --profile, with COMPOSE_PROFILES or simply by naming the service, with two rules people forget: a base service must never depend on a profiled one, and down without repeating the profile leaves orphaned containers running.

Overrides cover the rest: the automatic compose.override.yaml for development conveniences and explicit combination with several -f where the last one wins. You have mastered the merge rules —scalars that get replaced, maps merged key by key, lists concatenated, and blocks like command or healthcheck.test replaced wholesale— and you know how to get out of the list dead end with !reset and !override, the clean way to remove a debugging port in production. The strategy is clear: a neutral compose.yaml with no build and no debugging ports, a development override and a compose.prod.yaml with a mandatory image tag, restart: always, its own limits and logging configured; and docker compose config read before every deployment.

You also know when to use each reuse tool: YAML anchors within a file, extends for service templates across projects —remembering that it does not carry depends_on— and include: for aggregating complete files maintained by other teams, each with its own path and variable context. Plus the file and project naming convention (-p aurora-dev, -p aurora-prod) that lets two stacks coexist on the same machine without sharing a single byte, with COMPOSE_FILE so you do not have to repeat the -f.

What is left is the part you will use most: the day-to-day. In the next lesson, Local Development with Docker Compose, you will turn that development override into a real working environment: a bind mount of the code with the solution to the eternal node_modules problem, automatic reloading with Node 22's --watch and with Compose's native develop.watch block, step-by-step debugging from VS Code with the inspector on port 9229, tests in throwaway containers with their database in tmpfs, development data and a one-command reset, bind mount performance on macOS and Windows, and a Makefile with the team's shortcuts.