Diagram as code - introduction

Diagram as code - introduction

Since my homelab is expanding, I came up with the idea that maybe it is time to start documenting the solutions I am building so that I do not have to keep everything in my head. I’m terrible at drawing, so discovering Diagram as Code was a the perfect match.

What is Diagram as Code?

It’s a tool written in Python, that lets you easily create neat looking diagrams, especially good for prototyping architecture or any other IT-related work.

Why you need it?

The main advantage of that solution is that it allows you to track every little change - as everything is written with simple Python script. Then you just push it to your Git repository, and from that point on, you have the entire history. Besides, it has a large number of icons, so you do not have to look around for a specific SVG file on the internet.

How to install DaC?

Below instructions are made for macOs users, but I’m linking resources below for other operating systems, so that you could still benefit from this article.

First step is to install Python libraries. I’m using homebrew to manage installed packages.

brew install python3

Then we need to install Graphviz, which is a visualization software. What that package does is to produce a final diagram image as a png file.

brew install graphviz

We need to also install diagrams module.

First, create a folder where you will store your diagrams.

Then we need to set up a virtual environment so that we can install the diagrams module.

python3 -m venv ./env
source ./env/bin/activate

then run pip3 install diagrams

I would also suggest initiating a Git repository here to track changes using a simple git init.

You should be now ready to go!

Diagram as Code example

As I mentioned in the beginning, I wanted to document my local network architecture. This is a sample of the code I created.

You can copy and paste it to your file and see the outcome. 

Don’t forget to save your file and execute the script with `python3 diagram.py`.

from diagrams import Diagram, Cluster
from diagrams.generic.network import Router, Switch
from diagrams.onprem.proxmox import ProxmoxVE
from diagrams.onprem.compute import Server
from diagrams.onprem.database import Postgresql
from diagrams.onprem.groupware import Nextcloud
from diagrams.onprem.client import Client
from diagrams.generic.os import Ubuntu

with Diagram("Home network", show=True, direction="TB"):
    router = Router("router")
    switch = Switch("switch")
    tv = Client("tv")
    xbox = Client("xbox")
    
    with Cluster("Proxmox"):
        proxmox = ProxmoxVE("pve-1")
        proxmox - [Server("home-assistant"),
                  Postgresql("postgresql"),
                  Nextcloud("next-cloud"),
                  Ubuntu("ws-2")]

    router << proxmox
    router << switch
    switch << tv
    switch << xbox

After running in terminal python3 diagram.py a png file will be created in your directory. Mine diagram looks like that:

Conclusion

In this article, I briefly described how you can create any sort of architectural diagram, that is easy to maintain and track history. That was just an introduction. Feel free to explore the topic and adjust the options to your needs. You can find detailed documentation below.

References:

References:
https://diagrams.mingrammer.com/