Working with docker compose in a development team

Josué Carvajal
2 min readDec 21, 2021



When working in development teams we do not want to modify the docker-compose.yml that is hosted in the repository to avoid conflicts with other members of the team. To achieve this, docker has a tool called override, which is basically the same docker-compose.yml.

Compose override

As stated before, this file is called docker-compose.override.yml and it is meant to override/add stuff to the original docker-compose.yml file, the name does not have to follow that structure, but, to keep the consistency with the official docs of docker we are going to call it in that way. Keep in mind that some dev companies uses other naming convention such as:, docker-compose.test.yml, docker-compose.staging.yml

This file follows the same logic when we are using override methods in any programing language, with some limitations.

Understanding the override flow

In the following diagram you can see the two files, in which in the override file we are adding different stuff to the original file. What occurs is that docker (seeing from a high level perspective) will do a merge of the settings that we have in both files and create a single docker-compose file during the execution. This is not as straight forward like this, there are different steps that are performed during the build which also leads to some limitations.

Docker override overview

Some limitations with this override are the ports, you should never specify ports in the override file, usually the docker-composer.yml is the first part compiled and docker does not understand how to change the given ports if they are specified in the override file. Another caveat is, in the image above, if we run docker-compose up it will create our build with the name in the original docker compose file, and not the auto-generated one.

Last but not least, remember that the override file will have more privilege rating compared to the docker-compose.yml file, this means that if you add a custom environment variable such as MONGO_URL which also exists in the original docker compose, the value of the variable will be the one located in the override file

Thanks for reading, more content soon!



Josué Carvajal

Sr. Security software engineer working in the DevSecOps area. CompTIA Sec+, C|EH