rmoff / excalidocker-rs

Convert your docker-compose into excalidraw

excalidocker-rs

Rust-based utility to convert docker-compose.yaml files into excalidraw files.

Key features

• Transform your local docker-compose files into excalidraw with just a single docker run command. Showcase your infrastructure designs in a visually appealing and engaging format.
• Convert external docker-compose files into excalidraw by simply providing a Github link. Easy to share and collaborate.
• Available for installation on both Linux and MacOS platforms (amd64/arm64).
• Design customization. Tailor your infrastructure diagrams to your specific needs by customizing font, background colours, styles, etc.

Table of contents

• Motivation
• Usage
  • Docker image
  • Binaries
  • Config file
  • Demo
• Installation
• Contributing
• Roadmap

Motivation

An idea of writing this utility originates from Robin Moffatt's tweet.

Usage

Docker image

🐳 excalidocker is available as a docker image. Convert docker-compose files without hassle. Use as a Github action for documentation, presentations, ADRs what have you. The sky is the limit. Get the latest image from docker hub:

docker pull etolbakov/excalidocker:latest

Convert a local file:

docker run --rm \
-v "$(pwd)/data/compose/:/tmp/" \
-e INPUT_PATH=/tmp/docker-compose.yaml \
etolbakov/excalidocker:latest > produced-by-image.excalidraw

Convert an external file:

docker run --rm \
-v "$(pwd)/data/compose/:/tmp/" \
-e INPUT_PATH=https://github.com/apache/pinot/blob/master/docker/images/pinot/docker-compose.yml \
etolbakov/excalidocker:latest > produced-by-image-remote.excalidraw

A produced excalidraw file could be opened in excalidraw and .... hopefully it won't be too scary 👻 😅.

Convert a local file proving a config

The command below shows how to pass the config file for additional customization

 docker run --rm \ 
 -v "$(pwd)/data/compose/:/tmp/" \
 -v "$(pwd)/excalidocker-config.yaml:/tmp/excalidocker-config.yaml" \
 -e INPUT_PATH=/tmp/docker-compose.yaml \
 -e CONFIG_PATH=/tmp/excalidocker-config.yaml \
 etolbakov/excalidocker:latest > produced-by-image-config-deps.excalidraw

More command examples are in the Makefile.

Binaries

📚 Download the latest artifact for your platform/architecture from releases and ungzip it.

To get the help menu use:

./excalidocker -h

The output should be similar to:

Utility to convert docker-compose into excalidraw

Usage: excalidocker [OPTIONS] --input-path <INPUT_PATH>

Options:
  -i, --input-path <INPUT_PATH>    file path to the docker-compose.yaml
  -s, --skip-dependencies          display connecting lines between services; if `true` then only service without the lines are rendered
  -o, --output-path <OUTPUT_PATH>  file path for the output excalidraw file. By default the file content is sent to console output
  -c, --config-path <CONFIG_PATH>  config file path for the excalidraw. [default: excalidocker-config.yaml]
  -h, --help                       Print help
  -V, --version                    Print version

Usage example:

./excalidocker --input-path /your/path/docker-compose.yaml --output-path /your/path/result.excalidraw

Warning

On the first launch the ungzipped artifact I saw the following pop up "Mac cannot be opened because it is from an unidentified developer" If you are fine with that you can Control-click the artifact, then choose Open from the shortcut menu. Click Open. The utility will be saved as an exception to your security settings, and you can open it in the future by double-clicking it just as you can any registered app.

Config file

🎨 excalidocker supports basic customization provided via file, for example excalidocker-config.yaml. At the moment it's possible to customize:

• font size and type
• fill type (hachure, cross-hatch, solid)
• backgroud colours for services and ports
• edge type (sharp, round)
• enable/disable connections (has the same effect as --skip-dependencies cli option)

Demo

🎥 This is a small demo to see the excalidocker in action

Installation

To build excalidocker locally, please follow these steps:

1. Install Rust and Cargo if you haven't already. Refer to the official Rust documentation for installation instructions:
2. Clone this repository:

git clone https://github.com/etolbakov/excalidocker-rs.git

3. Build the project using Cargo:

cd excalidocker-rs && cargo build --release

There is the make r command available in the Makefile along with other useful command shortcuts.

Roadmap

These are the features that I would like to add at some point:

• 📊 visualize more data from a docker-compose file - volumes, network, etc
• 🦀 various code improvements/enhancements. Feel free to review/suggest if anything could be done better!
• 👨‍💻 etc

Contributing

Contributions are welcome! If you encounter any issues, have suggestions for improvements or would like to participate please open an issue or submit a pull request.

License

This project is licensed under the MIT License. Feel free to customize the text based on your project's specific details, such as repository URLs, installation instructions, and contribution guidelines.