Visualize Your Docker-Compose with Mermaid + docker-compose-viz This Weekend
I have been big into documenting my home lab and finding tools that are great for creating documentation for my DevOps processes in the lab and in production. This has led me down a rabbit hole of trying all sorts of documentation tools and tools that can help visualize my docker compose code. If you have been looking for tools that can help you visualize your Docker compose code, you are in the right place. Let’s look at a project you can enjoy this weekend which is visualizing your Docker Compose stack with simple tools.
Why visualize Docker-Compose services
Visualizing your home lab services is a great way to add visuals to your documentation. Have you ever thought it would be a great idea to have a visual of your Docker compose code? I have often thought it would be great to have a visual graph of the Docker Compose services, volume mounts, networks the services connect to, etc.
As it turns out, there are several tools out there that can turn YAML into architecture diagrams that show many of these things like ports, dependencies, and other things. If you are a home labber, this means faster troubleshooting and easier maintenance of your stacks. And, of course for production team environments, it means that you can onboard ones easier with visual documentation and help them get up to speed.
Let’s see what tools are available out there to use for diagramming and visualizing your Docker Compose code.
Docker-compose Viz
One of the simplest tools to start with is docker-compose-viz. This is a small utility that accepts your docker-compose.yml file as input and generates a graph using Graphviz. Better yet, the project is packaged as a container itself. So you don’t have to hunt and search and install the dependencies on your host machine. You simply run it against your Compose file and get back a diagram.
One hurdle I did find is there are a lot of projects on GitHub that show to be compose-viz or some variant. There was one that was updated very recently that works well and that is the one that I am showcasing below.
Here is the docker run command to visualize your docker-compose.yml file using the compose-viz project.
docker run --rm -it -v $(pwd):/in wst24365888/compose-viz -m svg docker-compose.ymlThe file that it generates is a compose-viz.svg file. I really like the look and feel of the compose-viz output. Below is the actual output SVG of a test compose file I fed into the tool. I think the output is great in that you can see the ports, the containers, the volumes, and the network they are attached to. The one disappointment with the tool is you don’t get service discovery with it. It would be nice if it could enumerate the hosts associated with the containers.
There are quite a few flags you can pass along with the container:
| Option | Description |
|---|---|
-o, --output-filename FILENAME | You can control the name of the output file [default: compose-viz] |
-m, --format FORMAT | Output format for the generated visualization file [default: svg] |
-r, --root-service SERVICE_NAME | Root of the service tree (convenient for large compose yamls) |
-l, --legend | Include a legend in the visualization. |
-p, --no-ports | You can choose to not show ports |
-s, --simple | A more simple graph with image names and only basename of sources |
-v, --version | You can choose the version |
--help | Show help |
Another great use for the tool is you can use this in CI/CD pipelines where you want to automatically publish diagrams as part of your project’s documentation.
Docker Compose Viz with Mermaid
As you may know, Mermaid is a text-based diagramming tool that lets you describe graphs in plain text. Then you can render them to PNG or SVG. The cool thing with being able to describe anything in text, is you can have it in version control right with your code and you can update it and render it in your pipeline.
Note the following GitHub link for this project in particular:
Here’s a simple example of a Mermaid diagram for a stack with Traefik, a dashboard app, and an API:
docker run --rm -v $(pwd):/data derlin/docker-compose-viz-mermaid docker-compose.yml -f png
You can see even though this was a diagram of the same docker-compose file it looks different with the Mermaid styling. Mermaid is great in that GitHub and GitLab and other code repos as these can natively render Mermaid diagrams in markdown files. This means you can drop the snippet into your repo’s README and have it display automatically.
Using AI to create Mermaid Code directory
One of the other things you can do is feed something like ChatGPT your Docker Compose code and then with a prompt, ask it to render the Docker Compose as Mermaid code. Also, unlike the other tools, you can ask it to include anything you want, like service discovery of hosts.
We all know this that AI is changing everything and allowing us to have automation and visualizations that we never had before, including graphing of our Docker Compose code. With Mermaid you can highlight details like TLS termination, middleware, or specific network paths and ask AI to do this in really any way you want it to be rendered.
Suggested prompt:
Convert Docker Compose YAML into a clean Mermaid graph. Requirements:
- Return ONLY raw Mermaid starting with 'graph LR' (no prose, no code fences).
- Use graph LR.
- Represent services as nodes.
- Represent docker networks as subgraphs with label "network: <name>" (quote the label).
- Add edges for depends_on if present.
- If Traefik labels include Host(...) rules, create a SINGLE edge from traefik to the target labeled with that hostname (no unlabeled duplicate).
- Show host → container port mappings as dashed edges from Internet to the service, label "hostPort → containerPort".
- Keep labels concise.Also, I like the fact that unlike the limitations that exist for mapping hostnames for your services in the resulting drawing, AI can include this as well.
I am also experimenting around with creating an n8n workflow to create the resulting graph file of my docker-compose, but I don’t really have that workflow hammered out as of yet, at least enough to share. Look for a follow up on this where I will show how to use n8n to create these as well.
Documentation for home labs
For home labs I think being able to visualize your docker compose services is a valuable tool to build out very powerful documentation for your self-hosted services. A picture is worth a thousand words and I definitely would rather look at a visualization of compose code rather than read through the code to see what it does.
However, we are not saying a picture replaces all text documentation, just that it is a powerful complement to what we already are doing with our traditional documentation. And the compose code or YAML in your Kubernetes clusters is documentation in itself and that is the beauty of infrastructure as code. Just add the visualizations and you will have a complete set of documentation for your services.
Check out my posts here for more ideas when it comes to documenting your home lab:
- How to Document Your Home Lab (The Right Way)
- Why I Started Documenting My Docker Containers and What I Include
Wrapping up
These are just a few of the tools you can use to document and diagram your docker-compose code. Docker compose viz is a straightforward tool that is easy to use and the SVG file is extremely detailed and looks great. I honestly think the SVG file that is produced looks great and it can be produced from a CI/CD pipeline. The same goes for the docker-compose viz tool that also integrates Mermaid code. The last option is simply using AI to document the docker-compose code which has many advantages too. You can have it render Mermaid code or something else. Stay tuned for incorporating n8n into this workflow. Have you found another tool that you like to render or visualize your Docker Compose code?
