On-premises installation

The on-premises installation (the "Application") is a standalone version of Structurizr that can be run locally on your own server, and includes the majority of the features found in the cloud version. The key difference is the security model. Where workspaces on the cloud service are private by default, workspaces on the on-premises installation are open by default.

Please see the pricing page for pricing and to see the difference in feature set.

Licensing and download process

The Application is licensed, not sold, to you by Structurizr Limited for use strictly in accordance with the terms of the End User License Agreement at the bottom of this page. By licensing the Application, Structurizr Limited grants you a license to install and use the Application on your own server. Free licenses are granted on a perpetual basis, with some features unavailable. Paid licenses are also granted on a perpetual license, although you will only have access to software updates for the duration of a valid subscription.

Each on-premises license will be associated with a user account on structurizr.com, so you will need to sign up for a free account before purchasing. After purchase, the license key and downloads of the on-premises installation are available on a self-service basis, from your structurizr.com dashboard, using the On-premises installation link.

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. Please note that you must have already purchased a license for the on-premises installation or have started a free trial. 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 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}

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.

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:

4.2.1 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. Delete the existing ROOT directory if it exists.

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

After starting the Apache Tomcat server, you should be able to navigate to http://localhost:8080 in your browser.

Authentication

There are three variants of the on-premises installation that you can download, each with different authentication methods.

1. Form-based login, with a local file-based user store (free and paid)

This variant is configured to use a form-based login (username and password), with the set of users stored in a file called structurizr.users in the Structurizr data directory (passwords are hashed using bcrypt). A user with the username of structurizr and password of password is created by default. You can add, remove or modify users as needed. Each line in this file should be in the following format:

{username}={hashed password}

