Adds Lite docs.

lite/01-quickstart.md

@@ -0,0 +1,52 @@
+---
+layout: default
+title: Quickstart
+parent: Structurizr Lite
+nav_order: 1
+permalink: /lite/quickstart
+---
+
+# Quickstart
+
+Here's a quick getting started to using Structurizr Lite via the pre-built Docker image,
+and assumes that you have Docker installed.
+
+## 1. Create a directory
+
+First you need to create a directory somewhere to store your workspace.
+We'll refer to this directory as the "Structurizr data directory".
+
+## 2. Start Structurizr Lite
+
+You can now start Structurizr Lite with the following commands, replacing `PATH` with the path to your Structurizr data directory:
+
+```
+docker pull structurizr/lite
+docker run -it --rm -p 8080:8080 -v PATH:/usr/local/structurizr structurizr/lite
+```
+
+For example, if your Structurizr data directory is located at `/Users/simon/structurizr`, the command would be:
+
+```
+docker pull structurizr/lite
+docker run -it --rm -p 8080:8080 -v /Users/simon/structurizr:/usr/local/structurizr structurizr/lite
+```
+
+## 3. Open your web browser
+
+With Structurizr Lite running, you can head to [http://localhost:8080](http://localhost:8080) in your web browser, where
+you should see the diagram editor:
+
+![Getting started with Structurizr Lite](images/getting-started.png)
+
+At startup, Structurizr Lite created a file named `workspace.dsl` in your Structurizr data directory as a starting point.
+This is a Structurizr workspace, defined using the [Structurizr DSL](/dsl).
+It defines a model consisting of a user using a software system, and a single C4 model system context view.
+
+## 4. Make some changes
+
+You can now modify the `workspace.dsl` file, save the changes, and refresh your web browser to see those changes.
+Some useful links related to the DSL are:
+
+- [Structurizr DSL language reference](/dsl/language)
+- [Structurizr DSL cookbook](/dsl/cookbook)

lite/02-installation.md

@@ -0,0 +1,62 @@
+---
+layout: default
+title: Installation
+parent: Structurizr Lite
+nav_order: 2
+permalink: /lite/installation
+---
+
+# Installation
+
+Structurizr Lite is available as [Docker image](#docker) (recommended) and [a Spring Boot application](#spring-boot).
+
+## Create the Structurizr data directory
+
+Structurizr Lite needs to be given access to a directory, in which a `workspace.dsl` or `workspace.json` file exists that defines your workspace.
+We'll refer to this directory as the "Structurizr data directory".
+If this directory doesn't exist when Structurizr Lite is started up, it will be created for you, along with a basic DSL file.
+
+## Docker
+
+Assuming that you have Docker installed, to start Structurizr Lite, use the following command to pull the image from [Docker Hub](https://hub.docker.com/r/structurizr/lite).
+
+```
+docker pull structurizr/lite
+```
+
+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/lite
+```
+
+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/lite
+```
+
+There is a [Dockerfile](https://github.com/structurizr/lite/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.
+
+## Spring Boot
+
+To use the Spring Boot version, you'll need Java 17+ (required) and [Graphviz](https://graphviz.org/download/) (optional; if you want to use automatic layout).
+Download the `structurizr-lite.war` file from [https://github.com/structurizr/lite/releases](https://github.com/structurizr/lite/releases), and start with the following command, replacing `PATH` with the path to your Structurizr data directory:
+
+```
+java -Djdk.util.jar.enableMultiRelease=false -jar structurizr-lite-xxxx.war PATH
+```
+
+
+For example, if your Structurizr data directory is located at `/Users/simon/structurizr`, the command would be:
+
+```
+java -Djdk.util.jar.enableMultiRelease=false -jar structurizr-lite-xxxx.war /Users/simon/structurizr
+```
+
+Please note that there is [an issue with Windows PowerShell](https://github.com/PowerShell/PowerShell/issues/15541),
+so you may need to quote the system property argument, for example:
+
+```
+java "-Djdk.util.jar.enableMultiRelease=false" -jar structurizr-lite-xxxx.war /Users/simon/structurizr
+```

lite/03-usage.md

@@ -0,0 +1,111 @@
+---
+layout: default
+title: Usage
+parent: Structurizr Lite
+nav_order: 3
+permalink: /lite/usage
+---
+
+# Usage
+
+Structurizr Lite will look for a `workspace.dsl` and `workspace.json` file in your Structurizr data directory, in that order, and use the file it finds first.
+Navigating to [http://localhost:8080](http://localhost:8080) should open Structurizr Lite,
+where you'll be able to view any diagrams, documentation, and decision records defined in your workspace.
+Any changes made to the `workspace.dsl` or `workspace.json` file will be reflected when you refresh your web browser.
+
+## Workspace path
+
+Setting an environment variable named `STRUCTURIZR_WORKSPACE_PATH` provides a way to tell Structurizr Lite that your
+workspace definition can be found in a subdirectory of the Structurizr data directory.
+This can be useful in conjunction with the workspace extension feature; for example:
+
+- `/Users/simon/structurizr/system-landscape.dsl`
+- `/Users/simon/structurizr/software-system-1/workspace.dsl` (`extends ../system-landscape.dsl`)
+- `/Users/simon/structurizr/software-system-2/workspace.dsl` (`extends ../system-landscape.dsl`)
+
+To start Structurizr Lite against the workspace for "software system 1", with Docker:
+
+```
+docker run -it --rm -p 8080:8080 -v /Users/simon/structurizr:/usr/local/structurizr -e STRUCTURIZR_WORKSPACE_PATH=software-system-1 structurizr/lite
+```
+
+Or with Spring Boot:
+
+```
+export STRUCTURIZR_WORKSPACE_PATH=software-system-1
+java -jar structurizr-lite.war /Users/simon/structurizr
+```
+
+### Workspace filename
+
+By default, Structurizr Lite will look for files named `workspace.dsl` and `workspace.json` in your Structurizr data directory.
+You can customise this behaviour via an environment variable named `STRUCTURIZR_WORKSPACE_FILENAME`.
+For example, the following command will look for files named `system-landscape.dsl` and `system-landscape.json` instead:
+
+```
+docker run -it --rm -p 8080:8080 -v /Users/simon/structurizr:/usr/local/structurizr -e STRUCTURIZR_WORKSPACE_FILENAME=system-landscape structurizr/lite
+```
+
+Please note that you do not need to include the `.dsl` or `.json` file extension.
+
+## Auto-save
+
+By default, auto-save is enabled, with a 5000ms interval. To change this, create a file named `structurizr.properties`
+in your Structurizr Lite data directory and add the following line, changing the number of milliseconds as required. A value of `0` will disable auto-save.
+
+```
+structurizr.autoSaveInterval=5000
+```
+
+## Auto-refresh
+
+By default, auto-refresh is disabled, and changes to your workspace will not be seen in your web browser until you refresh the diagrams/documentation/decision pages.
+To enable auto-refresh, create a file named `structurizr.properties`
+in your Structurizr Lite data directory and add the following line, changing the number of milliseconds as required. A value of `0` will disable auto-refresh.
+
+```
+structurizr.autoRefreshInterval=2000
+```
+
+When enabled, Structurizr Lite will look for changes to files inside your Structurizr data directory, and the diagrams/documentation/decision pages will automatically refresh when changes are detected.
+
+## Auto-sync
+
+Structurizr Lite's auto-sync feature allows you to automatically sync Structurizr Lite with a remote workspace from the Structurizr cloud service or an on-premises installation
+(excluding on-premises installations with self-signed certificates; support for this may be added in the future).
+This means that you can use Structurizr Lite for local authoring, and publish that same workspace for other people to view.
+
+### Configuring auto-sync
+
+To configure auto-sync, create a file named `structurizr.properties`
+in your Structurizr Lite data directory. The contents of the file should be as follows;
+replacing `ID`, `KEY`, and `SECRET` with your remote workspace ID, API key, and API secret respectively (you can find these on your workspace settings page).
+
+
+```
+structurizr.remote.workspaceId=ID
+structurizr.remote.apiKey=KEY
+structurizr.remote.apiSecret=SECRET
+```
+
+
+A property named `structurizr.remote.apiUrl` can be used to specify an API URL for on-premises installations (this is not required for the cloud service).
+A property named `structurizr.remote.passphrase` can be used to specify the [client-side encryption](https://structurizr.com/help/client-side-encryption) passphrase.
+
+### Using auto-sync
+
+With auto-sync configured, Structurizr Lite will pull a copy of your remote workspace upon startup and save it as `workspace.json`
+(unless the local version is newer than the remote version) - this includes any diagram layout information, which you will now see in Lite.
+You can then edit your workspace as usual (e.g. by modifying your `workspace.dsl` file, saving it, and refreshing your web browser).
+When you've finished making edits, ensure that any local diagram layout changes are saved in Structurizr Lite's diagram editor.
+When you shutdown Structurizr Lite, it will automatically push this new version to your cloud service/on-premises installation.
+Opening your remote workspace will confirm that all changes have been synced.
+
+## Read-only diagrams
+
+By default, diagrams are editable. To disable this behaviour and make the diagrams read-only, create a file named `structurizr.properties`
+in your Structurizr Lite data directory and add the following line.
+
+```
+structurizr.editable=false
+```

lite/04-workflow.md

@@ -0,0 +1,50 @@
+---
+layout: default
+title: Workflow
+parent: Structurizr Lite
+nav_order: 4
+permalink: /lite/workflow
+---
+
+# Workflow
+
+The recommended workflow depends on whether you're using the DSL vs a code-based client library,
+and automatic vs manual layout for the diagrams in your workspace.
+Structurizr Lite is optimised for working with the DSL, and this is the recommended approach for most teams.
+Unlike the cloud service and on-premises installation, Structurizr Lite does not require you to push your workspace to it via a web API.
+Instead it works directly off the file system.
+
+## Structurizr DSL
+
+For local authoring:
+
+1. Create your workspace using the DSL, as a file named `workspace.dsl` in your Structurizr Lite data directory. Any included files (documentation, ADRs, icons, etc) should also be accessible from this directory.
+2. Start Structurizr Lite.
+3. Open your web browser and navigate to Structurizr Lite (e.g. [http://localhost:8080](http://localhost:8080)) to see your workspace content.
+4. Modify the diagram layout as needed, and save your workspace via the web UI (the "Save workspace" button). Structurizr Lite will write a JSON version of your workspace into your Structurizr Lite data directory to a file named `workspace.json` - this includes your workspace and the layout information for your diagrams.
+5. Make any changes as required to your DSL, and save your workspace.
+6. Refresh your web browser to see the changes.
+
+To publish your local workspace to the Structurizr cloud service or an on-premises installation:
+
+- For workspaces where all diagrams are configured to use auto-layout, just push the `workspace.dsl` file using the [Structurizr CLI](/cli).
+- For workspaces where one or more diagrams are configured to use manual layout, push the `workspace.json` file using the [Structurizr CLI](/cli) with `-merge false` to force your local diagram layout to be used.
+- Alternatively you can configure [auto-sync](usage#auto-sync).
+
+## Code-based client library
+
+For local authoring, create your workspace using code and, rather than pushing it via the web API, export the workspace to a file named `workspace.json` in your Structurizr Lite data directory. With the Java client library, this can be achieved with the following code, which will ensure that any diagram layout changes created by Structurizr Lite are retained when regenerating your workspace from code:
+
+```
+Workspace workspace = new Workspace(...);
+// create the workspace
+
+File file = new File("/some/path/workspace.json");
+if (file.exists()) {
+    Workspace liteWorkspace = WorkspaceUtils.loadWorkspaceFromJson(file); // load the old version that contains layout information
+    workspace.getViews().copyLayoutInformationFrom(liteWorkspace.getViews()); // copy layout information into the new workspace
+}
+WorkspaceUtils.saveWorkspaceToJson(workspace, file); // save the new workspace
+```
+
+To publish your local workspace to the Structurizr cloud service or an on-premises installation, push the `workspace.json` file using the [Structurizr CLI](/cli) or your client library.

lite/05-faq.md

@@ -0,0 +1,14 @@
+---
+layout: default
+title: FAQ
+parent: Structurizr Lite
+nav_order: 5
+permalink: /lite/faq
+---
+
+# FAQ
+
+## Does Structurizr Lite require Internet access?
+
+Internet access is not required by Structurizr Lite unless you're using [auto-sync](usage#auto-sync),
+or you're making use of a [theme](https://structurizr.com/help/themes) and have server-side (Graphviz) automatic layout enabled.

lite/06-troubleshooting.md

@@ -0,0 +1,55 @@
+---
+layout: default
+title: Troubleshooting
+parent: Structurizr Lite
+nav_order: 6
+permalink: /lite/troubleshooting
+---
+
+# Troubleshooting
+
+## Installation
+
+### Structurizr Lite loads, but doesn't look right
+
+If you can see Structurizr Lite in your web browser, 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 do the following. This is particularly applicable if you're running Structurizr Lite on a server with multiple hostnames, or behind a reverse proxy/load balancer/etc.
+
+1. Create a file named `structurizr.properties` in your Structurizr data directory, next to your `workspace.dsl` file.
+2. Add a line as follows: `structurizr.url=XXX` (where `XXX` represents the top-level URL of your Structurizr Lite installation; e.g. `https://structurizr.example.com`).
+3. Restart Structurizr Lite.
+
+## Diagrams
+
+### Diagram layout is lost when using manual layout
+
+Whenever you refresh Structurizr Lite, it will parse the `workspace.dsl` file and transform it into a workspace.
+But that new workspace doesn't include any layout information, because it's not stored in the DSL.
+Instead, the layout information is stored in the JSON representation of the workspace, in a file named `workspace.json`.
+
+When the DSL is refreshed, Structurizr Lite will additionally load the `workspace.json` file,
+and copy the layout information into the newly created version.
+This is done via [a pluggable merging algorithm in the Structurizr for Java library](https://github.com/structurizr/java/blob/master/structurizr-core/src/com/structurizr/view/DefaultLayoutMergeStrategy.java). 
+This algorithm works most of the time, but doesn't cater for a number of edge cases unfortunately.
+
+Individual elements losing their layout information is generally caused by renaming those elements, often in conjunction with changing
+the order of lines in the DSL, thereby affecting the order in which elements are created, and the internal IDs they are given.
+In essence, the merging algorithm isn't able to match elements created via the `workspace.dsl` file with those that already exist
+in the `workspace.json` file.
+
+Entire diagrams losing their layout information is generally caused by changing the key associated with that view.
+To minimise this, please be sure to use stable keys for your views, rather than allowing the DSL parser to generate them for you.
+For example:
+
+```
+systemLandscape "MyViewKey" {
+  include *
+}
+```
+
+ Rather than:
+
+```
+systemLandscape {
+  include *
+}
+```

lite/index.md

@@ -0,0 +1,18 @@
+---
+layout: default
+title: Structurizr Lite
+nav_order: 4
+has_children: true
+permalink: /lite
+has_toc: true
+---
+
+# Structurizr Lite
+
+This free and open source version of Structurizr allows you to view/edit diagrams, view documentation, and view architecture decision records defined in a single DSL or JSON workspace.
+Structurizr Lite can be used standalone for workspace viewing/authoring, or in conjunction with the cloud service/on-premises installation as an authoring/testing/staging environment.
+
+Please note that Structurizr Lite is only designed to be used by a single person, and has no collaboration features built-in.
+Having multiple people concurrently access the same Structurizr Lite instance, or running multiple Structurizr Lite instances concurrently against the same folder may result in unexpected behaviour (workspace content corrupted, diagram layout lost, etc).
+The [on-premises installation](https://structurizr.com/help/on-premises) or [cloud service](https://structurizr.com/help/cloud-service)
+are recommended if you require team/collaboration features.