Skip to content

Commit

Permalink
Adds on-premises docs.
Browse files Browse the repository at this point in the history
  • Loading branch information
@simonbrowndotje
simonbrowndotje committed Sep 1, 2023
1 parent 49b1e86 commit 9714799
Show file tree
Hide file tree
Showing 22 changed files with 646 additions and 0 deletions.
37 changes: 37 additions & 0 deletions onpremises/01-quickstart.md
View file
Original file line number Diff line number Diff line change
@@ -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.
80 changes: 80 additions & 0 deletions onpremises/02-installation.md
View file
Original file line number Diff line number Diff line change
@@ -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).
71 changes: 71 additions & 0 deletions onpremises/03-configuration.md
View file
Original file line number Diff line number Diff line change
@@ -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`
Loading

0 comments on commit 9714799

Please sign in to comment.