DEV Community

Simon Brown
Simon Brown

Posted on

Getting started with Structurizr Lite

Structurizr Lite is a free version of Structurizr, packaged as a Docker container, and designed for developers who want to quickly author and/or view software architecture diagrams, documentation, and architecture decision records (ADRs). A software architecture model, views, and documentation (together called a "workspace") can be defined using the Structurizr DSL - what I referred to as Diagrams as code 2.0 in a previous post; a textual language specifically designed to support software architecture and the C4 model. Let's get started.

1. Create a new directory

First we need to create a directory somewhere to store our workspace.

2. Create a workspace.dsl file

Next we need to create a file called workspace.dsl inside that directory, with the following content.

workspace {

    model {
        user = person "User"
        softwareSystem = softwareSystem "Software System"

        user -> softwareSystem "Uses"
    }

    views {
        systemContext softwareSystem "Diagram1" {
            include *
            autoLayout
        }

        theme default
    }

}
Enter fullscreen mode Exit fullscreen mode

You can find more about the Structurizr DSL at https://github.com/structurizr/dsl, but essentially this DSL file says:

  • Create a model with a user and a software system, where the user uses the software system.
  • Create a system context view for the software system, adding the default set of elements, using auto-layout.
  • Use the default theme for styling elements and relationships.

3. Start Structurizr Lite

Assuming that you have Docker installed, you can now start Structurizr Lite with the following commands:

docker pull structurizr/lite
docker run -it --rm -p 8080:8080 -v PATH:/usr/local/structurizr structurizr/lite
Enter fullscreen mode Exit fullscreen mode

Be sure to replace PATH with the full path to the directory created in step 1. For example, if the directory is located at /Users/alice/structurizr, the commands would be:

docker pull structurizr/lite
docker run -it --rm -p 8080:8080 -v /Users/alice/structurizr:/usr/local/structurizr structurizr/lite
Enter fullscreen mode Exit fullscreen mode

4. View the diagram

Open the workspace in a web browser by heading to http://localhost:8080 and you should see your diagram.

Structurizr Lite - diagram

If you make a change to the DSL file and save it, you should see that change immediately reflected when you refresh your web browser.

5. Add some documentation

Let's add some documentation to describe our software system. To do this, create a subdirectory named docs and create a file named 01-context.md inside that subdirectory, with the following content:

## Context

Here is a description of my software system...

![](embed:Diagram1)
Enter fullscreen mode Exit fullscreen mode

Now change the content of the workspace.dsl file to be as follows (notice the addition of the !docs line):

workspace {

    model {
        user = person "User"
        softwareSystem = softwareSystem "Software System" {
            !docs docs
        }

        user -> softwareSystem "Uses"
    }

    views {
        systemContext softwareSystem "Diagram1" {
            include *
            autoLayout
        }

        theme default
    }

}
Enter fullscreen mode Exit fullscreen mode

Save all files, refresh your web browser, and click on the top-left button with the icon that looks like a book. You should now see the Markdown documentation page that we just created, which itself is embedding our existing system context diagram.

Structurizr Lite - documentation

Summary

Structurizr Lite provides a quick and free way to get started with the Structurizr tooling. It supports the full set of C4 model diagrams, along with the ability to publish Markdown/AsciiDoc documentation, and architecture decision records (ADRs). Enjoy!

Discussion (16)

Collapse
dylanmorley profile image
Dylan Morley

Fantastic work on Structurizr Lite @simonbrown . I've used structurizr.com/ before but last night was the first time giving Lite a go, simple and straightforward to get going - everything 'just worked'. Gone are the days where I present photos of illegible scribbles in random boxes - a degree of professionalism achieved with the help of Structurizr! Cheers

Collapse
simonbrown profile image
Simon Brown Author

Thanks, glad you're enjoying it!

Collapse
maephisto666 profile image
Raffaele Briganti

What a nice discovery this Structurizr Lite!

