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

On-premises installation home page

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 (the default username and password is structurizr and password - see below for details on how to change this).

On-premises installation dashboard

Usage

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

Security is implemented using Spring Security and, by default, the on-premises installation defines the set of users in a file called structurizr.users in the Structurizr data directory (passwords are hashed using bcrypt). 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).

You can also modify the WEB-INF/applicationContext-authentication.xml file inside the wev application to use another authentication provider, such as one that integrates with a database, LDAP server, etc. See the Spring Security reference guide for more information.

Single-sign on with mechanisms such as OAuth is not supported at this time.

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.

If you have customised the security configuration, be sure to copy this to the updated installation too.

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