Convert your docker-compose into excalidraw

Overview

excalidocker-rs

GitHub release (latest by date) Docker Pulls License Maintenance

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

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

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

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

mac-warning

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

excalidocker-demo

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

Comments
  • Suggestions :)

    Suggestions :)

    This is just brilliant, thank you!

    I saw your roadmap, FWIW I would put at #1 the Docker artefact - being able to run this without installing/building would make it super useful. It could then also be used in things like github actions for auto documentation as well.

    Other ideas:

    • [x] Echo the output path used; I was a bit confused when I ran it and nothing seemed to happen - I had to RTFM to find out it went to /tmp by default
    • [x] Add ability to specify font used
    • [x] Add toggle for displaying dependencies
    • [x] Use arrows instead of lines as connectors so that when boxes are moved the connections remain with them
    opened by rmoff 4
  • In github-action release step replace set-output with GITHUB_OUTPUT

    In github-action release step replace set-output with GITHUB_OUTPUT

    The following line causes warnings https://github.com/etolbakov/excalidocker-rs/blob/4e64a2ab784261f80e2cc13da523e1930139eac9/.github/workflows/release.yml#L234

    The `set-output` command is deprecated and will be disabled soon. Please upgrade to using Environment Files. For more information see: https://github.blog/changelog/2022-10-11-github-actions-deprecating-save-state-and-set-output-commands/
    

    As per Github recommendation a workflow using save-state or set-output like the following

    - name: Save state
    run: echo "::save-state name={name}::{value}"
    
    - name: Set output
    run: echo "::set-output name={name}::{value}"
    

    should be updated to write to the new GITHUB_STATE and GITHUB_OUTPUT environment files:

    - name: Save state
    run: echo "{name}={value}" >> $GITHUB_STATE
    
    - name: Set output
    run: echo "{name}={value}" >> $GITHUB_OUTPUT
    

    source

    enhancement help wanted good first issue 
    opened by etolbakov 1
  • thread 'main' panicked at 'index out of bounds: the len is 1 but the index is 1'

    thread 'main' panicked at 'index out of bounds: the len is 1 but the index is 1'

    ./excalidocker --input-path ~/git/lakeFS/deployments/compose/docker-compose.yml
    thread 'main' panicked at 'index out of bounds: the len is 1 but the index is 1', src/main.rs:159:38
    note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
    

    Input file is this one

    (excalidocker worked fine with this one)

    opened by rmoff 1
  • feat(core): add initial edge-type support

    feat(core): add initial edge-type support

    This PR addresses https://github.com/etolbakov/excalidocker-rs/issues/16 Potentially we might need to add edge configuration for connecting arrows as well.

    opened by etolbakov 0
  • Edge type support

    Edge type support

    Excalidraw supports 2 edge types: sharp and round. We need to add support in the config. Scope of change:

    enhancement help wanted good first issue 
    opened by etolbakov 0
  • Support `extends` fully

    Support `extends` fully

    For example:

    docker run --rm -e INPUT_PATH=https://raw.githubusercontent.com/treeverse/lakeFS-samples/main/standalone/airflow-dag-example/docker-compose.yml etolbakov/excalidocker:latest > tmp.excalidraw
    

    The generated diagram doesn't show the ports exposed by the services that are extended from a parent Docker Compose, only those in the Docker Compose specified

    CleanShot_2023-06-14_at_11 06 55@2x

    Also odd how they're all rendered at an increasing vertical offset, not sure if this is by design but keeping it level would be useful too

    opened by rmoff 1
  • support docker-compose `network`

    support docker-compose `network`

    At the moment network is ignored, it will be good to add network support. At the moment there are 2 options

    • have a single colour for all services in one network and paste the agenda.
    • wrap all services in one network in a big rectangle with the text that shows network name
    opened by etolbakov 0
  • improve the existing solution with multiple `HashMap` structs

    improve the existing solution with multiple `HashMap` structs

    It feels that these number of structs is excessive: https://github.com/etolbakov/excalidocker-rs/blob/99459d082a0b413cd0994094f4fcf80f4320ab2d/src/main.rs#L143-L147 During the development I came up with the most straightforward solution and didn't have much time to reflect on the optimal one, but maybe we can reduce the number of HashMap structs.

    enhancement help wanted good first issue 
    opened by etolbakov 0
  • Fix linter issues

    Fix linter issues

    The code is in relatively untidy state. Commands

    cargo check --all-features
    cargo fmt -- --check
    cargo clippy -- -D warnings	
    

    produce a lot of actions (unused code, not optimal methods etc). This needs to be addressed

    enhancement help wanted good first issue 
    opened by etolbakov 0
Releases(0.1.5)
Owner
Eugene Tolbakov
Eugene Tolbakov
It's like "docker stats" but with beautiful, real-time charts into your terminal. 📊

