Skip to content

Latest commit

 

History

History
146 lines (97 loc) · 5.09 KB

getting-started.md

File metadata and controls

146 lines (97 loc) · 5.09 KB

Getting started

The Structurizr CLI provides tooling to parse Structurizr DSL workspace definitions, upload them to the Structurizr cloud service/on-premises installation, and export diagrams to other formats (e.g. PlantUML, Mermaid, and WebSequenceDiagrams).

1. Download and install the Structurizr CLI

There are a number of ways to download/install the Structurizr CLI.

Local installation

Download the Structurizr CLI from the releases page, and unzip. You will need Java (version 8+) installed, and available to use from your command line (please note that the CLI does not work with Java versions 11.0.0-11.0.3).

Homebrew (MacOS only)

The Structurizr CLI can be installed via Homebrew as follows:

brew install structurizr-cli

And to upgrade:

brew update
brew upgrade structurizr-cli

Scoop (Windows only)

The Structurizr CLI can be installed via Scoop as follows:

scoop bucket add extras
scoop install structurizr-cli

And to upgrade:

scoop update structurizr-cli

Docker, dev containers, etc

The Structurizr CLI can be built into a container, to avoid installing it locally. See leopoldodonnell/structurizr-cli-docker or aidmax/structurizr-cli-docker for some Docker examples. Alternatively, if you're using Visual Studio, take a look at evilpilaf/structurizr-remotecontainer.

Build from source

To build from the source, clone this repo and run the following command:

gradlew build

2. Create a software architecture model with the DSL

Create a new empty file with your favourite text editor, and copy the following text into it.

workspace "Getting Started" "This is a model of my software system." {

    model {
        user = person "User" "A user of my software system."
        softwareSystem = softwareSystem "Software System" "My software system."

        user -> softwareSystem "Uses"
    }

    views {
        systemContext softwareSystem "SystemContext" "An example of a System Context diagram." {
            include *
            autoLayout
        }

        styles {
            element "Software System" {
                background #1168bd
                color #ffffff
            }
            element "Person" {
                shape person
                background #08427b
                color #ffffff
            }
        }
    }
    
}

Save this file into the unzipped CLI directory.

This DSL definition:

  • creates a person named "User"
  • creates a software system named "Software System"
  • creates a relationship between the person and the software system
  • create a System Context view for the software system
  • creates some element styles that will be applied when rendering the diagram

Please note that the Structurizr CLI will create some default views for you if you don't define them yourself in the DSL. See Defaults for more details.

3. Render with Structurizr, or export to other diagram formats

You can now either render your diagrams with the Structurizr cloud service/on-premises installation, or render your diagrams with another tool (e.g. PlantUML, Mermaid, etc).

Upload and render with the Structurizr cloud service/on-premises installation

If you've not done so, follow Structurizr - Getting started to sign up for a free Structurizr account, and create a workspace. To upload your workspace to the Structurizr cloud service/on-premises installation, you will need your workspace ID, API key and secret. See Structurizr - Workspaces for information about finding these.

Open a terminal, and issue the following command to upload the workspace (you should change to the unzipped CLI directory, or have it on your path):

./structurizr.sh push -id WORKSPACE_ID -key KEY -secret SECRET -workspace WORKSPACE_FILE

or

structurizr push -id WORKSPACE_ID -key KEY -secret SECRET -workspace WORKSPACE_FILE
  • WORKSPACE_ID: your workspace ID
  • API_KEY: your API key
  • API_SECRET: your API secret
  • WORKSPACE_FILE: the name of your workspace DSL file

You can now sign in to your Structurizr account, and open the workspace from your dashboard. Your workspace should now contain a diagram like this:

Getting started

Export and render to other diagram formats

Alternatively, you can export the views defined in your DSL workspace definition to a number of other formats, for rendering with other tools. You do not need a Structurizr account to do this. For example, to export the views to PlantUML format:

./structurizr.sh export -workspace WORKSPACE_FILE -format plantuml

or

structurizr  export -workspace WORKSPACE_FILE -format plantuml

This will create one PlantUML definition per view. See export for more details.