Inspired from docker-compose-viz, Docker Compose Viz (Mermaid) is a tool to transform docker-compose files into mermaid flowcharts.

Table of contents

1. Installation
   1. Using docker
   2. Running directly
2. Usage
3. How to read the flowchart
   1. Links and dependencies
      1. Implicit links
   2. Ports
   3. Volumes
   4. Network bindings
   5. DBs
4. Generating images
5. Data privacy

Installation

Using docker

It is available on DockerHub for both ARM and AMD.

For example:

docker run --rm -v $(PWD):/data derlin/docker-compose-viz-mermaid /data/docker-compose.yml -f png
# -> will generate the image.png in the current directory

Running directly

This is a simple jar, that you can download from:

• nightly,
• releases.

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_local jar: 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
  --debug     Be verbose
  -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:

1. refer to another service, either through its internal host:port or through the exposed host port (using localhost, 127.0.01 or ${DOCKER_HOST_IP} as the host part),
2. 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);
• 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.