?? ds - Real-time Stats with Terminal Charts Visualize container stats with beautiful, real-time charts directly in your terminal. Why ds? Missing Cha

Rafael R. Camargo 5 Oct 3, 2023
Docker daemon API in Rust

Bollard: an asynchronous rust client library for the docker API Bollard leverages the latest Hyper and Tokio improvements for an asynchronous API cont

Niel Drummond 439 Jan 3, 2023
Docker containers on a synthetic network. Run applications in a context that lets you manipulate their network conditions.

Synthetic Network Docker containers on a synthetic network. Run applications in a context that lets you manipulate their network conditions. Dependenc

Daily 58 Dec 15, 2022
A tool for defining and running multi-container Docker applications

Ikki Ikki is a tool for defining and running multi-container Docker applications. It is similar to Docker Compose but comes with some differences. Goa

Kirill Vasiltsov 39 Dec 21, 2022
Implementation of the Docker Registry HTTP API V2 in Rust, that can act as a proxy to other registries

Docker registry server and proxy (I'm bad at creating catchy names, but this one is good enough.) This project aims to implement a Docker Registry HTT

l4p1n (Mathias B.) 2 Dec 30, 2022
Convert TeleInfo frames from a Linky meter's serial port to Home Assistant-compatible MQTT messages.

teleinfo2mqtt-rs Convert TeleInfo frames from a Linky meter's serial port to Home Assistant-compatible MQTT messages. Overview sequenceDiagram par

Stanislas 4 Mar 19, 2024
Acts as an IRC server and a nostr client. Connect with your IRC client using your nostr private key as the password.

nostr-irc Acts as an IRC server and a nostr client. Connect with your IRC client using your nostr private key as the password. Experimental code, use

null 11 Dec 26, 2022
Transforms UDP stream into (fake) TCP streams that can go through Layer 3 & Layer 4 (NAPT) firewalls/NATs.

Phantun A lightweight and fast UDP to TCP obfuscator. Table of Contents Phantun Latest release Overview Usage 1. Enable Kernel IP forwarding 2. Add re

Datong Sun 782 Dec 30, 2022
A rough transliteration of ls and grep from Toybox into Rust

Toybox to Rust (transliteration) A rough port of ls and grep from Toybox by trying to follow the original structure of the C code. Building Your syste

null 0 Dec 25, 2021
First iteration of gluing our modules together into a PoA private network

First iteration of gluing our modules together into a PoA private network

null 7 Oct 29, 2022
Imagine your SSH server only listens on an IPv6 address, and where the last 6 digits are changing every 30 seconds as a TOTP code...

tosh Imagine your SSH server only listens on an IPv6 address, and where the last 6 digits are changing every 30 seconds as a TOTP code... Inspired fro

Mark Vainomaa 409 Oct 23, 2022
A tool to aid in self-hosting. Expose local services on your computer, via a public IPv4 address.

innisfree A tool to aid in self-hosting. Expose local services on your computer, via a public IPv4 address. Why? Most of the data I maintain is local,

Conor Schaefer 7 Mar 19, 2022
Obtain (wildcard) certificates from let's encrypt using dns-01 without the need for API access to your DNS provider.

Agnos Presentation Agnos is a single-binary program allowing you to easily obtain certificates (including wildcards) from Let's Encrypt using DNS-01 c

Arthur Carcano 246 Dec 20, 2022
Automatically updates your Cloudflare DNS records for specific zones. Especially useful if you have dynamic IP address

Cloudflare DNS updater What does it do? Cloudflare DNS updater updates specified dns records for specified zones effortlessly and automatically. It wa

Niko Huuskonen 8 Aug 30, 2022
Userspace libpcap-based tool to mirror your dns traffic

DNS traffic mirroring tool (dns-mirror) Description Userspace libpcap-based tool. dns-mirror sniffs dns packets on the given interface and proxies it

Timofey 1 Mar 15, 2022
[WIP] wadachi scrapes your GitHub Activities.

wadachi wadachi scrapes your GitHub Activities. Usage | Examples | Docs This library is currently under development. Dependencies [dependencies] wadac

Takayuki Maeda 2 Mar 18, 2022
Test the interception/filter of UDP 53 of your local networks or hotspots.

udp53_lookup Test the interception/filter of UDP 53 of your local networks or hotspots. Inspired by BennyThink/UDP53-Filter-Type . What's the purpose?

null 1 Dec 6, 2021
🔌 A curseforge proxy server, keeping your API key safe and sound.

?? CFPROXY - The curseforge proxy server Curseforge has locked down their API and now restricts access without authentification. This spells trouble f

null 6 Nov 7, 2022
🐘 Query your Postgres Database directly from the Browser.

Postgres Browser Proxy Query your Postgres Database directly from the Browser. Video: https://youtu.be/ohr9gBPC3cE Download the latest binaries: https

Yannick 6 Jan 7, 2023