On-premises installation

The Structurizr on-premises installation is a standalone version of Structurizr that can be run locally on your own server, and includes the majority of the features found in the cloud service. The key difference is the security model. Where workspaces on the cloud service are private by default, workspaces on the on-premises installation are open by default.

Please see the pricing page for pricing and to see the difference in feature set.

Licensing and download process

The Application is licensed, not sold, to you by Structurizr Limited for use strictly in accordance with the terms of the End User License Agreement. By licensing the Application, Structurizr Limited grants you a license to install and use the Application on your own server. Free licenses are granted on a perpetual basis, with some features unavailable. Paid licenses are also granted on a perpetual license, although you will only have access to software updates for the duration of a valid subscription.

Each on-premises license will be associated with a user account on structurizr.com, so you will need to sign up for a free account before purchasing. After purchase, the license key and downloads of the on-premises installation are available on a self-service basis, from your structurizr.com dashboard, using the On-premises installation link.

Deployment

The on-premises installation is a Java EE web application, packaged as a .war file for deployment into any compatible Java EE server, such as Apache Tomcat.

1 Download

The on-premises installation is available to download from your dashboard using the On-premises installation link. Please note that you must have already purchased a license for the on-premises installation or have started a free trial. The file you download will be named structurizr-onpremises-xxxx.war, where xxxx refers to the build number.

2 Create the Structurizr data directory

The Structurizr on-premises installation stores all data on the file system, so you first need to create a directory somewhere for this purpose. We'll refer to this directory as the "Structurizr data directory".

3 Create a configuration file

Inside the Structurizr data directory, create a file called structurizr.properties containing your license key as follows, which is also available by clicking On-premises installation link on your dashboard.

structurizr.license={license key}

For example:

structurizr.license=LUKuPlhSQaA5yULRYPKtL5kCO7H...

4 Deployment

There are a number of ways to deployment the Structurizr on-premises web application, for example using a Docker container or a standalone Apache Tomcat server.


4.1 Deployment via a Docker container

For the purposes of testing and trialling the on-premises installation, deployment via a Docker container is probably the most straightforward. Assuming that you have Docker installed and running, run the following command, replacing /path/to/structurizr-onpremises-xxxx.war and /path/to/structurizrDataDirectory as appropriate:

docker run -it --rm -p 8080:8080 -v /path/to/structurizr-onpremises-xxxx.war:/usr/local/tomcat/webapps/ROOT.war -v /path/to/dataDirectory:/usr/local/structurizr structurizr/tomcat

After starting the Docker container, you should be able to navigate to http://localhost:8080 in your browser. Please note that the structurizr/tomcat Docker image is for testing purposes only, and is NOT recommended for production use. We recommend that you create your own secured/hardened image.


4.2 Deployment into a standalone Apache Tomcat server

Here are some basic instructions that assume you are using a freshly downloaded version of Apache Tomcat. In the instructions that follow, TOMCAT_HOME refers to the location of the Apache Tomcat installation.

The pre-requisites for deploying Structurizr into Apache Tomcat are as follows:

4.2.1 Copy the WAR file

Copy the structurizr-onpremises-xxxx.war file to TOMCAT_HOME/webapps/ROOT.war. The on-premises installation must be installed as the root web application. Delete the existing ROOT directory if it exists.

4.2.2 Configuration

You then need to tell Structurizr the location of the data directory. One way to do this is to create a file called ROOT.xml in the TOMCAT_HOME/conf/Catalina/localhost directory with the following content, replacing /path/to/structurizrDataDirectory as appropriate.

<Context>
    <Environment name="structurizr/dataDirectory" value="/path/to/structurizrDataDirectory" type="java.lang.String"/>
</Context>

Alternatively, you can specify the Structurizr data directory via an environment variable, called STRUCTURIZR_DATA_DIRECTORY, or a JVM system property called structurizr.dataDirectory.

After starting the Apache Tomcat server, you should be able to navigate to http://localhost:8080 in your browser.


Reverse proxies

If you have installed the on-premises installation behind a reverse proxy, be aware that some reverse proxies will add additional HTTP headers, which may cause issues such as the embedded diagram viewer/editor not working.

Authentication

There are three variants of the on-premises installation that you can download, each with different authentication methods.

1. Form-based login, with a local file-based user store (free and paid)

This variant is configured to use a form-based login (username and password), with the set of users stored in a file called structurizr.users in the Structurizr data directory (passwords are hashed using bcrypt). A user with the username of structurizr and password of password is created by default. You can add, remove or modify users as needed. Each line in this file should be in the following format:

{username}={hashed password}

