On-premises installation

Overview | Getting started | Configuration | Troubleshooting | FAQ
Authentication | LDAP | SAML 2.0 | Authorisation and role-based access | HTTPS | Amazon Web Services S3 | Elasticsearch

The Structurizr on-premises installation is licensed to you by Structurizr Limited for use strictly in accordance with the terms of the End User License Agreement.

structurizr-onpremises.war (build 2828) Docker Hub

Getting started

Here's a brief guide to getting started with the Structurizr on-premises installation.

1. Create the Structurizr data directory

The Structurizr on-premises installation needs to be given access to a directory, where all data will be stored. We'll refer to this directory as the "Structurizr data directory".

2. Starting the Structurizr on-premises installation

The Structurizr on-premises installation is available as a Docker image (recommended) and a Java EE application.

2.1 Docker

Assuming that you have Docker installed, to start the Structurizr on-premises installation, use the following command to pull the image from Docker Hub.

docker pull structurizr/onpremises

Then use the following command to start the Docker container, replacing PATH with the path to your Structurizr data directory:

docker run -it --rm -p 8080:8080 -v PATH:/usr/local/structurizr structurizr/onpremises

For example, if your Structurizr data directory is located at /Users/simon/structurizr, the command would be:

docker run -it --rm -p 8080:8080 -v /Users/simon/structurizr:/usr/local/structurizr structurizr/onpremises

2.2 Java EE

To use the Java EE version, you'll need Java 11+ (required), a web/application server (required, e.g. Apache Tomcat 9.x), and Graphviz (optional; if you want to use automatic layout). 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).

2.2.1 Shutdown Apache Tomcat

Shutdown Apache Tomcat if it's running.

2.2.2 Delete the ROOT web application

Delete the following if they exist:

  • TOMCAT_HOME/webapps/ROOT.war
  • TOMCAT_HOME/webapps/ROOT

2.2.3 Download/copy the on-premises installation file

Download the structurizr-onpremises.war file from the link above, move it to the TOMCAT_HOME/webapps directory, and rename it to ROOT.war (the on-premises installation must be installed as the root web application).

2.2.4 Configuration

You then need to configure the Structurizr data directory location. The easiest way to do this is to set an environment variable named STRUCTURIZR_DATA_DIRECTORY, with a value of the full path to your Structurizr data directory. For example:

export STRUCTURIZR_DATA_DIRECTORY=/Users/simon/structurizr

2.2.5 Start Apache Tomcat

After starting Apache Tomcat (e.g. using the TOMCAT_HOME/bin/startup.sh or TOMCAT_HOME\bin\startup.bat script), you should be able to navigate to http://localhost:8080 in your browser.

Here's a starting point if you would like to build your own Docker image:

FROM tomcat:9.0.65-jre17-temurin-jammy

RUN set -eux; \
	apt-get update; \
	apt-get install -y --no-install-recommends graphviz

ADD structurizr-onpremises.war /usr/local/tomcat/webapps/ROOT.war


CMD ["catalina.sh", "run"]

3. Using the Structurizr on-premises installation

If deployment was successful, navigating to http://localhost:8080 should open the Structurizr on-premises installation. You will see the end user license agreement, which you will need to accept, before the on-premises installation home page is displayed. You can then sign in using the default credentials (structurizr and password).