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
network: foo services: foo: labels: - "com.example.description=Accounting webapp" - "com.example.department=Finance" - "com.example.label-with-empty-value" tmpfs: - /tmp - /var/run environment: - 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: https://github.com/funkwerk/compose_format
It’s Docker image is here: https://hub.docker.com/r/funkwerk/compose_format/
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?