On-premises installationOverview | Software architecture | Download | Deployment | Configuration | FAQ | EULA
Authentication | LDAP | SAML 2.0 | Authorisation and role-based access | Amazon Web Services S3 | Elasticsearch
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 Create the Structurizr data directory
The Structurizr on-premises installation stores 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".
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.
2.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. In this scenario, the Structurizr data directory will reside on your local server, while the on-premises installation will run inside Apache Tomcat, which itself will run inside a Docker container.
Assuming that you have Docker installed and running, run the following command, replacing
/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 tomcat:9.0.38-jdk11-openjdk
After starting the Docker container, you should be able to navigate to http://localhost:8080 in your browser. We recommend that you create your own secured/hardened container image for production use.
2.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 9.x
2.2.1 Delete the ROOT web application
TOMCAT_HOME/webapps/ROOT.war file and the
TOMCAT_HOME/webapps/ROOT directory if they exist.
2.2.2 Copy the WAR file
TOMCAT_HOME/webapps/ROOT.war (the on-premises installation must be installed as the root web application)
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
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
2.2.4 Start Apache Tomcat
After starting the Apache Tomcat server, you should be able to navigate to http://localhost:8080 in your browser.
There are several options for running the on-premises installation over HTTPS, including:
- Configure HTTPS in the web/application server hosting the on-premises installation; for example SSL/TLS Configuration How-To for Apache Tomcat.
- Configure HTTPS upstream; for example Load Balancing Apache Tomcat Servers with NGINX Open Source and NGINX Plus, Create an HTTPS listener for your Application Load Balancer, etc.
If, after configuring HTTPS, you find that the on-premises installation is reporting an incorrect HTTP URL, you may need to configure the
structurizr.url property - see On-premises installation - Configuration for details.
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).