Getting started with Structurizr Lite
Tags: architecture, productivity, c4model
Published: 2021-06-23 16:02:28

---
title: Getting started with Structurizr Lite
published: true
description:
tags: #architecture #productivity #c4model
//cover_image: https://direct_url_to_image.jpg
---

[Structurizr Lite](https://structurizr.com/help/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](https://dev.to/simonbrown/diagrams-as-code-2-0-82k) in a previous post; a textual language specifically designed to support software architecture and the [C4 model](https://c4model.com). 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
    }
    
}
```

You can find more about the Structurizr DSL at [https://github.com/structurizr/dsl](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
```

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
```

## 4. View the diagram

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

![Structurizr Lite - diagram](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/3ykus0m4p7m01bghbptb.png)

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)
```

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
    }
    
}
```

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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/9s29xtb2nzrxwuy06ia6.png)

## 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!