Docker Community Forums

Share and learn in the Docker community.

Docker-compose.yml Best Practices

docker-compose.yml files could be written in various ways. If they are written in various ways then it’s hard to understand them, cause everybody writes them a bit different. So in the community several good practices evoled.
Here are some good practices I found during reading dozens of compose file from various authors.

Starting with a not well structured example to explain what is considered as bad practice:

Example: Not well structured compose file

    - "com.example.description=Accounting webapp"
    - "com.example.department=Finance"
    - "com.example.label-with-empty-value"
    - /tmp
    - /var/run
    - FOO=BAR
    - BAR=BAZ
    image: ubuntu:14.04
version: '2.0'

Good Practices for docker-compose.yml Files

Good Practice: Mention important things first

The compose file above is considered as bad, cause it starts with boring information and at the end comes to the important ones.

So it is usually considered a good practice to first mention the image for a service. Mention the important things first, later the details.

Good Practice: Group by category

Another good practice is to group items by a category. Networking configurations should be kept close together. Security things as well. It’s also good to keep entrypoint and command next to each other.

Good Practice: Avoid Whitespaces

Another good practice is to avoid unnecessary whitespaces. Adding whitespaces just results in churn commits. Diffing gets difficult.

Good Practice: Sort Services Alphabetically

If compose files grow, then it’s tedious to find services. If the services are ordered alphabetically, then it is easy to find them.
Also Environment Variables, Ports, Networks and many other things also should be sorted alphabetically.


To assist in avoiding simple mistakes, I wrote a small program. It’s called compose_format.
It’s available here:
It’s Docker image is here:

To format your compose files, simply execute

cat docker-compose.yml | docker run -i funkwerk/compose_format

Would love to hear your opinion about it.
Are there some best practices missing?
What do you do to keep your compose files clean?