Link Search Menu Expand Document

Docker Compose Viz (Mermaid)

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
  2. Usage
  3. How to read the flowchart
    1. Links and dependencies
      1. Implicit links
    2. Ports
    3. Volumes
    4. DBs
  4. Generating images
  5. Data privacy

Installation

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

Given a JRE is installed on your machine, run:

java -jar docker-compose-viz-mermaid-*.jar

Usage

The best way to understand how it works is to run the tool with the -h option:

Usage: cli [OPTIONS] [docker-compose-path]

  Generate a mermaid graph from a docker-compose file.

  There are different kind of outputs:

  * '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.

  When using theme and classes, the output may become hard to read depending on the background.
  It is thus possible to force a background (using a hack) with the option `-b`.

Options:
  -d, --dir [LR|RL|TB|BT]                   Graph orientation (default: TB)
  -t, --theme [DEFAULT|DARK]                Graph theme (default: DEFAULT)
  -p, --ports / -P, --no-ports
  -v, --volumes / -V, --no-volumes
  -l, --ilinks / -L, --no-ilinks            If set, try to find implicit links/depends_on by looking
                                            at the environment variables, see if one if pointing to
                                            the host:port of another service
  -c, --classes / -C, --no-classes          If set, add some classes to mermaid to make the output
                                            nicer
  -f, --format [TEXT|MARKDOWN|EDITOR|PREVIEW|PNG|SVG]
                                            Control the output format, case-insensitive. (default:
                                            TEXT)
  -b, --with-bg / -B, --no-bg               If set, try to find implicit links/depends_on by looking
                                            at the environment variables, see if one if pointing to
                                            the host:port of another service
  -o, --out PATH                            Only available for format TEXT and PNG
  -h, --help                                Show this message and exit

How to read the flowchart

The generated graph should be rather straight-forward (see examples).

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.

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).

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, and I strongly suggest to check it out. 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 takes advantage of online tools, namely:

Note that the image may sometimes be of poor quality, or not what you expect. If you see any problem in the rendered output, generate the images manually or try using the above tools directly. Don’t hesitate to report issues on their own github repositories if required.

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 is the only output format which directly uses third-party services (see generating images). Again, only the graph is sent for rendering, and not the docker-compose itself. If you have a doubt, do not use image generation and rely on the mermaid-cli tool or other more trusted alternatives to render images.