diff --git a/onpremises/01-quickstart.md b/onpremises/01-quickstart.md
new file mode 100644
index 0000000..9e70120
--- /dev/null
+++ b/onpremises/01-quickstart.md
@@ -0,0 +1,37 @@
+---
+layout: default
+title: Quickstart
+parent: Structurizr on-premises
+nav_order: 1
+permalink: /onpremises/quickstart
+---
+
+# Quickstart
+
+Here's a brief guide to getting started with the Structurizr on-premises installation via the pre-built Docker image,
+and assumes that you have Docker installed.
+
+## 1. Create the Structurizr data directory
+
+The Structurizr on-premises installation needs to be given access to a directory, where all data will be stored.
+We'll refer to this directory as the "Structurizr data directory".
+
+## 2. Start Structurizr on-premises
+
+You can now start the Structurizr on-premises installation with the following commands, replacing `PATH` with the path to your Structurizr data directory:
+
+```
+docker pull structurizr/onpremises
+docker run -it --rm -p 8080:8080 -v PATH:/usr/local/structurizr structurizr/onpremises
+```
+
+For example, if your Structurizr data directory is located at `/Users/simon/structurizr`, the command would be:
+
+```
+docker run -it --rm -p 8080:8080 -v /Users/simon/structurizr:/usr/local/structurizr structurizr/onpremises
+```
+
+## 3. Open your web browser
+
+With the Structurizr on-premises installation running, you can head to [http://localhost:8080](http://localhost:8080) in your web browser, where
+you should see the home page. You can then sign in using the default credentials (`structurizr` and `password`), and start to create workspaces, etc.
\ No newline at end of file
diff --git a/onpremises/02-installation.md b/onpremises/02-installation.md
new file mode 100644
index 0000000..51469a1
--- /dev/null
+++ b/onpremises/02-installation.md
@@ -0,0 +1,80 @@
+---
+layout: default
+title: Installation
+parent: Structurizr on-premises
+nav_order: 2
+permalink: /onpremises/installation
+---
+
+# Installation
+
+The Structurizr on-premises installation is available as [Docker image](#docker) and [a Java EE application](#java-ee).
+
+## Create the Structurizr data directory
+
+The Structurizr on-premises installation needs to be given access to a directory, where all data will be stored.
+We'll refer to this directory as the "Structurizr data directory".
+
+## Docker
+
+Assuming that you have Docker installed, to start the Structurizr on-premises installation, use the following command to pull the image from [Docker Hub](https://hub.docker.com/r/structurizr/onpremises).
+
+```
+docker pull structurizr/onpremises
+```
+
+Then use the following command to start the Docker container, replacing `PATH` with the path to your Structurizr data directory:
+
+```
+docker run -it --rm -p 8080:8080 -v PATH:/usr/local/structurizr structurizr/onpremises
+```
+
+For example, if your Structurizr data directory is located at `/Users/simon/structurizr`, the command would be:
+
+```
+docker run -it --rm -p 8080:8080 -v /Users/simon/structurizr:/usr/local/structurizr structurizr/onpremises
+```
+
+There is a [Dockerfile](https://github.com/structurizr/onpremises/blob/main/Dockerfile) in the GitHub repo that can be used as a starting point if you'd like to build your own Docker image.
+
+## Java EE
+
+To use the Java EE version, you'll need:
+
+- Java 17+ (required)
+- A Java EE compatible web/application server (required, e.g. [Apache Tomcat 9.x](https://tomcat.apache.org/download-90.cgi) ... please note that Tomcat 10.x and other Jakarta EE servers are not supported)
+- [Graphviz](https://graphviz.org/download/) (optional if you want to use automatic layout)
+
+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).
+
+### Shutdown Apache Tomcat
+
+Shutdown Apache Tomcat if it's running.
+
+### Delete the ROOT web application
+
+Delete the following if they exist:
+
+- `TOMCAT_HOME/webapps/ROOT.war`
+- `TOMCAT_HOME/webapps/ROOT`
+
+### Download/copy the on-premises installation file
+
+Download the `structurizr-onpremises.war` file from [https://github.com/structurizr/onpremises/releases](https://github.com/structurizr/onpremises/releases),
+move it to the `TOMCAT_HOME/webapps` directory,
+and rename it to `ROOT.war` (the on-premises installation must be installed as the root web application, and is not designed to work otherwise).
+
+### Configuration
+
+You then need to configure the Structurizr data directory location.
+The easiest way to do this is to set an environment variable named `STRUCTURIZR_DATA_DIRECTORY`,
+with a value of the full path to your Structurizr data directory. For example:
+
+```
+export STRUCTURIZR_DATA_DIRECTORY=/Users/simon/structurizr
+```
+
+### Start Apache Tomcat
+
+After starting Apache Tomcat (e.g. using the `TOMCAT_HOME/bin/startup.sh` or `TOMCAT_HOME\bin\startup.bat` script).
diff --git a/onpremises/03-configuration.md b/onpremises/03-configuration.md
new file mode 100644
index 0000000..5a33d0c
--- /dev/null
+++ b/onpremises/03-configuration.md
@@ -0,0 +1,71 @@
+---
+layout: default
+title: Configuration
+parent: Structurizr on-premises
+nav_order: 3
+permalink: /onpremises/configuration
+---
+
+# Configuration
+
+The on-premises installation has two major configuration points:
+
+1. The location of the Structurizr data directory.
+2. Configuration of the on-premises installation itself via a file named `structurizr.properties` inside the Structurizr data directory.
+
+## Structurizr data directory
+
+The location of the Structurizr data directory can be configured in a number of ways:
+
+- An environment variable named `STRUCTURIZR_DATA_DIRECTORY`
+- A JVM system property named `structurizr.dataDirectory`
+
+If unset, the Structurizr data directory location will default to `/usr/local/structurizr`.
+
+## structurizr.properties
+
+The following parameters can be set in a text file named `structurizr.properties` in your Structurizr data directory.
+Changing these parameters requires a restart of the on-premises installation.
+
+Values can either be static strings, or references to environment variables
+(e.g. `structurizr.redis.password=${REDIS_PASSWORD}`).
+
+| Name | Description |
+|--------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `structurizr.url` | If you are running the on-premises installation behind a load balancer and/or reverse-proxy (e.g. SSL termination is being handled upstream), or the pages served by the on-premises installation don't look right (e.g. styles are not loading, images are oversized, etc), you will likely need to set this property to explicitly tell the on-premises installation the URL you are using to access it. This should be a full URL, such as `https://structurizr.example.com`. |
+| `structurizr.encryption` | 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), you can specify this property as an environment variable (`STRUCTURIZR_ENCRYPTION`) or a JVM system property (`structurizr.encryption`), rather than putting this in the `structurizr.properties` file.
+| `structurizr.authentication` | The name of the authentication implementation to use: `file` (default), `ldap` (see [LDAP](authentication#ldap) for more details), or `saml` (see [SAML 2.0](authentication#saml-20) for more details). |
+| `structurizr.apiKey` | A bcrypt encoded value to use as an API key for the [admin API](api#admin-api). |
+| `structurizr.session` | The name of the HTTP session storage implementation to use: `local` (default) or `redis`. See [HTTP sessions](http-sessions) for more details. |
+| `structurizr.admin` | By default, any authenticated user can create and delete workspaces. If you would like to restrict who can create and delete workspaces, set this property to a comma-separated list of usernames or roles that should have "admin" access. |
+| `structurizr.data` | The name of the data storage implementation to use: `file` (default) or `aws-s3` (see [Amazon Web Services S3](data-storage#amazon-web-services-s3) for more details). |
+| `structurizr.search` | The name of the search implementation to use: `lucene` (default), `none`, or `elasticsearch` (see [Elasticsearch](data-storage#elasticsearch) for more details). |
+| `structurizr.maxWorkspaceVersions` | The number of workspace versions to retain when using file-based data storage (default; `30`). |
+| `structurizr.safeMode` | Whether HTML should be filtered from workspace content; `true` (default) or `false`. |
+| `structurizr.feature.ui.dslEditor` | Enables/disables the browser-based DSL editor: `true` or `false` (default). |
+| `structurizr.feature.ui.workspaceUsers` | Enables/disables the ability to manage workspace users via the UI (i.e. the "Users" link on the workspace summary pages): `true` (default) or `false`. |
+| `structurizr.feature.ui.workspaceSettings` | Enables/disables the workspace settings page: `true` (default) or `false`. |
+
+## HTTPS
+
+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](https://tomcat.apache.org/tomcat-9.0-doc/ssl-howto.html).
+- Configure HTTPS upstream; for example [Load Balancing Apache Tomcat Servers with NGINX Open Source and NGINX Plus](https://docs.nginx.com/nginx/deployment-guides/load-balance-third-party/apache-tomcat/), [Create an HTTPS listener for your Application Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/create-https-listener.html), etc.
+
+If, after configuring HTTPS, you find that the on-premises installation is still trying to use some HTTP URLs
+or the web pages don't look right (e.g. styles are not loading correctly, images are oversize, etc),
+you will likely need to specify the correct HTTPS URL via the `structurizr.url` property (see above).
+
+## Logging
+
+The `log4j2` framework is used for logging and, by default, the logging level is set to `info`.
+If you're having an issue and would like to change the logging level:
+
+1. Copy the [log4j2.properties](https://github.com/structurizr/onpremises/blob/main/structurizr-onpremises/src/main/resources/log4j2.properties) file into your Structurizr data directory.
+2. Modify the logging levels as needed.
+3. Restart your on-premises installation.
+
+If you're specifically having issues with authentication via SAML, you can make the following changes:
+
+1. Change line 19 to `logger.springSecurity.level = debug`
\ No newline at end of file
diff --git a/onpremises/04-authentication.md b/onpremises/04-authentication.md
new file mode 100644
index 0000000..6037569
--- /dev/null
+++ b/onpremises/04-authentication.md
@@ -0,0 +1,175 @@
+---
+layout: default
+title: Authentication
+parent: Structurizr on-premises
+nav_order: 4
+permalink: /onpremises/authentication
+---
+
+# Authentication
+
+There are three variants of the on-premises installation, each with different authentication methods:
+
+- [Form-based login, with a file-based user store](#local-file)
+- [Form-based login, with integration to your LDAP server](#ldap)
+- [Single sign-on with your Identity Provider via SAML 2.0](#saml-20)
+
+## Local file
+
+This variant is used by default, and 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](http://localhost:8080/bcrypt/password)).
+
+It is also possible to configure a comma separated list of roles for every user, in a file called `structurizr.roles`, again in the Structurizr data directory.
+Each line in this file should be in the following format:
+
+```
+{username}={role1},{role2},{role3}
+```
+
+## LDAP
+
+A form-based login with integration to an LDAP server is supported, and this has been used successfully with FreeIPA and Microsoft Active Directory (via the LDAP binding). To configure LDAP integration:
+
+- Add `structurizr.authentication=ldap` to your `structurizr.properties` file.
+- Create a file named `ldap.xml` in your Structurizr data directory, based upon the following template. If you make any changes to this LDAP configuration file, you will need to restart the on-premises installation.
+
+```
+
+
+
+
+
+```
+
+The [Spring - LDAP Authentication](https://docs.spring.io/spring-security/site/docs/5.0.x/reference/html/ldap.html) documentation explains how to configure
+LDAP integration, but some example configurations are as follows.
+
+### FreeIPA
+
+The FreeIPA demo server can be useful to test LDAP integration.
+
+```
+
+
+
+
+
+```
+
+### Microsoft Active Directory
+
+This configuration can be used as a starting point for integrating with Microsoft Active Directory.
+You will need to change the following values in the example below:
+
+- `DC=mycompany,DC=local` (the search base x2)
+- `ldap://127.0.0.1:389` (your LDAP URL)
+- `MYCOMPANY\Administrator` (your LDAP username)
+- `password` (your LDAP password)
+
+```
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+## SAML 2.0
+
+Single sign-on is supported via SAML 2.0 integration with an Identity Provider.
+There are teams using this in conjunction with Auth0, Okta, Keycloak, PingFederate, and Microsoft Azure Active Directory.
+To configure SAML integration:
+
+- Add `structurizr.authentication=saml` to your `structurizr.properties` file.
+- The `structurizr.url` property in the `structurizr.properties` file should be set to the URL where Structurizr is installed (e.g. `http://localhost:8080`).
+- 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`).
+- Add a `structurizr.saml.entityId` property to your `structurizr.properties` file, set to the SAML Entity ID that you are using to identify the Structurizr on-premises installation (configured with your Identity Provider when setting up the application/client in the previous step).
+- 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.
+- Map the IdP username to a SAML attribute named `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`
+- Map the IdP roles/groups to a SAML attribute named `http://schemas.xmlsoap.org/claims/Group`
+
+If you make any changes to the SAML configuration, you will need to restart the on-premises installation.
+
+Here are some guides that show how to integrate with different identity providers.
+
+### Auth0
+
+Here are some basic instructions for integration with Auth0. In this example, the Structurizr on-premises installation was running at `http://localhost:7080`.
+
+| Step | Description |
+| ---- | ----------- |
+| 1. Register the Structurizr on-premises installation | Create an Auth0 "application" to represent the Structurizr on-premises installation. The "name" you use here should be set as the `structurizr.saml.entityId` property in your `structurizr.properties` file.  |
+| 2. Set the callback URL | After creation, you will need to change the allowed callback URLs setting to `http://localhost:7080/saml/SSO`.  |
+| 3. Download IdP metadata | Click the "SAML2 webapp" add-on for the application, and download the SAML metadata by clicking the "Identity Provider Metadata: Download" link, saving this as `saml-idp-metadata.xml` in your Structurizr data directory.  |
+
+### Azure Active Directory
+
+Here are some basic instructions for integration with Azure Active Directory. In this example, the Structurizr on-premises installation was running at `http://localhost:7080`.
+See [SSO :: 500 Error after initial authentication](https://github.com/structurizr/onpremises/issues/8) if your SAML integration stops working after a short period of time -
+you may need to change the [max authentication age](troubleshooting#max-authentication-age) or [force authentication](troubleshooting#force-authentication).
+
+| Step | Description |
+| ---- | ----------- |
+| 1. Register the Structurizr on-premises installation | Create an Azure "enterprise application" to represent the Structurizr on-premises installation. Choose the "Integrate with any other application you don't find in the gallery" option.  |
+| 2. Change the SSO method to SAML |  |
+| 3. Configure SAML | The "identifier" you use here should be set as the `structurizr.saml.entityId` property in your `structurizr.properties` file. And the "reply URL" should be set to `http://localhost:7080/saml/SSO`.  |
+| 4. Download IdP metadata | Download the IdP metadata from the "App Federation Metadata URL" link, saving this as `saml-idp-metadata.xml` in your Structurizr data directory.  |
+
+### Keycloak
+
+Here are some basic instructions for integration with Keycloak (tested on v21). In this example, the Structurizr on-premises installation was running at `http://localhost:7080`, and a realm already existed.
+
+| Step | Description |
+| ---- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| 1. Download IdP metadata | Find the realm that you would like authenticate against, open "Realm settings" menu, and download the SAML metadata by clicking the "SAML 2.0 Identity Provider Metadata" link, saving this as `saml-idp-metadata.xml` in your Structurizr data directory.  |
+| 2. Register the Structurizr on-premises installation | Create a Keycloak "client" to represent the Structurizr on-premises installation. The "client ID" you use here should be set as the `structurizr.saml.entityId` property in your `structurizr.properties` file. . On second screen you need to specify "Valid redirect URIs" to the `http://localhost:7080/saml/SSO` (otherwise you'll see an "Invalid redirect URI" message). |
+| 3. Configure SAML | After creation, set "Client Signature Required" on the "Keys" tab to `Off` (otherwise you'll see an "Invalid requester" message).
+| 4. Add user property mappers | At this point, the integration should be functional, although you won't see the username and groups/roles associated with the user. To do that, you need to add a couple of mappings for the client - one for the username, and one for the groups/roles. To do this navigate to the "Client Scopes" tab and choose "structurizr-dedicated" item. To add email mapper choose "configure new mapper", "User Property" and fill SAML attribute name as `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` and property name as "email":  To configure group mapping create new "Role list" mapper and set "Role attribute name" as `http://schemas.xmlsoap.org/claims/Group`. Enable "Single Role Attribute" setting, otherwise app will see only one group. Save mapper and create and assign appropriate roles to your users.  |
diff --git a/onpremises/05-authorisation.md b/onpremises/05-authorisation.md
new file mode 100644
index 0000000..d4213c6
--- /dev/null
+++ b/onpremises/05-authorisation.md
@@ -0,0 +1,26 @@
+---
+layout: default
+title: Authorisation
+parent: Structurizr on-premises
+nav_order: 5
+permalink: /onpremises/authorisation
+---
+
+# Authorisation
+
+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 a locked/unlocked icon.
+
+## Configuring users and roles
+
+Workspace access can be configured via the "Users" link on your workspace summary page.
+Two text boxes provide a way to specify the usernames or role names that should have
+read/write or read-only access.
+Usernames and roles can also be specified via a regular expression.
+For example, `^.*@example.com$` can be used to match everybody with an `@example.com` e-mail address.
+Please note that regular expressions must be specified in the form, `^...$`.
+
+If you'd prefer, you can also configure the set of users when creating your workspace using the Structurizr DSL,
+via [users](/dsl/language#users).
+Some code-based libraries (e.g. [Structurizr for Java](https://github.com/structurizr/java/blob/master/structurizr-core/src/com/structurizr/configuration/WorkspaceConfiguration.java)) may also support this feature.
diff --git a/onpremises/06-http-sessions.md b/onpremises/06-http-sessions.md
new file mode 100644
index 0000000..3146bd3
--- /dev/null
+++ b/onpremises/06-http-sessions.md
@@ -0,0 +1,26 @@
+---
+layout: default
+title: HTTP sessions
+parent: Structurizr on-premises
+nav_order: 6
+permalink: /onpremises/http-sessions
+---
+
+# HTTP session storage
+
+There are two variants for HTTP session storage.
+
+## Local server
+
+By default, HTTP sessions are stored locally, in memory, on the server that created them. This works for a single server installation, but may not work for a high-availability installation, particularly where multiple instances are deployed behind a load balancer that is delivering requests using a round-robin algorithm. If "sticky sessions" or "session pinning" is not an option, you can choose
+to have HTTP session information stored in a Redis database instead.
+
+## Redis
+
+To use Redis for HTTP session storage, assuming that you have a Redis installation and up running, make the following changes to your
+`structurizr.properties` file, and restart your on-premises installation.
+
+1. Add a property named `structurizr.session` with a value of `redis`.
+2. Add properties named `structurizr.redis.host`, `structurizr.redis.port`, and `structurizr.redis.password` with values that reflect your Redis installation.
+
+A side-effect of using Redis for session storage is that user sessions should survive restarts of the on-premises installation.
\ No newline at end of file
diff --git a/onpremises/07-data-storage.md b/onpremises/07-data-storage.md
new file mode 100644
index 0000000..ff8bf09
--- /dev/null
+++ b/onpremises/07-data-storage.md
@@ -0,0 +1,61 @@
+---
+layout: default
+title: Data storage
+parent: Structurizr on-premises
+nav_order: 7
+permalink: /onpremises/data-storage
+---
+
+# Data storage
+
+The default configuration uses the local file system for data storage.
+This is sufficient for a single server installation, as well as for a multi-server installation where you can share a file system between server nodes.
+
+## Amazon Web Services S3
+
+Alternatively, Amazon Web Services S3 (or an S3 compatible service) can be used for data storage.
+
+
+
+The basic steps to configure S3 are:
+
+- Create a bucket under your AWS account (folders named `workspaces` and `reviews` will be created in this bucket).
+- Create a new programmatic access user in AWS, with the following permissions: `AmazonS3FullAccess`.
+- Modify your `structurizr.properties` file to configure AWS S3 integration as follows:
+
+| Property name | Property value |
+|--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------|
+| `structurizr.data` | `aws-s3` |
+| `aws-s3.accessKeyId` | Your AWS API key ID. |
+| `aws-s3.secretAccessKey` | Your AWS API secret access key. |
+| `aws-s3.region` | Your AWS region (e.g. `us-east-1`). |
+| `aws-s3.bucketName` | Your S3 bucket name. |
+| `aws-s3.endpoint` | Your custom S3-compatible endpoint. |
+| `aws-s3.pathStyleAccess` | Enables [path-style access](https://docs.aws.amazon.com/AmazonS3/latest/userguide/VirtualHosting.html#path-style-access) (`false` by default). |
+
+Alternatively, you can leave the `aws-s3.accessKeyId` and `aws-s3.secretAccessKey` parameters unset,
+and the on-premises installation will use the "Default Credential Provider Chain" to search your environment for the credentials, as described at
+[Working with AWS Credentials - Using the Default Credential Provider Chain](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html).
+
+You will need to enable bucket versioning if you'd like to use [Structurizr's workspace versioning feature](https://structurizr.com/help/workspace-versioning).
+
+### Elasticsearch
+
+The default configuration uses Apache Lucene for search functionality, storing search indexes on the local file system.
+This is sufficient for a single server installation, but Apache Lucene's search indexes are not designed for concurrent access from multiple processes.
+To run the Structurizr on-premises installation across multiple servers, for high availability, you'll need to use Elasticsearch instead.
+You can use a local Elasticsearch installation, or a service provided by a cloud provider.
+Version 6.8.10 and above is recommended.
+
+
+
+Modify your `structurizr.properties` file to configure Elasticsearch integration as follows:
+
+| Property name | Property value |
+| ------------- | -------------- |
+| `structurizr.search` | `elasticsearch` |
+| `elasticsearch.protocol` | The protocol used to communicate with Elasticsearch: `http` (default) or `https`. |
+| `elasticsearch.host` | Your Elasticsearch hostname/IP address (default: `localhost`) |
+| `elasticsearch.port` | Your Elasticsearch port number (default: `9200`). |
+| `elasticsearch.username` | The username used to connect to your Elasticsearch instance, if applicable. |
+| `elasticsearch.password` | The password used to connect to your Elasticsearch instance, if applicable. |
diff --git a/onpremises/08-api.md b/onpremises/08-api.md
new file mode 100644
index 0000000..27235df
--- /dev/null
+++ b/onpremises/08-api.md
@@ -0,0 +1,43 @@
+---
+layout: default
+title: API
+parent: Structurizr on-premises
+nav_order: 8
+permalink: /onpremises/api
+---
+
+# API
+
+The on-premises installation has two APIs:
+
+1. The workspace API for getting and putting workspaces.
+2. The admin API for creating, deleting, and listing workspaces.
+
+## Workspace API
+
+The workspace API is documented at [Structurizr - Help - Web API](https://structurizr.com/help/web-api),
+and has the following endpoints:
+
+- GET `/api/workspace/{workspaceId}` (get workspace)
+- PUT `/api/workspace/{workspaceId}` (put workspace)
+- PUT `/api/workspace/{workspaceId}/lock` (lock workspace)
+- DELETE `/api/workspace/{workspaceId}/lock` (unlock workspace)
+
+## Admin API
+
+The admin API provides a way to create, delete, and list workspaces.
+This API is disabled by default, and can be enabled by adding a property named
+`structurizr.apiKey` to your `structurizr.properties` file - see [Configuration](configuration) for more details.
+
+The following endpoints are available:
+
+- GET `/api/workspace` (list all workspaces)
+- POST `/api/workspace` (create workspace)
+- DELETE `/api/workspace/{workspaceId}` (delete workspace)
+
+The API key should be specified via the `X-Authorization` header.
+For example, the following `curl` command could be used to get a list of workspaces:
+
+```
+curl --header "X-Authorization: 123456789" http://localhost:8080/api/workspace
+```
\ No newline at end of file
diff --git a/onpremises/09-faq.md b/onpremises/09-faq.md
new file mode 100644
index 0000000..eb14105
--- /dev/null
+++ b/onpremises/09-faq.md
@@ -0,0 +1,45 @@
+---
+layout: default
+title: FAQ
+parent: Structurizr on-premises
+nav_order: 9
+permalink: /onpremises/faq
+---
+
+# FAQ
+
+Here are answers to some frequently asked questions. If you don't see an answer you are looking for,
+please [open a new discussion on the GitHub repo](https://github.com/structurizr/onpremises/discussions).
+
+## Installation
+
+### What are the minimum hardware requirements?
+
+The on-premises installation will happily run on a laptop, supporting hundreds of concurrent users, so any small server with a few GB of RAM should be sufficient for most teams.
+
+### Can the on-premises version of Structurizr be installed on public cloud IaaS and PaaS services?
+
+The on-premises version is designed to run inside a trusted network environment, but some of our customers have installed it on
+environments such as the public Amazon Web Services and Microsoft Azure clouds.
+Please ensure that you consider the security implications of doing this, and that you harden any servers and restrict access where appropriate.
+
+### Can the on-premises installation be clustered for high availability?
+
+Yes, [Amazon Web Service S3](data-storage#amazon-web-services-s3) and [Elasticsearch](data-storage#elasticsearch) are supported.
+
+### Does the on-premises installation require an Internet connection?
+
+No, the on-premises installation can run completely disconnected from the Internet, and doesn't make any requests to the Internet to check for updates.
+You will only require Internet access from the server if you have workspaces that make use of an Internet hosted [theme](https://structurizr.com/help/themes) and have server-side (Graphviz) automatic layout enabled.
+
+### Does the on-premises installation automatically update itself?
+
+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, pull the latest Docker image or download a new version of the
+`.war` file, overwrite the existing version and restart your web/application server.
+We recommend scripting your deployments, and ensuring that you can easily rollback if needed.
+
+### Can the on-premises installation run over HTTPS?
+
+Yes, see [HTTPS](configuration#https) for details.
diff --git a/onpremises/10-troubleshooting.md b/onpremises/10-troubleshooting.md
new file mode 100644
index 0000000..c011063
--- /dev/null
+++ b/onpremises/10-troubleshooting.md
@@ -0,0 +1,67 @@
+---
+layout: default
+title: Troubleshooting
+parent: Structurizr on-premises
+nav_order: 10
+permalink: /onpremises/troubleshooting
+---
+
+# Troubleshooting
+
+Here are some common problems, and how to resolve them.
+If your problem isn't listed here, please browse [the issues on the GitHub repo](https://github.com/structurizr/onpremises/issues).
+
+## Installation
+
+### The home page loads, but doesn't look right
+
+If you can see the home page, but it doesn't look right (e.g. the styles don't seem to be loading, images are oversized, etc),
+you will likely need to explicitly set the `structurizr.url` property. See [Configuration - structurizr.properties](configuration#structurizrproperties) for details.
+
+### The on-premises installation cannot be accessed or is not found
+
+The on-premises installation needs to be run as the root/default web application/context.
+For Apache Tomcat, this means the web application named `ROOT`, running at `/`.
+It is not possible to run the on-premises installation with an alternative context (e.g. `/structurizr-onpremises`).
+
+## Diagrams
+
+### Embedded diagrams don't load
+
+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 override those generated/used by the on-premises installation,
+causing issues such as the embedded diagram viewer/editor not working.
+The following headers may need to be disabled in your reverse proxy if they are being set:
+
+- [X-Frame-Options](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options)
+- [Content-Security-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy)
+
+## Reviews
+
+### Diagram reviews fail to be created
+
+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](https://tomcat.apache.org/tomcat-9.0-doc/config/http.html)).
+
+## SAML integration
+
+The variation between identity providers and how organisations configure identity providers can make it difficult
+to configure SAML integration, and even the smallest misconfiguration can cause errors, most of which you'll see in
+the logs as a HTTP 405, `Request method 'POST' not supported` message. Some recommended steps to resolve this are:
+
+1. Configure a non-secure (i.e. HTTP) `localhost` instance of the on-premises installation against your IdP to ascertain whether the problems you are seeing are related to your hosting environment (i.e. HTTPS, load balancers, reverse proxies, DNS, etc).
+2. Debug the SAML handshake with one of the available browser plugins.
+3. Enable debug on the on-premises installation to see the underlying error message (see [Configuration - Logging](configuration#logging)).
+
+### Max authentication age
+
+By default, Spring Security checks that you've been authenticated with your IdP within the past 2 hours (7200 seconds).
+If this value is too low, you can override it via a property named `structurizr.saml.maxAuthenticationAge` in your `structurizr.properties` file (the value is the number of seconds, e.g. 86400 seconds for 24 hours).
+
+### Force authentication
+
+If you see intermittent HTTP 405 errors when trying to sign in (particularly after signing in already),
+you can set Structurizr to force authentication by setting a property named `structurizr.saml.forceAuthentication`
+in your `structurizr.properties` file (`true`, or `false` by default).
+
diff --git a/onpremises/images/auth0-1.png b/onpremises/images/auth0-1.png
new file mode 100644
index 0000000..c471d1e
Binary files /dev/null and b/onpremises/images/auth0-1.png differ
diff --git a/onpremises/images/auth0-2.png b/onpremises/images/auth0-2.png
new file mode 100644
index 0000000..2cd7c41
Binary files /dev/null and b/onpremises/images/auth0-2.png differ
diff --git a/onpremises/images/auth0-3.png b/onpremises/images/auth0-3.png
new file mode 100644
index 0000000..0e2e015
Binary files /dev/null and b/onpremises/images/auth0-3.png differ
diff --git a/onpremises/images/azure-1.png b/onpremises/images/azure-1.png
new file mode 100644
index 0000000..281ab1f
Binary files /dev/null and b/onpremises/images/azure-1.png differ
diff --git a/onpremises/images/azure-2.png b/onpremises/images/azure-2.png
new file mode 100644
index 0000000..7172832
Binary files /dev/null and b/onpremises/images/azure-2.png differ
diff --git a/onpremises/images/azure-3.png b/onpremises/images/azure-3.png
new file mode 100644
index 0000000..aa210ee
Binary files /dev/null and b/onpremises/images/azure-3.png differ
diff --git a/onpremises/images/azure-4.png b/onpremises/images/azure-4.png
new file mode 100644
index 0000000..a581f8d
Binary files /dev/null and b/onpremises/images/azure-4.png differ
diff --git a/onpremises/images/keycloak-1.png b/onpremises/images/keycloak-1.png
new file mode 100644
index 0000000..e2e9f5c
Binary files /dev/null and b/onpremises/images/keycloak-1.png differ
diff --git a/onpremises/images/keycloak-2.png b/onpremises/images/keycloak-2.png
new file mode 100644
index 0000000..e5b482f
Binary files /dev/null and b/onpremises/images/keycloak-2.png differ
diff --git a/onpremises/images/keycloak-3.png b/onpremises/images/keycloak-3.png
new file mode 100644
index 0000000..f90fac2
Binary files /dev/null and b/onpremises/images/keycloak-3.png differ
diff --git a/onpremises/images/keycloak-4.png b/onpremises/images/keycloak-4.png
new file mode 100644
index 0000000..354e809
Binary files /dev/null and b/onpremises/images/keycloak-4.png differ
diff --git a/onpremises/index.md b/onpremises/index.md
new file mode 100644
index 0000000..cf6b745
--- /dev/null
+++ b/onpremises/index.md
@@ -0,0 +1,15 @@
+---
+layout: default
+title: Structurizr on-premises
+nav_order: 5
+has_children: true
+permalink: /onpremises
+has_toc: true
+---
+
+# Structurizr on-premises
+
+The Structurizr on-premises installation is a standalone version of Structurizr that can be run locally on your own infrastructure.
+It's a Java EE/Spring MVC web application, packaged as a `.war` file, for deployment into any compatible Java EE server, such as Apache Tomcat.
+For ease of deployment, by default, all data is stored on the local file system.
+Optionally, data can be stored on Amazon S3, and search indexes on an Elasticsearch cluster.
\ No newline at end of file