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
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.
Convert a local file:
docker run --rm --pull always \
-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 --pull always \
-e INPUT_PATH=https://github.com/apache/pinot/blob/master/docker/images/pinot/docker-compose.yml \
etolbakov/excalidocker:latest \
> produced-by-image-remote.excalidraw
The produced excalidraw
file can 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 --pull always \
-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
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 chooseOpen
from the shortcut menu. ClickOpen
. 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
excalidocker
in action
Installation
To build excalidocker
locally, please follow these steps:
- Install Rust and Cargo if you haven't already. Refer to the official Rust documentation for installation instructions:
- Clone this repository:
git clone https://github.com/etolbakov/excalidocker-rs.git
- 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.