Compose's next new feature = "includes"

🗓️ What's new

Compose "includes" is released

Compose Watch (aka sync) was the first big 2023 addition I recently explained in a YouTube Short (and it keeps getting faster/better). Then, Docker just added the 2nd new prominent feature to Docker Compose this year: includes.

Today, I'll talk about the new includes that helps you separate your various app parts into separate files.

🤔 But wait, we already had that with overrides and extends, right?

Yes, well, kinda. Let's review:

I am a long-time advocate of overrides for customizing your local Compose setup by merging multiple files. You can do this by listing two or more yaml files with the docker compose -f command option. Compose will then merge them together, and with each subsequent -f, it'll override the previous files. In this way you can stack (merge) files on top of others.

My most common use for overrides is to make my workflow easier by using the conventions of a docker-compose.override.yml file to automatically change anything in the original docker-compose.yml. Compose merging in that way is handy for making a generic compose setup stored in the git repo with the code and then use the override file to customize the generic file for your local machine workflow (ports, envs, volumes). ProTip: add docker-compose.override.yml to .gitignore so anyone can just keep their local yaml in the same directory as the app and never worry about it sneaking into a git commit. In this way, you can just use docker compose up and it will look for the compose and override files automatically.

Note you can now also remove docker- from your compose file names so they become compose.override.ymland compose.yml.

Next, we've had extends, which for years was supported in compose file version: 2.x but never made it into 3.x, so some of you may have forgotten about it. Since 2020 though, we're all using the Compose Spec (versionless) which brought extends support back, so we can again use multiple yaml files in our compose apps, and extends allowed us to be very specific about what we were overriding in the file. Often if you couldn't figure out a way to do something with extends, you could make it work with overrides, and vice versa.

But there were some use cases that these two ways still didn't solve well, and Docker's Nicolas De Loof detailed why includes was born.

He goes on to detail in that post that includes is great when you have different people (or teams) managing different compose files used together for a single solution.

The includes method for combining yaml files together to create a full solution is a great addition and something I'll likely use more with larger teams that have multiple people managing multiple parts of the whole compose solution. They can now manage their own compose files and all those yaml's can be brought together for easy local use across directories and repos.

Even better, a feature idea may allow us to point to a git URL for dependent YAML, meaning you won't need to use local file paths to use cross-repo compose files!