The on-premises installation is a standalone version of Structurizr that can be run locally on your own servers, providing all of the major features needed to visualise, document and explore your software architecture.
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.
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.
After downloading the on-premises installation, copy the
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.
You then need to add some configuration information.
To do this, create a file called
ROOT.xml in the
with the following content (replacing
... with your license key).
<Context> <Environment name="structurizr/dataDirectory" value="/usr/local/structurizr" type="java.lang.String"/> <Environment name="structurizr/license" value="..." type="java.lang.String"/> </Context>
The parameters being configured in this file are as follows.
structurizr/dataDirectory: The location where Structurizr data will be stored.
structurizr/license: The Structurizr on-premises license key.
structurizr/url: The URL where Structurizr can be accessed (optional; only set this if the Structurizr dashboard is reporting an incorrect URL, which may happen if SSL termination is being handled upstream ... don't include the
/apiportion in the URL).
After starting Apache Tomcat, you should be able to navigate to
http://localhost:8080 in your browser.
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
password - see below for details on how to change this).
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.
Security is implemented using Spring Security
and, by default, the on-premises installation defines the set of users in the
<authentication-manager> <authentication-provider> <user-service> <user name="structurizr" password="password" authorities="ROLE_STRUCTURIZR_USER" /> </user-service> </authentication-provider> </authentication-manager>
You can add, remove or modify users as needed. If you would prefer the passwords to not be stored in plaintext (plaintext is not recommended for a production deployment), you can configure the bcrypt password encoder as follows:
<authentication-manager> <authentication-provider> <password-encoder hash="bcrypt" /> <user-service> <user name="structurizr" password="$2a$06$uM5wM.eJwrPq1RM/gBXRr.d0bfyu9ABxdE56qYbRLSCZzqfR7xHcC" authorities="ROLE_STRUCTURIZR_USER" /> </user-service> </authentication-provider> </authentication-manager>
You can also modify the
WEB-INF/applicationContext-authentication.xml file 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
Authenticated users must be granted the role named
ROLE_STRUCTURIZR_USER, which allows users to create, delete and modify workspaces.
The mapping between user roles and URL patterns is configured in the
although these shouldn't need to be modified.
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, with the ROLE_STRUCTURIZR_USER role) 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 public/private label to specify the set of users or roles who should have read-only or read-write access.
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?
The license covers a single installation, but Structurizr can be installed multiple times for high availability and redundancy purposes.
Is workspace data encrypted?
No, it is stored as plain text on disk.