I have been promoting the use of Structurizr in the company where I work and we are finalizing the purchase of the license. The idea is to create the diagrams via Structurizr and use them for our internal documentation as well as for the documentation we publish for our customers.

Actually I thought there was a gap because there was no way the teams can work separately on the diagrams we have at the company level using the license we wanted to buy (3 workspaces), but I genuinely believe that this tool can really help us for the workflow we want to have. So each single team can use the Lite Docker version to preview the changes and then commit those to our git repository: then the automation will build the diagrams (specifically we will generate the SVG files) and will publish them when we have a new release.

The autoLayout will be a challenge: we need to make sure we are able to extract the layout information from the diagrams on the cloud service (where we set the autoLayout to false and we arranged the items manually) and replicate that in the local environment (otherwise when the developers run the Docker container all the boxes will be piled up in the top left corner). But we will find a way...

Just for you to know Simon, I'm a big fan.

Collapse
simonbrown profile image
Simon Brown Author • Edited on

Thanks Raffaele. Regarding layout ... you'll need to export your workspace from the cloud service as a JSON file, and copy this to the Lite data directory (workspace.json) before starting Lite, which will then use that as a basis for diagram layouts. Once you're done editing the DSL, save the workspace, and push the new version of the workspace.json file to the cloud service, to upload everything including the new layout. See structurizr.com/help/lite/workflow for more details.

Collapse
simonbrown profile image
Simon Brown Author

I just wanted to add ... there's now an "auto-sync" feature that will sync your workspace between Structurizr Lite and the cloud service. See structurizr.com/help/lite/sync for details.

Collapse
maephisto666 profile image
Raffaele Briganti

oh my... Thanks Simon, completely missed that. You should think about a newsletter from time to time, because there are many features and many repositories I'm discovering now (e.g. the Docker Lite image which is a game-changer) that I'm afraid I could miss something.

Thread Thread
simonbrown profile image
Simon Brown Author

Following me on Twitter and/or joining the Structurizr Slack group (the link is on the Structurizr help page) will keep you up to date. 👍

Collapse
a30006441 profile image
Dinesh Dharmawardena

I love the tool so far. Are there any plans to make Structurizr Lite open source?

The only feedback I have at this stage is that the Automatic Layout doesn't really do a great job of laying out the elements. There are a few more issues I'd like to raise, just wish it was opensource so that we could see accelerated improvement of this tool

Collapse
simonbrown profile image
Simon Brown Author

Thanks! No plans to make it open source, and I agree with your comment about automatic layout - I don't use it myself. Feel free to raise issues at github.com/structurizr/structurizr....

Collapse
rivale23 profile image
rivale23

Great tool, I just started working with it, if everything goes well, I will ask my company to get the license.
I have a script that will combine different files into a single workspace using include, but when I see the diagram in Structurizr Lite it only shows the workspace in the main file, not the include one, is there a way to fix that?

Collapse
simonbrown profile image
Simon Brown Author

Thanks! It's hard to say without more information - feel free to raise an issue.

Collapse
albinotonnina profile image
Albino Tonnina

Starting to use it in my company and personally I cannot stress enough how happy I am to have stumbled upon the C4 model. I started by watching your presentation on youTube and then read your books. Speaking of diagramming and generally documenting my work, I'll admit I was lost, had no mind framework to rely on. This model is simply and elegantly helping me getting that. Grateful to you Sir.

Collapse
catcodeme profile image
catcodeme

👍👍👍

Collapse
joopaulo_desousa_0e909 profile image
João paulo De Sousa

Simplify amazing!

I would like to know best practices as:

Structures of files/folders
Organization
Insert more icon's
Connects diagrams, example: A container block can expand and link with other diagrams
And anything more tips that you have.

Thanks Simon!

Collapse
vikingexplorer profile image
VikingExplorer

Confused on how this works. I modified the workspace file, and these changes do not show up in the browser at localhost:8080/

Collapse
simonbrown profile image
Simon Brown Author

Feel free to raise an issue.