A simple utility page is provided to calculate a bcrypt hashed password at {structurizr.url}/bcrypt/{password} (e.g. http://localhost:8080/bcrypt/password).

2. Form-based login, with integration to your LDAP server (paid only)

Integration with your LDAP server is also possible by downloading the LDAP variant of the on-premises installation. To configure your LDAP integration, place a copy of the WEB-INF/applicationContext-security-ldap-configuration.xml file into your Structurizr data directory, renamed to ldap.xml, and modify it as needed. Some of our customers have successfully integrated the on-premises installation with FreeIPA and Microsoft Active Directory (via the LDAP binding). If you make any changes to the LDAP configuration, you will need to restart the on-premises installation.

See LDAP server for details on how to configure LDAP.

3. Single sign-on via SAML 2.0 (paid only)

Single sign-on is possible via SAML 2.0 integration with your Identity Provider. Please note that this has only been tested against Auth0 and Microsoft Azure Active Directory so far. After downloading the SAML variant of the on-premises installation, there are four things that need to be done.

  1. Register the Structurizr on-premises application with your Identity Provider. When doing this, you will need a "Reply URL", which is of the form {structurizr.url}/saml/SSO (e.g. http://localhost:8080/saml/SSO).
  2. The structurizr.url property in the structurizr.properties file should be set to the URL where Structurizr is installed (e.g. http://localhost:8080).
  3. The structurizr.saml.entityId property in the structurizr.properties file should be set to the SAML Entity ID, which is provided by your Identity Provider.
  4. A copy of your Identity Provider's SAML metadata (XML format) should be saved to a file called saml-idp-metadata.xml in your Structurizr data directory.

If you make any changes to the SAML configuration, you will need to restart the on-premises installation.

Authorisation and role-based access to workspaces

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) 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 ... label associated with a workspace to specify the set of users or roles who should have read-only or read-write access. You can also configure the set of users via the Structurizr for Java and .NET client libraries.

Updates

There is no auto-update mechanism, so new versions of the Structurizr on-premises installation need to be applied manually. 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, download a new version of the .war file, overwrite the existing version and restart your web/application server.

Configuration

The following parameters can be specified for an on-premises installation, most of which can be provided as environment variables, JVM system properties, or as properties in the structurizr.properties file.

Parameter Environment variable JVM system property structurizr.properties
Data directory
The path to the directory on disk where Structurizr data should be stored.
STRUCTURIZR_DATA_DIRECTORY structurizr.dataDirectory (not applicable)
URL
If the Structurizr dashboard is reporting an incorrect URL, which may happen if SSL termination is being handled upstream, this property can be used to override the URL.
STRUCTURIZR_URL structurizr.url structurizr.url
Server-side encryption passphrase
By default, workspace data is stored as plaintext on disk. Setting this property will enable server-side encryption. For better security (and to keep the encryption passphrase away from the encrypted files), we recommend specifying this property as an environment variable or a JVM system property, rather than putting this in the structurizr.properties file. You may need to patch your Java installation with the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files for encryption to work.
STRUCTURIZR_ENCRYPTION structurizr.encryption structurizr.encryption
Admin users and/or roles
By default, any authenticated user can create workspaces. If you would like to restrict who can create workspaces, set this property to a comma-separated list of usernames or roles that should have "admin" access.
STRUCTURIZR_ADMIN structurizr.admin structurizr.admin
PlantUML server URL
The URL of a PlantUML installation (e.g. http://plantuml.com/plantuml).
STRUCTURIZR_PLANTUML structurizr.plantuml structurizr.plantuml
mermaid server URL
The URL of a mermaid live editor installation (e.g. https://mermaidjs.github.io/mermaid-live-editor).
STRUCTURIZR_MERMAID structurizr.mermaid structurizr.mermaid

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. Some of our customers 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 installation on the public cloud, please ensure that access is suitably restricted.

Can I install the on-premises version more than once?

No, the license covers a single installation.

Can the on-premises installation be clustered for high availability?

No, for deployment simplicity, the on-premises installation has been designed to run on a single server.

Does the on-premises installation require an Internet connection?

No, the on-premises installation runs completely disconnected from the Internet. Furthermore, it doesn't make any requests to the Internet if there is an Internet connection (e.g. to check for updates).

End User License Agreement

License

Structurizr Limited grants you a revocable, non-exclusive, non-transferable, limited license to download, install, evaluate and use the Application strictly in accordance with the terms of this Agreement.

Restrictions

You agree not to, and you will not permit others to:

  • license, sell, rent, lease, assign, distribute, transmit, host, outsource, disclose or otherwise commercially exploit the Application or make the Application available to any third party.

  • modify, make derivative works of, disassemble, decrypt, reverse compile or reverse engineer any part of the Application.

  • remove, alter or obscure any proprietary notice (including any notice of copyright or trademark) of Structurizr Limited or its affiliates, partners, suppliers or the licensors of the Application.

Intellectual Property

The Application, including without limitation all copyrights, patents, trademarks, trade secrets and other intellectual property rights are, and shall remain, the sole and exclusive property of Structurizr Limited.

Modifications to Application

Structurizr Limited reserves the right to modify, suspend or discontinue, temporarily or permanently, the Application or any service to which it connects, with or without notice and without liability to you.

Updates to Application

Structurizr Limited may from time to time provide enhancements or improvements to the features/functionality of the Application, which may include patches, bug fixes, updates, upgrades and other modifications ("Updates").

Updates may modify or delete certain features and/or functionalities of the Application. You agree that Structurizr Limited has no obligation to (i) provide any Updates, or (ii) continue to provide or enable any particular features and/or functionalities of the Application to you.

You further agree that all Updates will be (i) deemed to constitute an integral part of the Application, and (ii) subject to the terms and conditions of this Agreement.

Updates will only be made available for the duration specified in your license key.

Content

The Application allows you to post, link, store, share and otherwise make available certain information, text, graphics, videos, or other material ("Content"). You are responsible for the Content that you post to the Application, including its legality, reliability, and appropriateness.

Third-Party Services

The Application may display, include or make available third-party content (including data, information, applications and other products services) or provide links to third-party websites or services ("Third-Party Services").

You acknowledge and agree that Structurizr Limited shall not be responsible for any Third-Party Services, including their accuracy, completeness, timeliness, validity, copyright compliance, legality, decency, quality or any other aspect thereof. Structurizr Limited does not assume and shall not have any liability or responsibility to you or any other person or entity for any Third-Party Services.

Third-Party Services and links thereto are provided solely as a convenience to you and you access and use them entirely at your own risk and subject to such third parties' terms and conditions.

Term and Termination

This Agreement shall remain in effect until terminated by you or Structurizr Limited.

Structurizr Limited may, in its sole discretion, at any time and for any or no reason, suspend or terminate this Agreement with or without prior notice.

This Agreement will terminate immediately, without prior notice from Structurizr Limited, in the event that you fail to comply with any provision of this Agreement. You may also terminate this Agreement by deleting the Application and all copies thereof from your mobile device or from your computer.

Upon termination of this Agreement, you shall cease all use of the Application and delete all copies of the Application from your mobile device or from your computer.

Termination of this Agreement will not limit any of Structurizr Limited's rights or remedies at law or in equity in case of breach by you (during the term of this Agreement) of any of your obligations under the present Agreement.

Indemnification

You agree to indemnify and hold Structurizr Limited and its parents, subsidiaries, affiliates, officers, employees, agents, partners and licensors (if any) harmless from any claim or demand, including reasonable attorneys' fees, due to or arising out of your: (a) use of the Application; (b) violation of this Agreement or any law or regulation; or (c) violation of any right of a third party.

No Warranties

The Application is provided to you "AS IS" and "AS AVAILABLE" and with all faults and defects without warranty of any kind. To the maximum extent permitted under applicable law, Structurizr Limited, on its own behalf and on behalf of its affiliates and its and their respective licensors and service providers, expressly disclaims all warranties, whether express, implied, statutory or otherwise, with respect to the Application, including all implied warranties of merchantability, fitness for a particular purpose, title and non-infringement, and warranties that may arise out of course of dealing, course of performance, usage or trade practice. Without limitation to the foregoing, Structurizr Limited provides no warranty or undertaking, and makes no representation of any kind that the Application will meet your requirements, achieve any intended results, be compatible or work with any other software, applications, systems or services, operate without interruption, meet any performance or reliability standards or be error free or that any errors or defects can or will be corrected.

Without limiting the foregoing, neither Structurizr Limited nor any Structurizr Limited's provider makes any representation or warranty of any kind, express or implied: (i) as to the operation or availability of the Application, or the information, content, and materials or products included thereon; (ii) that the Application will be uninterrupted or error-free; (iii) as to the accuracy, reliability, or currency of any information or content provided through the Application; or (iv) that the Application, its servers, the content, or e-mails sent from or on behalf of Structurizr Limited are free of viruses, scripts, trojan horses, worms, malware, timebombs or other harmful components.

Some jurisdictions do not allow the exclusion of or limitations on implied warranties or the limitations on the applicable statutory rights of a consumer, so some or all of the above exclusions and limitations may not apply to you.

Limitation of Liability

Notwithstanding any damages that you might incur, the entire liability of Structurizr Limited and any of its suppliers under any provision of this Agreement and your exclusive remedy for all of the foregoing shall be limited to the amount actually paid by you for the Application.

To the maximum extent permitted by applicable law, in no event shall Structurizr Limited or its suppliers be liable for any special, incidental, indirect, or consequential damages whatsoever (including, but not limited to, damages for loss of profits, for loss of data or other information, for business interruption, for personal injury, for loss of privacy arising out of or in any way related to the use of or inability to use the Application, third-party software and/or third-party hardware used with the Application, or otherwise in connection with any provision of this Agreement), even if Structurizr Limited or any supplier has been advised of the possibility of such damages and even if the remedy fails of its essential purpose.

Some states/jurisdictions do not allow the exclusion or limitation of incidental or consequential damages, so the above limitation or exclusion may not apply to you.

Severability

If any provision of this Agreement is held to be unenforceable or invalid, such provision will be changed and interpreted to accomplish the objectives of such provision to the greatest extent possible under applicable law and the remaining provisions will continue in full force and effect.

Waiver

Except as provided herein, the failure to exercise a right or to require performance of an obligation under this Agreement shall not effect a party's ability to exercise such right or require such performance at any time thereafter nor shall be the waiver of a breach constitute waiver of any subsequent breach.

Amendments to this Agreement

Structurizr Limited reserves the right, at its sole discretion, to modify or replace this Agreement at any time. If a revision is material we will provide at least 30 days' notice prior to any new terms taking effect. What constitutes a material change will be determined at our sole discretion.

By continuing to access or use our Application after any revisions become effective, you agree to be bound by the revised terms. If you do not agree to the new terms, you are no longer authorized to use the Application.

Governing Law

The laws of Jersey, excluding its conflicts of law rules, shall govern this Agreement and your use of the Application. Your use of the Application may also be subject to other local, state, national, or international laws.

Contact Information

If you have any questions about this Agreement, please contact us.

Entire Agreement

The Agreement constitutes the entire agreement between you and Structurizr Limited regarding your use of the Application and supersedes all prior and contemporaneous written or oral agreements between you and Structurizr Limited.

You may be subject to additional terms and conditions that apply when you use or purchase other Structurizr Limited's services, which Structurizr Limited will provide to you at the time of such use or purchase.