On-premises installation

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. 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 basic 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:

  • Java 8 or Java 11
  • Apache Tomcat 8.x or 9.x

4.2.1 Delete the ROOT web application

Delete the TOMCAT_HOME/webapps/ROOT.war file and the TOMCAT_HOME/webapps/ROOT directory if they exist.


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


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


4.2.4 Start Apache Tomcat

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.

Diagram reviews and maxPostSize

Some web servers (e.g. Apache Tomcat) restrict the quantity of data that can be sent in a HTTP POST request. If you find that creating diagram reviews fails, you may need to change this configuration. For Apache Tomcat, you can modify the maxPostSize parameter for your connector in the server.xml file (see https://tomcat.apache.org/tomcat-9.0-doc/config/http.html).