Documentation with Structurizr

Creating documentation can be a challenging task, and it can be especially difficult when using tools like Structurizr that require a certain level of technical proficiency. But you can make this process easier and more accessible by doing things like hosting the documentation locally. Local hosting gives you more control over the documentation process and makes sure that all team members can get to it easily. This also makes it easier for people to work together since they can quickly and easily look at the documentation and add to it. As the team grows and expands, Structurizr documents can be migrated either to the cloud or to on-premises hosting.

I have developed a Helm chart that enables you to host Structurizr on your local machine, providing you with the freedom to select the hosting option that best meets your requirements, be it security or ease of use. Furthermore, the Helm chart allows for seamless management and deployment of Structurizr within your own infrastructure.

First we need a place to host the helm chart. This will be easily accomplished with GitHub Actions and Pages. Follow the official instructions to get a Helm repository hosted on your GitHub Repo. To update the helm chart that is hosted in the repository, the version of the chart must be updated in the main Chart.yaml file. This will create a release and will be added to the index.yaml that is generated for each GitHub Pages release.

To use the chart, you can add:

helm repo add scry https://garunski-co.github.io/scry-helm-charts/

Or you can specify the repo through a flag:

helm install --set localDirectory="/FULL PATH TO THE FOLDER" --set ingress.host="diagrams.local.scryapp.website" --repo https://garunski-co.github.io/scry-helm-charts/ structurizr structurizr-local

Or with an upgrade:

    helm upgrade -i --set localDirectory="/FULL PATH TO THE FOLDER" --set ingress.host="diagrams.local.scryapp.website" --repo https://garunski-co.github.io/scry-helm-charts/ structurizr structurizr-local

The localDirectory must be a fully qualified path to the folder with the Structurizr workspace.dsl. For the ingress.host, I have configured *.local.scryapp.website to point to 127.0.0.1. This is something that I configured through the infrastructure project and had it automatically applied through the GitHub action automation. While I do not advise this, the same functionality is also accomplishable with the various free online options like nip.io and other services that are similar. The local setup is based on Rancher Desktop with Traefik turned on.

Structurizr is a great tool for creating diagrams that can be easily shared with stakeholders, and it also allows you to track changes to your architecture over time. Using Traefik with Rancher Desktop also gives you a strong local infrastructure for deploying and managing your apps. Next, I will be using Structurizr to document the high level architecture, generate some architectural decisions, and create diagrams for ease of communication.