Inspired from docker-compose-viz, Docker Compose Viz (Mermaid) is a tool to transform docker-compose files into mermaid flowcharts.
Table of contents
Installation
This is a simple jar, that you can download from:
Note that Docker Compose Viz (Mermaid) comes in two flavors:
- normal jar (default): quite heavy (86M+), but contains everything to generate PNG/SVG locally, with no internet access. This is best for security, and the rendering is of good quality;
_no_localjar: very light, but uses third-party online tools to generate PNG/SVG (https://mermaid.ink by default). The quality is sometimes off, and depends on the upstream. Not all features are perfectly supported (e.g. no PNG for kroki.io).
Given a JRE (java 8+) is installed on your machine, run:
java -jar docker-compose-viz-mermaid-*.jar
(Note: if you want to use the mermaid-cli renderer, you will need nodejs and npm installed on your machine.)
Usage
The best way to understand how it works is to run the tool with the -h option:
Usage: cli [OPTIONS] [docker-compose-path]
Visualize a docker-compose, by converting it to a Mermaid graph.
Supported outputs (`-f`):
* 'text' (default) outputs the mermaid graph (use -o to output to a file instead of stdout);
* 'markdown' is same as text, but wraps the graph text in '```mermaid```'
* 'png' or 'svg' generates the image and saves it 'image.[png|svg]' (use -o to change the destination);
* 'editor' // 'preview' generates a link to the mermaid online editor, and print it to the console.
You can further customize the result using the options below.
Processing options:
-p, --ports / -P, --no-ports Extract and display ports
-v, --volumes / -V, --no-volumes Extract and display volumes
-n, --networks / -N, --no-networks Extract and display networks
-l, --ilinks / -L, --no-ilinks Try to find implicit links between services by looking at the
environment variables
Output options:
-f, --format [TEXT|MARKDOWN|EDITOR|PREVIEW|PNG|SVG]
Output type (case insensitive) (default: TEXT)
-o, --out PATH Write output to a specific file
-b, --with-bg Force background color
-d, --dir [LR|RL|TB|BT] Graph orientation (default: TB)
-t, --theme [DEFAULT|DARK] Graph theme (default: DEFAULT)
-c, --classes / -C, --no-classes Add CSS classes to mermaid to make the output nicer
Options:
--version Show the version and exit
-h, --help Show this message and exit
How to read the flowchart
The generated graph should be rather straight-forward (see examples).
Links and dependencies
Both links (from services.<service>.links) and dependencies (from services.<service>.depends_on) are displayed using plain arrows. In case a link defines an alias (using container:alias), it is shown as text on the arrow connector.
Here, both apis need db, and web needs both apis. web will connect to the search api using the alias search-api-alias.
Implicit links
If implicit link is enabled, Docker Compose Viz (Mermaid) will try to deduce implicit dependencies from environment variables, which will be shown exactly as the links and dependencies above. For a link to be discovered, the environment value must:
- refer to another service, either through its internal
host:portor through the exposed host port (usinglocalhost,127.0.01or${DOCKER_HOST_IP}as the host part), - have a value matching either
host:port, or<scheme>:[<driver>:]<host>:<port>[/.*].
Here are typical examples:
bar:
ports:
- 8080:1234
foo:
environment:
# links using internal host:port
LINK_INTERNAL_1: bar:1234
LINK_INTERNAL_2: https://bar:1234/auth
LINK_INTERNAL_3: jdbc:postgresql:bar:1234/db
# links using external port
LINK_EXTERNAL_1: https://${DOCKER_HOST_IP}:8080/auth
Ports
Ports (from services.<service>.ports) are displayed as circle and are linked to containers using plain arrows. The port shown in the circle is the port exposed on the host, while the internal port is shown as text on the arrow connector (80:8080). If both ports are the same (e.g. 443:443), or only one port is defined (e.g. 443), only the port in the circle is shown.
If classes are enabled, the color of the port will be gray.
Volumes
Volume shapes and text depend on the type of volume:
- host binds → hexagonal shape, text matching the path on the host;
- named volumes → rounded rectangle, text matching the name of the volume;
- anonymous volumes → text set to
⋅ ∃ ⋅(logical operator meaning there exists);
- anonymous volumes → text set to
- tmpfs mount → diamond with no text;
- named pipe → banner, text matching the path on the host.
Volumes are pointing to the container using dotted connectors ending with x on both sides. read-only connectors miss the x on the volume side. The text inside the shape is the source of the volume (on the host), while the text on the connector is the target (inside the container).
If classes are enabled, the color of the port will be yellowish (light theme) or purple (dark theme).
Network bindings
Network bindings are displayed as parallelograms and are linked to containers using dotted connectors. Any alias(es) or ip(s) will be shown as text on the connector, separated by commas. Only network bindings are supported, that is networks keys defined at the service level.
If classes are enabled, the color of the network will be light green (light theme) or blue (dark theme).
DBs
The tool tries to automatically detect database services and render them as cylindrical shapes. The detection is dumb enough, looking for services named database, db or well-known database providers (mysql, redis, etc.).
Generating images
Docker Compose Viz (Mermaid) outputs the generated graph in mermaid syntax by default, and is its primary purpose. Once you have a mermaid graph, a lot of tools and options exist to generate pretty much anything (png, svg, pdf, etc.).
For example, the mermaid-cli has many options and capabilities. Another possibility to get images is to copy-paste your graph in the Mermaid Live Editor (or you the -f editor option, which will generate the link to the editor with the graph directly).
Automatic way
For convenience, Docker Compose Viz (Mermaid) also gives you the option to generate images directly in multiple formats (see output types).
To do so, it launches and instruments a headless Chromium using https://playwright.dev by default. The latter will download Chromium the first time it is launched, so be patient and don’t worry: the next execution will be dazzlingly fast.
Another option is to use well-known online tools to render images, namely https://mermaid.ink/ or https://kroki.io. You can finally opt for the official mermaid-cli tool, but this requires you have nodejs and npm available on your system. The installation of mmdc (mermaid-cli) will be handled by docker-compose-viz-mermaid on first use. Have a look at environment variables for details.
Data privacy
This tool processes docker-compose, which can hold sensitive information. Thus, it is important to state that docker-compose-viz-mermaid only reads the information needed to show the graph and doesn’t store or spy on anything. As long as you only ask for mermaid graphs as text (default output), everything stays on your machine, and you can always check the output to see if anything sensitive is exposed.
When generating links to the mermaid editor or the live preview (see output types), the graph is encoded in base64 to generate the link. It is up to you to decide to open the link, and hence “share” your graph with the mermaid online tools (which to my knowledge use client-side JS for rendering, thus is safe from a data privacy standpoint).
Image generation uses a headless Chromium running locally by default. It is thus completely safe. However, other renderers are available, that can use third-party services (see generating images and see environment variables). For complete privacy, always use the default renderer.