On-premises installation

The on-premises installation is a standalone version of Structurizr that can be run locally on your own servers. It includes the majority of the features found in the cloud version (including Structurizr Express) - please see the pricing page for pricing and to see the difference in feature set.

Purchase and download process

The on-premises license will be associated with an 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}

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.

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.

Usage

By default, as an anonymous user (not signed in), you'll have read-only access. To create, delete and modify workspaces, you'll need to be signed in. Using the on-premises installation is much the same as the cloud-based service. You can create a workspace using the "Create a new workspace" link on the dashboard after signing in, and upload your workspace content using the Structurizr client libraries (Java or C#). As the on-premises installation is completely separate from the cloud-based service, no data is sent to our cloud servers.

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

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

2. Form-based login, with integration to your LDAP server

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

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, simply download a new version of the .war file, overwrite the existing version and restart your web/application server.

Pricing and licensing

The on-premises installation is available as a perpetual license, with support and updates included for one year. See the pricing page for more details.

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. We 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 version 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.

Is workspace data encrypted?

No, it is stored as plain text on disk. You can use client-side encryption to encrypt individual workspaces though.

Why doesn't URL reported by the on-premises installation doesn't match the actual URL?

If the Structurizr dashboard is reporting an incorrect URL, which may happen if SSL termination is being handled upstream, you can override this URL in the structurizr.properties file by adding a property called structurizr.url. Don't include the /api portion of the URL when setting this property.

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