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

Download the structurizr-onpremises.war file (you'll need to be signed in).

2 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".

3 Deployment

There are a number of ways to deploy the Structurizr on-premises web application, for example using a Docker container or a standalone Apache Tomcat server.


3.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, although we recommend that you create your own secured/hardened container image for production use. 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/structurizr-onpremises.war and /path/to/structurizrDataDirectory as appropriate:


docker run -it --rm -p 8080:8080 -v /path/to/structurizr-onpremises.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. If deployment was successful 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).


3.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 11 or 17
  • Apache Tomcat 9.x

3.2.1 Shutdown Apache Tomcat

Shutdown Apache Tomcat if it's running.


3.2.2 Delete the ROOT web application

Delete the following if they exist:

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

3.2.3 Copy the on-premises installation file

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


3.2.4 Configuration

You then need to configure the Structurizr data directory location. One way to do this is to create a file called ROOT.xml in the TOMCAT_HOME/conf/Catalina/localhost directory (you may need to create the Catalina and localhost directories) with the following content, replacing /path/to/structurizrDataDirectory with the full path to your Structurizr data directory created in step 2.

<Context>
    <Environment name="structurizr/dataDirectory" value="/path/to/structurizrDataDirectory" type="java.lang.String"/>
</Context>

3.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. If deployment was successful 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).