A simple utility page is provided to calculate a bcrypt hashed password at {structurizr.url}/bcrypt/{password} (e.g. http://localhost:8080/bcrypt/password).

It is also possible to configure a comma separated list of roles for every user, in a file called structurizr.roles, again in the Structurizr data directory. Each line in this file should be in the following format:

{username}={role1},{role2},{role3}

2. Form-based login, with integration to your LDAP server (paid only)

Integration with your LDAP server is also possible by downloading the LDAP variant of the on-premises installation. To configure your LDAP integration, place a copy of the WEB-INF/applicationContext-security-ldap-configuration.xml file into your Structurizr data directory, renamed to ldap.xml, and modify it as needed. Some of our customers have successfully integrated the on-premises installation with FreeIPA and Microsoft Active Directory (via the LDAP binding). If you make any changes to the LDAP configuration, you will need to restart the on-premises installation.

See LDAP server for details on how to configure LDAP.

3. Single sign-on via SAML 2.0 (paid only)

Single sign-on is possible via SAML 2.0 integration with your Identity Provider. Please note that this has only been tested against Auth0 and Microsoft Azure Active Directory so far. After downloading the SAML variant of the on-premises installation, there are four things that need to be done.

  1. Register the Structurizr on-premises application with your Identity Provider. When doing this, you will need a "Reply URL", which is of the form {structurizr.url}/saml/SSO (e.g. http://localhost:8080/saml/SSO).
  2. The structurizr.url property in the structurizr.properties file should be set to the URL where Structurizr is installed (e.g. http://localhost:8080).
  3. The structurizr.saml.entityId property in the structurizr.properties file should be set to the SAML Entity ID, which is provided by your Identity Provider.
  4. A copy of your Identity Provider's SAML metadata (XML format) should be saved to a file called saml-idp-metadata.xml in your Structurizr data directory.

If you make any changes to the SAML configuration, you will need to restart the on-premises installation.

Authorisation and role-based access to workspaces

By default, all workspaces are accessible by anybody who has access to your Structurizr installation. Anonymous users (not signed in) have read-only access, while authenticated users (signed in) have read-write access.

The security of each workspace is summarised on the dashboard with the following labels:

  • Public (accessible to everybody)
  • Private (accessible only to specified users)

To restrict access to specific workspaces, click the ... label associated with a workspace to specify the set of users or roles who should have read-only or read-write access. You can also configure the set of users via the Structurizr for Java and .NET client libraries.

Updates

There is no auto-update mechanism, so new versions of the Structurizr on-premises installation need to be applied manually. The cloud service and on-premises installation share a common codebase, so any updates made to the cloud service are immediately available in the on-premises installation. To update, download a new version of the .war file, overwrite the existing version and restart your web/application server.

Configuration

The following parameters can be specified for an on-premises installation, most of which can be provided as environment variables, JVM system properties, or as properties in the structurizr.properties file.

Parameter Environment variable JVM system property structurizr.properties
Data directory
The path to the directory on disk where Structurizr data should be stored.
STRUCTURIZR_DATA_DIRECTORY structurizr.dataDirectory (not applicable)
URL
If the Structurizr dashboard is reporting an incorrect URL, which may happen if SSL termination is being handled upstream, this property can be used to override the URL.
STRUCTURIZR_URL structurizr.url structurizr.url
Server-side encryption passphrase
By default, workspace data is stored as plaintext on disk. Setting this property will enable server-side encryption. For better security (and to keep the encryption passphrase away from the encrypted files), we recommend specifying this property as an environment variable or a JVM system property, rather than putting this in the structurizr.properties file. You may need to patch your Java installation with the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files for encryption to work.
STRUCTURIZR_ENCRYPTION structurizr.encryption structurizr.encryption
Admin users and/or roles
By default, any authenticated user can create workspaces. If you would like to restrict who can create workspaces, set this property to a comma-separated list of usernames or roles that should have "admin" access.
STRUCTURIZR_ADMIN structurizr.admin structurizr.admin
PlantUML server URL
The URL of a PlantUML installation (e.g. http://plantuml.com/plantuml).
STRUCTURIZR_PLANTUML structurizr.plantuml structurizr.plantuml
Graphviz integration
Whether the Graphviz integration should be enabled; true or false (default). If you would like to use the Graphviz integration for auto-layout, you will need to install Graphviz on your server (the dot command must be available from the command line).
STRUCTURIZR_GRAPHVIZ structurizr.graphviz structurizr.graphviz

Frequently asked questions

Here are answers to some frequently asked questions. If you don't see an answer you are looking for, please get in touch.

Can the on-premises version of Structurizr be installed on public cloud IaaS and PaaS services?

The on-premises version was designed to run inside a trusted network environment. Some of our customers have successfully installed it on environments such as the public Microsoft Azure cloud, but we do not recommend this. If you really do want to run the on-premises installation on the public cloud, please ensure that access is suitably restricted.

Can I install the on-premises version more than once?

No, the license covers a single installation.

Can the on-premises installation be clustered for high availability?

No, for deployment simplicity, the on-premises installation has been designed to run on a single server.

Does the on-premises installation require an Internet connection?

No, the on-premises installation runs completely disconnected from the Internet. Furthermore, it doesn't make any requests to the Internet if there is an Internet connection (e.g. to check for updates).