diff --git a/deploy/compose/docker-compose.yml b/deploy/compose/docker-compose.yml
deleted file mode 100644
index a24f70f4b7..0000000000
--- a/deploy/compose/docker-compose.yml
+++ /dev/null
@@ -1,42 +0,0 @@
-version: '3.8'
-
-services:
- zitadel:
- restart: always
- networks:
- - zitadel
- image: ghcr.io/zitadel/zitadel:v2.0.0-v2-alpha.33-amd64
- command: start-from-init --masterkey "MasterkeyNeedsToHave32Characters" --tlsMode disabled
- environment:
- - ZITADEL_DATABASE_HOST=db
- - ZITADEL_DEFAULTINSTANCE_CUSTOMDOMAIN=localhost
- healthcheck:
- test: ["CMD", "curl", "-f", "http://localhost:8080/debug"]
- interval: 10s
- timeout: 30s
- retries: 5
- start_period: 40s
- depends_on:
- db:
- condition: service_healthy
- ports:
- - 8080:8080
-
- db:
- restart: always
- networks:
- - zitadel
- image: cockroachdb/cockroach:v22.1.0
- command: start-single-node --insecure
- healthcheck:
- test: ["CMD", "curl", "-f", "http://localhost:8080/health?ready=1"]
- interval: 10s
- timeout: 30s
- retries: 5
- start_period: 20s
- ports:
- - 9090:8080
- - 26257:26257
-
-networks:
- zitadel:
diff --git a/docs/docs/guides/installation/compose.mdx b/docs/docs/guides/installation/compose.mdx
deleted file mode 100644
index 956f5aa833..0000000000
--- a/docs/docs/guides/installation/compose.mdx
+++ /dev/null
@@ -1,11 +0,0 @@
-Download the docker compose example configuration
-
-```bash
-wget https://raw.githubusercontent.com/zitadel/zitadel/v2-alpha/deploy/compose/docker-compose.yml
-```
-
-Run the database and application containers
-
-```bash
-docker compose up
-```
diff --git a/docs/docs/guides/installation/configuration.mdx b/docs/docs/guides/installation/configuration.mdx
deleted file mode 100644
index 811370db29..0000000000
--- a/docs/docs/guides/installation/configuration.mdx
+++ /dev/null
@@ -1,40 +0,0 @@
-## Overwrite ZITADEL Defaults
-
-See a description of all possible configuration options with their defaults [in the source code](https://github.com/zitadel/zitadel/blob/v2/cmd/defaults.yaml).
-You can overwrite these values using environment variables or configuration files.
-
-### Configure by environment variables
-
-Prefix the key with *ZITADEL\_*, uppercase the propery and join sections by an underscore _.
-For example, if you want to configure the default ZITADEL IAM admin username and password, export these two variables.
-
-```bash
-export ZITADEL_DEFAULTINSTANCE_ORG_HUMAN_USERNAME="root"
-export ZITADEL_DEFAULTINSTANCE_ORG_HUMAN_PASSWORD="RootPassword1!"
-```
-
-### Configure by configuration files
-
-Probably, you want to keep some configuration secret.
-Fortunately, you can pass multiple configuration files to the zitadel command.
-
-```bash
-# Create a configuration file containing normal configuration
-cat << EOF > ./zitadel-config.yaml
-DefaultInstance:
- Org:
- Human:
- Username: root
-EOF
-
-# Create a configuration file containing secrets
-cat << EOF > ./zitadel-secrets.yaml
-DefaultInstance:
- Org:
- Human:
- Password: RootPassword1!
-EOF
-
-# Pass multiple config files using the --config argument
-zitadel start-from-init --config ./zitadel-config.yaml --config ./zitadel-secrets.yaml --masterkey "MasterkeyNeedsToHave32Characters"
-```
diff --git a/docs/docs/guides/installation/configure/compose.mdx b/docs/docs/guides/installation/configure/compose.mdx
new file mode 100644
index 0000000000..654498f023
--- /dev/null
+++ b/docs/docs/guides/installation/configure/compose.mdx
@@ -0,0 +1,29 @@
+The docker compose example mounts the example zitadel configuration files to the ZITADEL container.
+
+By executing the commands below, you will download the following files:
+- [docker-compose.yaml](./docker-compose.yaml)
+- [example-zitadel-config.yaml](./example-zitadel-config.yaml)
+- [example-zitadel-secrets.yaml](./example-zitadel-secrets.yaml)
+- [example-zitadel-init-steps.yaml](./example-zitadel-init-steps.yaml)
+
+```bash
+# Download the docker compose example configuration for a secure CockroachDB. For example:
+wget https://raw.githubusercontent.com/zitadel/zitadel/v2-alpha/docs/docs/guides/installation/configure/docker-compose.yaml
+
+# Download and adjust the example configuration file containing standard configuration
+wget https://raw.githubusercontent.com/zitadel/zitadel/v2-alpha/docs/docs/guides/installation/configure/example-zitadel-config.yaml
+
+# Download and adjust the example configuration file containing secret configuration
+wget https://raw.githubusercontent.com/zitadel/zitadel/v2-alpha/docs/docs/guides/installation/configure/example-zitadel-secrets.yaml
+
+# Download and adjust the example configuration file containing database initialization configuration
+wget https://raw.githubusercontent.com/zitadel/zitadel/v2-alpha/docs/docs/guides/installation/configure/example-zitadel-init-steps.yaml
+
+# A single ZITADEL instance always needs the same 32 characters long masterkey
+# If you haven't done so already, you can generate a new one
+# For example:
+export ZITADEL_MASTERKEY="$(tr -dc A-Za-z0-9
+
+
+
+
+
+
+
+
+
+
+
+Open your favorite internet browser at [http://localhost:8080/ui/console](http://localhost:8080/ui/console).
+This is the IAM admin users login according to your configuration in the [example-zitadel-init-steps.yaml](./example-zitadel-init-steps.yaml):
+- **username**: *root@zitadel.localhost*
+- **password**: *RootPassword1!*
+
+## What's next
+
+- Read more about [the login process](../../manuals/user-login).
+- If you want to run ZITADEL in production, you most certainly need to [customize your own domain](./custom-domain).
+- Check out all possible [runtime configuration properties and their defaults in the source code](https://github.com/zitadel/zitadel/blob/v2-alpha/cmd/defaults.yaml)
+- Check out all possible [setup step configuration properties and their defaults in the source code](https://github.com/zitadel/zitadel/blob/v2-alpha/cmd/adminn/setup/steps.yaml)
+
+:::caution
+
+
+The ZITADEL management console [requires end-to-end HTTP/2 support](./http2-support)
diff --git a/docs/docs/guides/installation/configure/docker-compose.yaml b/docs/docs/guides/installation/configure/docker-compose.yaml
new file mode 100644
index 0000000000..65d10a2f55
--- /dev/null
+++ b/docs/docs/guides/installation/configure/docker-compose.yaml
@@ -0,0 +1,68 @@
+version: '3.8'
+
+services:
+
+ zitadel:
+ restart: 'always'
+ networks:
+ - 'zitadel'
+ image: 'ghcr.io/zitadel/zitadel:v2.0.0-v2-alpha.33-amd64'
+ command: 'start-from-init --config /example-zitadel-config.yaml --config /example-zitadel-secrets.yaml --steps /example-zitadel-init-steps.yaml --masterkey "${ZITADEL_MASTERKEY}" --tlsMode disabled'
+ depends_on:
+ chown:
+ condition: 'service_completed_successfully'
+ ports:
+ - '8080:8080'
+ volumes:
+ - './example-zitadel-config.yaml:/example-zitadel-config.yaml:ro'
+ - './example-zitadel-secrets.yaml:/example-zitadel-secrets.yaml:ro'
+ - './example-zitadel-init-steps.yaml:/example-zitadel-init-steps.yaml:ro'
+ - 'zitadel-certs:/crdb-certs:ro'
+
+ chown:
+ image: 'cockroachdb/cockroach:v22.1.0'
+ entrypoint: [ '/bin/bash', '-c' ]
+ command: [ 'cp /certs/ca.crt /zitadel-certs/ && cp /certs/client.root.crt /zitadel-certs/ && cp /certs/client.root.key /zitadel-certs/ && cp /certs/client.zitadel_user.crt /zitadel-certs/ && cp /certs/client.zitadel_user.key /zitadel-certs/ && chown 1000:1000 /zitadel-certs/* && chmod 0400 /zitadel-certs/*' ]
+ volumes:
+ - 'certs:/certs:ro'
+ - 'zitadel-certs:/zitadel-certs:rw'
+ depends_on:
+ client-certs:
+ condition: 'service_completed_successfully'
+
+ client-certs:
+ image: 'cockroachdb/cockroach:v22.1.0'
+ command: 'cert create-client --certs-dir /certs/ --ca-key /certs/ca.key zitadel_user'
+ restart: 'on-failure'
+ volumes:
+ - 'certs:/certs:rw'
+ depends_on:
+ my-cockroach-db:
+ condition: 'service_healthy'
+
+ my-cockroach-db:
+ restart: 'always'
+ networks:
+ - 'zitadel'
+ image: 'cockroachdb/cockroach:v22.1.0'
+ command: 'start-single-node --advertise-addr my-cockroach-db'
+ healthcheck:
+ test: ["CMD", "curl", "-f", "http://localhost:8080/health?ready=1"]
+ interval: '10s'
+ timeout: '30s'
+ retries: 5
+ start_period: '20s'
+ ports:
+ - '9090:8080'
+ - '26257:26257'
+ volumes:
+ - 'certs:/cockroach/certs:rw'
+ - 'data:/cockroach/cockroach-data:rw'
+
+networks:
+ zitadel:
+
+volumes:
+ certs:
+ zitadel-certs:
+ data:
diff --git a/docs/docs/guides/installation/configure/example-zitadel-config.yaml b/docs/docs/guides/installation/configure/example-zitadel-config.yaml
new file mode 100644
index 0000000000..0387561e41
--- /dev/null
+++ b/docs/docs/guides/installation/configure/example-zitadel-config.yaml
@@ -0,0 +1,22 @@
+# All possible options and their defaults: https://github.com/zitadel/zitadel/blob/v2-alpha/cmd/defaults.yaml
+Log:
+ Level: 'info'
+
+# Make ZITADEL accessible over HTTP, not HTTPS
+ExternalSecure: false
+
+# If not using the docker compose example, adjust these values for connecting ZITADEL to your CockroachDB
+Database:
+ Host: 'my-cockroach-db'
+ User:
+ SSL:
+ Mode: 'verify-full'
+ RootCert: "/crdb-certs/ca.crt"
+ Cert: "/crdb-certs/client.zitadel_user.crt"
+ Key: "/crdb-certs/client.zitadel_user.key"
+AdminUser:
+ SSL:
+ Mode: 'verify-full'
+ RootCert: "/crdb-certs/ca.crt"
+ Cert: "/crdb-certs/client.root.crt"
+ Key: "/crdb-certs/client.root.key"
diff --git a/docs/docs/guides/installation/configure/example-zitadel-init-steps.yaml b/docs/docs/guides/installation/configure/example-zitadel-init-steps.yaml
new file mode 100644
index 0000000000..a3abfe37af
--- /dev/null
+++ b/docs/docs/guides/installation/configure/example-zitadel-init-steps.yaml
@@ -0,0 +1,7 @@
+# All possible options and their defaults: https://github.com/zitadel/zitadel/blob/v2-alpha/cmd/adminn/setup/steps.yaml
+S3DefaultInstance:
+ Org:
+ Human:
+ # use the loginname root@zitadel.localhost
+ Username: 'root'
+ Password: 'RootPassword1!'
diff --git a/docs/docs/guides/installation/configure/example-zitadel-secrets.yaml b/docs/docs/guides/installation/configure/example-zitadel-secrets.yaml
new file mode 100644
index 0000000000..f46cb0d683
--- /dev/null
+++ b/docs/docs/guides/installation/configure/example-zitadel-secrets.yaml
@@ -0,0 +1,11 @@
+# All possible options and their defaults: https://github.com/zitadel/zitadel/blob/v2-alpha/cmd/defaults.yaml
+
+# If not using the docker compose example, adjust these values for connecting ZITADEL to your CockroachDB
+Database:
+ User:
+ # If the user doesn't exist already, it is created
+ Username: 'zitadel_user'
+ Password: 'Secret_DB_User_Password'
+AdminUser:
+ Username: 'root'
+ Password: ''
diff --git a/docs/docs/guides/installation/configure/example-zitadel-values-secrets.yaml b/docs/docs/guides/installation/configure/example-zitadel-values-secrets.yaml
new file mode 100644
index 0000000000..2475f0da34
--- /dev/null
+++ b/docs/docs/guides/installation/configure/example-zitadel-values-secrets.yaml
@@ -0,0 +1,16 @@
+# All possible options and their defaults: https://github.com/zitadel/zitadel/blob/v2-alpha/cmd/defaults.yaml
+zitadel:
+
+ masterkey: 'MasterkeyNeedsToHave32Characters'
+
+ secretConfig:
+
+ Database:
+ User:
+ # If the user doesn't exist already, it is created
+ Username: 'zitadel_user'
+ Password: 'Secret_DB_User_Password'
+
+ AdminUser:
+ Username: 'root'
+ Password: ''
diff --git a/docs/docs/guides/installation/configure/example-zitadel-values.yaml b/docs/docs/guides/installation/configure/example-zitadel-values.yaml
new file mode 100644
index 0000000000..9fc6ee6223
--- /dev/null
+++ b/docs/docs/guides/installation/configure/example-zitadel-values.yaml
@@ -0,0 +1,17 @@
+# All possible options and their defaults: https://github.com/zitadel/zitadel/blob/v2-alpha/cmd/defaults.yaml
+zitadel:
+ configmapConfig:
+ Log:
+ Level: 'info'
+
+ # Make ZITADEL accessible over HTTP, not HTTPS
+ ExternalSecure: false
+ ExternalDomain: localhost
+
+ # the configmap is also passed to the zitadel binary via the --steps flag
+ S3DefaultInstance:
+ Org:
+ Human:
+ # use the loginname root@zitadel.localhost
+ Username: 'root'
+ Password: 'RootPassword1!'
diff --git a/docs/docs/guides/installation/configure/helm.mdx b/docs/docs/guides/installation/configure/helm.mdx
new file mode 100644
index 0000000000..fbc5560b89
--- /dev/null
+++ b/docs/docs/guides/installation/configure/helm.mdx
@@ -0,0 +1,24 @@
+By default, the chart installs a secure ZITADEL and CockroachDB.
+The example files makes an insecure ZITADEL accessible by port forwarding the ZITADEL service to localhost.
+For more configuration options, [go to the chart repo descriptions](https://github.com/zitadel/zitadel-charts).
+For a secure installation with Docker Compose, [go to the loadbalancing example](../loadbalancing-example/loadbalancing-example)
+
+By executing the commands below, you will download the following files:
+- [example-zitadel-values.yaml](./example-zitadel-values.yaml)
+- [example-zitadel-values-secrets.yaml](./example-zitadel-values-secrets.yaml)
+
+```bash
+# Download and adjust the example configuration file containing standard configuration
+wget https://raw.githubusercontent.com/zitadel/zitadel/v2-alpha/docs/docs/guides/installation/configure/example-zitadel-values.yaml
+
+# Download and adjust the example configuration file containing secret configuration
+wget https://raw.githubusercontent.com/zitadel/zitadel/v2-alpha/docs/docs/guides/installation/configure/example-zitadel-values-secrets.yaml
+
+# Install an insecure zitadel release that works with localhost
+helm install --namespace zitadel --create-namespace my-zitadel zitadel/zitadel \
+ --values ./example-zitadel-values.yaml \
+ --values ./example-zitadel-values-secrets.yaml
+
+# Forward the ZITADEL service port to your local machine
+kubectl --namespace zitadel port-forward svc/my-zitadel 8080:80
+```
diff --git a/docs/docs/guides/installation/configure/linuxunix.mdx b/docs/docs/guides/installation/configure/linuxunix.mdx
new file mode 100644
index 0000000000..366fc006d2
--- /dev/null
+++ b/docs/docs/guides/installation/configure/linuxunix.mdx
@@ -0,0 +1,48 @@
+### Configure by Files
+
+By executing the commands below, you will download the following files:
+- [example-zitadel-config.yaml](./example-zitadel-config.yaml)
+- [example-zitadel-secrets.yaml](./example-zitadel-secrets.yaml)
+- [example-zitadel-init-steps.yaml](./example-zitadel-init-steps.yaml)
+
+```bash
+# Download and adjust the example configuration file containing standard configuration
+wget https://raw.githubusercontent.com/zitadel/zitadel/v2-alpha/docs/docs/guides/installation/configure/example-zitadel-config.yaml
+
+# Download and adjust the example configuration file containing secret configuration
+wget https://raw.githubusercontent.com/zitadel/zitadel/v2-alpha/docs/docs/guides/installation/configure/example-zitadel-secrets.yaml
+
+# Download and adjust the example configuration file containing database initialization configuration
+wget https://raw.githubusercontent.com/zitadel/zitadel/v2-alpha/docs/docs/guides/installation/configure/example-zitadel-init-steps.yaml
+
+# A single ZITADEL instance always needs the same 32 characters long masterkey
+# If you haven't done so already, you can generate a new one
+# The key must be passed as argument
+ZITADEL_MASTERKEY="$(tr -dc A-Za-z0-9
+Coming soon
diff --git a/docs/docs/guides/installation/custom-domain.md b/docs/docs/guides/installation/custom-domain.md
new file mode 100644
index 0000000000..3654a67282
--- /dev/null
+++ b/docs/docs/guides/installation/custom-domain.md
@@ -0,0 +1,35 @@
+---
+title: Custom Domain
+---
+
+# Run ZITADEL on a (Sub)domain of Your Choice
+
+This guide assumes you are already familiar with [configuring ZITADEL](./configure).
+
+You most probably need to configure these fields for making ZITADEL work on your custom domain.
+
+## Standard Config
+
+For security reasons, ZITADEL only serves requests sent to the expected protocol, host and port.
+If not using localhost as ExternalDomain, ExternalSecure must be true and you need to serve the ZITADEL console over HTTPS.
+
+```yaml
+ExternalSecure: true
+ExternalDomain: 'zitadel.my.domain'
+ExternalPort: 443
+```
+
+## Database Initialization Steps Config
+
+ZITADEL creates random subdomains for each instance created.
+However, for the default instance, this is most probably not the desired behavior.
+You can give the default instance a fixed custom domain here.
+
+```yaml
+S3DefaultInstance:
+ CustomDomain: 'zitadel.my.domain'
+```
+
+## Example
+
+Go to the [loadbalancing example with Traefik](./loadbalancing-example) for seeing a working example configuration.
diff --git a/docs/docs/guides/installation/get-started/compose.mdx b/docs/docs/guides/installation/get-started/compose.mdx
new file mode 100644
index 0000000000..5337960fbe
--- /dev/null
+++ b/docs/docs/guides/installation/get-started/compose.mdx
@@ -0,0 +1,11 @@
+The setup is tested against Docker version 20.10.17 and Docker Compose version v2.2.3
+
+By executing the commands below, you will download the file [docker-compose.yaml](./docker-compose.yaml)
+
+```bash
+# Download the docker compose example configuration. For example:
+wget https://raw.githubusercontent.com/zitadel/zitadel/v2-alpha/docs/docs/guides/installation/get-started/docker-compose.yaml
+
+# Run the database and application containers
+docker compose up --detach
+```
diff --git a/docs/docs/guides/installation/get-started/docker-compose.yaml b/docs/docs/guides/installation/get-started/docker-compose.yaml
new file mode 100644
index 0000000000..dee9c55a21
--- /dev/null
+++ b/docs/docs/guides/installation/get-started/docker-compose.yaml
@@ -0,0 +1,36 @@
+version: '3.8'
+
+services:
+ zitadel:
+ restart: 'always'
+ networks:
+ - 'zitadel'
+ image: 'ghcr.io/zitadel/zitadel:v2.0.0-v2-alpha.33-amd64'
+ command: 'start-from-init --masterkey "MasterkeyNeedsToHave32Characters" --tlsMode disabled'
+ environment:
+ - 'ZITADEL_DATABASE_HOST=db'
+ - 'ZITADEL_EXTERNALSECURE=false'
+ depends_on:
+ db:
+ condition: 'service_healthy'
+ ports:
+ - '8080:8080'
+
+ db:
+ restart: 'always'
+ networks:
+ - 'zitadel'
+ image: 'cockroachdb/cockroach:v22.1.0'
+ command: 'start-single-node --insecure'
+ healthcheck:
+ test: ["CMD", "curl", "-f", "http://localhost:8080/health?ready=1"]
+ interval: '10s'
+ timeout: '30s'
+ retries: 5
+ start_period: '20s'
+ ports:
+ - '9090:8080'
+ - '26257:26257'
+
+networks:
+ zitadel:
diff --git a/docs/docs/guides/installation/installation.mdx b/docs/docs/guides/installation/get-started/get-started.mdx
similarity index 62%
rename from docs/docs/guides/installation/installation.mdx
rename to docs/docs/guides/installation/get-started/get-started.mdx
index b1803aaf9b..9775c3edd9 100644
--- a/docs/docs/guides/installation/installation.mdx
+++ b/docs/docs/guides/installation/get-started/get-started.mdx
@@ -1,5 +1,5 @@
---
-title: Installation
+title: Get Started
---
import Tabs from "@theme/Tabs";
@@ -9,12 +9,15 @@ import MacOS from './macos.mdx'
import Windows from './windows.mdx'
import Compose from './compose.mdx'
import Helm from './helm.mdx'
-import Configuration from './configuration.mdx'
-import OpenLocal from './openlocal.mdx'
+import NextSelfHosted from './nextselfhosted.mdx'
# Run ZITADEL
Choose your platform and run ZITADEL with the most minimal configuration possible.
+For an easy self-hosted production setup, we recommend running ZITADEL on [Kubernetes](https://kubernetes.io/docs/home/), using our official [Helm](https://helm.sh/docs/) chart.
+By default, it runs a highly available ZITADEL instance along with a secure and highly available [CockroachDB](https://www.cockroachlabs.com/docs/stable/) instance.
+
+
@@ -33,23 +35,18 @@ Choose your platform and run ZITADEL with the most minimal configuration possibl
-
-
+
-
-
-
-
-
+
-
-
+
+
diff --git a/docs/docs/guides/installation/get-started/helm.mdx b/docs/docs/guides/installation/get-started/helm.mdx
new file mode 100644
index 0000000000..8a2f90ff5d
--- /dev/null
+++ b/docs/docs/guides/installation/get-started/helm.mdx
@@ -0,0 +1,21 @@
+Installation and configuration details are described in the [open source ZITADEL charts repo](https://github.com/zitadel/zitadel-charts).
+By default, the chart installs a secure and highly available ZITADEL instance.
+For running an easily testable, insecure, non-HA ZITADEL instance, run the following commands.
+
+```bash
+# Add the helm repository
+helm repo add zitadel https://charts.zitadel.com
+
+# Install an insecure zitadel release that works with localhost
+helm install --namespace zitadel --create-namespace my-zitadel zitadel/zitadel \
+ --set zitadel.masterkey="MasterkeyNeedsToHave32Characters" \
+ --set zitadel.configmapConfig.ExternalDomain="localhost" \
+ --set zitadel.configmapConfig.ExternalSecure=false \
+ --set zitadel.secretConfig.Database.User.Password="a-zitadel-db-user-password"
+ --set replicaCount=1 \
+ --set cockroachdb.single-node=true \
+ --set cockroachdb.statefulset.replicas=1
+
+# Forward the ZITADEL service port to your local machine
+kubectl port-forward svc/my-zitadel 8080:80
+```
diff --git a/docs/docs/guides/installation/get-started/linux.mdx b/docs/docs/guides/installation/get-started/linux.mdx
new file mode 100644
index 0000000000..292c7acb4b
--- /dev/null
+++ b/docs/docs/guides/installation/get-started/linux.mdx
@@ -0,0 +1,17 @@
+## Download The CockroachDB binary
+
+Download a `cockroach` binary as described [in the CockroachDB docs](https://www.cockroachlabs.com/docs/v22.1/install-cockroachdb).
+ZITADEL is tested against CockroachDB v22.1.0 and Ubuntu 20.04.
+
+## Run CockroachDB and ZITADEL
+
+```bash
+# Run a CockroachDB instance
+cockroach start-single-node --insecure --background --http-addr :9090
+
+# Download the zitadel binary
+curl -s https://api.github.com/repos/zitadel/zitadel/releases/tags/v2.0.0-v2-alpha.24 | grep "browser_download_url.*zitadel_Linux_$(uname -i).tar.gz" | cut -d '"' -f 4 | xargs wget -qO - | sudo tar --extract --gzip --overwrite --directory /usr/local/bin zitadel && sudo chown $(id -u):$(id -g) /usr/local/bin/zitadel
+
+# Run the zitadel binary
+ZITADEL_EXTERNALSECURE=false zitadel start-from-init --masterkey "MasterkeyNeedsToHave32Characters" --tlsMode disabled
+```
diff --git a/docs/docs/guides/installation/get-started/macos.mdx b/docs/docs/guides/installation/get-started/macos.mdx
new file mode 100644
index 0000000000..ae80407c5d
--- /dev/null
+++ b/docs/docs/guides/installation/get-started/macos.mdx
@@ -0,0 +1,32 @@
+## Download The CockroachDB binary
+
+Download a `cockroach` binary as described [in the CockroachDB docs](https://www.cockroachlabs.com/docs/v22.1/install-cockroachdb).
+ZITADEL is tested against CockroachDB v22.1.0.
+
+## Run CockroachDB and ZITADEL
+
+Run a CockroachDB instance
+
+```bash
+cockroach start-single-node --insecure --background --http-addr :9090
+```
+
+# Download and Install ZITADEL
+
+Either use `Homebrew` ...
+
+```bash
+brew install zitadel/tap/zitadel
+```
+
+... or download the binary from GitHub
+
+```bash
+export MY_ARCHITECTURE="arm64 or amd64 depeding on your mac"
+curl -s https://api.github.com/repos/zitadel/zitadel/releases/tags/v2.0.0-v2-alpha.24 | grep "browser_download_url.*zitadel_Darwin_${MY_ARCHITECTURE}.tar.gz" | cut -d '"' -f 4 | xargs wget -qO - | sudo tar --extract --gzip --overwrite --directory /usr/local/bin zitadel && sudo chown $(id -u):$(id -g) /usr/local/bin/zitadel
+```
+
+Run ZITADEL
+
+```bash
+ZITADEL_EXTERNALSECURE=false zitadel start-from-init --masterkey "MasterkeyNeedsToHave32Characters" --tlsMode disabled
diff --git a/docs/docs/guides/installation/get-started/nextselfhosted.mdx b/docs/docs/guides/installation/get-started/nextselfhosted.mdx
new file mode 100644
index 0000000000..65ca1c497a
--- /dev/null
+++ b/docs/docs/guides/installation/get-started/nextselfhosted.mdx
@@ -0,0 +1,13 @@
+Open your favorite internet browser and navigate to [http://localhost:8080/ui/console](http://localhost:8080/ui/console).
+This is the default IAM admin users login:
+- **username**: *zitadel-admin@zitadel.localhost*
+- **password**: *Password1!*
+
+## What's next
+
+For running a production grade ZITADEL instance in your environment, go on with the [configure ZITADEL](./configure) section.
+
+:::caution
+
+
+The ZITADEL management console [requires end-to-end HTTP/2 support](./http2-support)
diff --git a/docs/docs/guides/installation/get-started/windows.mdx b/docs/docs/guides/installation/get-started/windows.mdx
new file mode 100644
index 0000000000..f2074b0c3e
--- /dev/null
+++ b/docs/docs/guides/installation/get-started/windows.mdx
@@ -0,0 +1,2 @@
+
+Coming soon
diff --git a/docs/docs/guides/installation/helm.mdx b/docs/docs/guides/installation/helm.mdx
deleted file mode 100644
index fe4d5d354b..0000000000
--- a/docs/docs/guides/installation/helm.mdx
+++ /dev/null
@@ -1 +0,0 @@
-Coming soon
\ No newline at end of file
diff --git a/docs/docs/guides/installation/http2-support.md b/docs/docs/guides/installation/http2-support.md
new file mode 100644
index 0000000000..ba2cc5c627
--- /dev/null
+++ b/docs/docs/guides/installation/http2-support.md
@@ -0,0 +1,10 @@
+---
+title: HTTP/2 Support
+---
+
+The ZITADEL console (prefix `/ui/console`) uses [gRPC-Web](https://github.com/grpc/grpc-web) for its API calls.
+The ZITADEL backend service accepts gRPC-Web requests and translates them into real gRPC calls to itself.
+Because ZITADEL accepts gRPC-Web and translates it to gRPC itself, your reverse proxy doesn't need to be able to support gRPC or gRPC-Web.
+However, as gRPC requires HTTP/2, your reverse proxy is required to send and receive downstream and upstream HTTP/2 traffic.
+
+Go to the [loadbalancing example with Traefik](./loadbalancing-example) for seeing a working example configuration.
diff --git a/docs/docs/guides/installation/linux.mdx b/docs/docs/guides/installation/linux.mdx
deleted file mode 100644
index c315eeea66..0000000000
--- a/docs/docs/guides/installation/linux.mdx
+++ /dev/null
@@ -1,31 +0,0 @@
-## Download The CockroachDB binary
-
-Download a `cockroach` binary as described [here](https://www.cockroachlabs.com/docs/v22.1/install-cockroachdb).
-ZITADEL is tested against CockroachDB v22.1.0.
-
-## Run CockroachDB and ZITADEL
-
-Run a CockroachDB instance
-
-```bash
-cockroach start-single-node --insecure --background --http-addr :9090
-```
-
-Configure your environment and generate a master encryption key
-
-```bash
-export ZITADEL_EXTERNALDOMAIN=localhost
-export ZITADEL_DEFAULTINSTANCE_CUSTOMDOMAIN=localhost
-```
-
-Download the zitadel binary
-
-```bash
-curl -s https://api.github.com/repos/zitadel/zitadel/releases/tags/v2.0.0-v2-alpha.33 | grep "browser_download_url.*zitadel_.*_linux_$(dpkg --print-architecture)" | cut -d '"' -f 4 | sudo wget -i - -O /usr/local/bin/zitadel && sudo chmod +x /usr/local/bin/zitadel && sudo chown $(id -u):$(id -g) /usr/local/bin/zitadel
-```
-
-Run the database and application containers
-
-```bash
-zitadel start-from-init --tlsMode disabled --masterkey "MasterkeyNeedsToHave32Characters"
-```
diff --git a/docs/docs/guides/installation/loadbalancing-example/docker-compose.yaml b/docs/docs/guides/installation/loadbalancing-example/docker-compose.yaml
new file mode 100644
index 0000000000..8e76dd1a74
--- /dev/null
+++ b/docs/docs/guides/installation/loadbalancing-example/docker-compose.yaml
@@ -0,0 +1,76 @@
+version: '3.8'
+services:
+
+ traefik:
+ networks:
+ - 'zitadel'
+ image: "traefik:v2.7"
+ ports:
+ - "80:80"
+ - "443:443"
+ volumes:
+ - "./traefik.yaml:/etc/traefik/traefik.yaml"
+
+ zitadel:
+ restart: 'always'
+ networks:
+ - 'zitadel'
+ image: 'ghcr.io/zitadel/zitadel:v2.0.0-v2-alpha.33-amd64'
+ command: 'start-from-init --config /example-zitadel-config.yaml --config /example-zitadel-secrets.yaml --steps /example-zitadel-init-steps.yaml --masterkey "${ZITADEL_MASTERKEY}" --tlsMode external'
+ depends_on:
+ chown:
+ condition: 'service_completed_successfully'
+
+ volumes:
+ - './example-zitadel-config.yaml:/example-zitadel-config.yaml:ro'
+ - './example-zitadel-secrets.yaml:/example-zitadel-secrets.yaml:ro'
+ - './example-zitadel-init-steps.yaml:/example-zitadel-init-steps.yaml:ro'
+ - 'zitadel-certs:/crdb-certs:ro'
+
+ chown:
+ image: 'cockroachdb/cockroach:v22.1.0'
+ entrypoint: [ '/bin/bash', '-c' ]
+ command: [ 'cp /certs/ca.crt /zitadel-certs/ && cp /certs/client.root.crt /zitadel-certs/ && cp /certs/client.root.key /zitadel-certs/ && cp /certs/client.zitadel_user.crt /zitadel-certs/ && cp /certs/client.zitadel_user.key /zitadel-certs/ && chown 1000:1000 /zitadel-certs/* && chmod 0400 /zitadel-certs/*' ]
+ volumes:
+ - 'certs:/certs:ro'
+ - 'zitadel-certs:/zitadel-certs:rw'
+ depends_on:
+ client-certs:
+ condition: 'service_completed_successfully'
+
+ client-certs:
+ image: 'cockroachdb/cockroach:v22.1.0'
+ command: 'cert create-client --certs-dir /certs/ --ca-key /certs/ca.key zitadel_user'
+ restart: 'on-failure'
+ volumes:
+ - 'certs:/certs:rw'
+ depends_on:
+ my-cockroach-db:
+ condition: 'service_healthy'
+
+ my-cockroach-db:
+ restart: 'always'
+ networks:
+ - 'zitadel'
+ image: 'cockroachdb/cockroach:v22.1.0'
+ command: 'start-single-node --advertise-addr my-cockroach-db'
+ healthcheck:
+ test: ["CMD", "curl", "-f", "http://localhost:8080/health?ready=1"]
+ interval: '10s'
+ timeout: '30s'
+ retries: 5
+ start_period: '20s'
+ ports:
+ - '9090:8080'
+ - '26257:26257'
+ volumes:
+ - 'certs:/cockroach/certs:rw'
+ - 'data:/cockroach/cockroach-data:rw'
+
+networks:
+ zitadel:
+
+volumes:
+ certs:
+ zitadel-certs:
+ data:
diff --git a/docs/docs/guides/installation/loadbalancing-example/example-zitadel-config.yaml b/docs/docs/guides/installation/loadbalancing-example/example-zitadel-config.yaml
new file mode 100644
index 0000000000..54ee71ebff
--- /dev/null
+++ b/docs/docs/guides/installation/loadbalancing-example/example-zitadel-config.yaml
@@ -0,0 +1,24 @@
+# All possible options and their defaults: https://github.com/zitadel/zitadel/blob/v2-alpha/cmd/defaults.yaml
+Log:
+ Level: 'info'
+
+# Make ZITADEL accessible over HTTP, not HTTPS
+ExternalSecure: true
+ExternalDomain: my.domain
+ExternalPort: 443
+
+# If not using the docker compose example, adjust these values for connecting ZITADEL to your CockroachDB
+Database:
+ Host: 'my-cockroach-db'
+ User:
+ SSL:
+ Mode: 'verify-full'
+ RootCert: "/crdb-certs/ca.crt"
+ Cert: "/crdb-certs/client.zitadel_user.crt"
+ Key: "/crdb-certs/client.zitadel_user.key"
+AdminUser:
+ SSL:
+ Mode: 'verify-full'
+ RootCert: "/crdb-certs/ca.crt"
+ Cert: "/crdb-certs/client.root.crt"
+ Key: "/crdb-certs/client.root.key"
diff --git a/docs/docs/guides/installation/loadbalancing-example/example-zitadel-init-steps.yaml b/docs/docs/guides/installation/loadbalancing-example/example-zitadel-init-steps.yaml
new file mode 100644
index 0000000000..bf58cb7fa6
--- /dev/null
+++ b/docs/docs/guides/installation/loadbalancing-example/example-zitadel-init-steps.yaml
@@ -0,0 +1,9 @@
+# All possible options and their defaults: https://github.com/zitadel/zitadel/blob/v2-alpha/cmd/adminn/setup/steps.yaml
+S3DefaultInstance:
+ CustomDomain: my.domain
+ Org:
+ Name: 'My Org'
+ Human:
+ # use the loginname root@my-org.my.domain
+ Username: 'root'
+ Password: 'RootPassword1!'
diff --git a/docs/docs/guides/installation/loadbalancing-example/example-zitadel-secrets.yaml b/docs/docs/guides/installation/loadbalancing-example/example-zitadel-secrets.yaml
new file mode 100644
index 0000000000..f46cb0d683
--- /dev/null
+++ b/docs/docs/guides/installation/loadbalancing-example/example-zitadel-secrets.yaml
@@ -0,0 +1,11 @@
+# All possible options and their defaults: https://github.com/zitadel/zitadel/blob/v2-alpha/cmd/defaults.yaml
+
+# If not using the docker compose example, adjust these values for connecting ZITADEL to your CockroachDB
+Database:
+ User:
+ # If the user doesn't exist already, it is created
+ Username: 'zitadel_user'
+ Password: 'Secret_DB_User_Password'
+AdminUser:
+ Username: 'root'
+ Password: ''
diff --git a/docs/docs/guides/installation/loadbalancing-example/loadbalancing-example.md b/docs/docs/guides/installation/loadbalancing-example/loadbalancing-example.md
new file mode 100644
index 0000000000..b8a055e24b
--- /dev/null
+++ b/docs/docs/guides/installation/loadbalancing-example/loadbalancing-example.md
@@ -0,0 +1,50 @@
+---
+title: Load Balancing Example
+---
+
+With this example configuration, you create a near production environment for ZITADEL with [Docker Compose](https://docs.docker.com/compose/).
+
+The stack consists of three long-running containers:
+- A [Traefik](https://doc.traefik.io/traefik/) reverse proxy with upstream HTTP/2 enabled, issuing a self-signed TLS certificate.
+- A secure ZITADEL container configured for a custom domain. As we terminate TLS with Traefik, we configure ZITADEL for `--tlsMode external`.
+- A secure [CockroachDB](https://www.cockroachlabs.com/docs/stable/).
+
+The setup is tested against Docker version 20.10.17 and Docker Compose version v2.2.3
+
+By executing the commands below, you will download the following files:
+- [docker-compose.yaml](./docker-compose.yaml)
+- [example-zitadel-config.yaml](./example-zitadel-config.yaml)
+- [example-zitadel-secrets.yaml](./example-zitadel-secrets.yaml)
+- [example-zitadel-init-steps.yaml](./example-zitadel-init-steps.yaml)
+
+```bash
+# Download the docker compose example configuration. For example:
+wget https://raw.githubusercontent.com/zitadel/zitadel/v2-alpha/docs/docs/guides/installation/loadbalancing-example/docker-compose.yaml
+
+# Download and adjust the example configuration file containing standard configuration
+wget https://raw.githubusercontent.com/zitadel/zitadel/v2-alpha/docs/docs/guides/installation/loadbalancing-example/example-zitadel-config.yaml
+
+# Download and adjust the example configuration file containing secret configuration
+wget https://raw.githubusercontent.com/zitadel/zitadel/v2-alpha/docs/docs/guides/installation/loadbalancing-example/example-zitadel-secrets.yaml
+
+# Download and adjust the example configuration file containing database initialization configuration
+wget https://raw.githubusercontent.com/zitadel/zitadel/v2-alpha/docs/docs/guides/installation/loadbalancing-example/example-zitadel-init-steps.yaml
+
+# A single ZITADEL instance always needs the same 32 characters long masterkey
+# If you haven't done so already, you can generate a new one.
+# For example:
+export ZITADEL_MASTERKEY="$(tr -dc A-Za-z0-9 my-org.my.domain*
+- **password**: *RootPassword1!*
+
+Read more about [the login process](../../manuals/user-login).
diff --git a/docs/docs/guides/installation/loadbalancing-example/traefik.yaml b/docs/docs/guides/installation/loadbalancing-example/traefik.yaml
new file mode 100644
index 0000000000..f8dbc78d34
--- /dev/null
+++ b/docs/docs/guides/installation/loadbalancing-example/traefik.yaml
@@ -0,0 +1,63 @@
+entrypoints:
+ web:
+ address: ":80"
+
+ websecure:
+ address: ":443"
+
+tls:
+ stores:
+ default:
+ # generates self-signed certificates
+ defaultCertificate:
+
+providers:
+ file:
+ filename: /etc/traefik/traefik.yaml
+
+http:
+
+ middlewares:
+ zitadel:
+ headers:
+ isDevelopment: false
+ allowedHosts:
+ - 'my.domain'
+ redirect-to-https:
+ redirectScheme:
+ scheme: https
+ port: 443
+ permanent: true
+
+ routers:
+ # Redirect HTTP to HTTPS
+ router0:
+ entryPoints:
+ - web
+ middlewares:
+ - redirect-to-https
+ rule: 'HostRegexp(`my.domain`, `{subdomain:[a-z]+}.my.domain`)'
+ service: zitadel
+ # The actual ZITADEL router
+ router1:
+ entryPoints:
+ - websecure
+ service: zitadel
+ middlewares:
+ - zitadel
+ rule: 'HostRegexp(`my.domain`, `{subdomain:[a-z]+}.my.domain`)'
+ tls:
+ domains:
+ - main: "my.domain"
+ sans:
+ - "*.my.domain"
+ - "my.domain"
+
+ # Add the service
+ services:
+ zitadel:
+ loadBalancer:
+ servers:
+ # h2c is the scheme for unencrypted HTTP/2
+ - url: h2c://zitadel:8080
+ passHostHeader: true
diff --git a/docs/docs/guides/installation/macos.mdx b/docs/docs/guides/installation/macos.mdx
deleted file mode 100644
index db4e197ab4..0000000000
--- a/docs/docs/guides/installation/macos.mdx
+++ /dev/null
@@ -1,40 +0,0 @@
-## Download The CockroachDB binary
-
-Download a `cockroach` binary as described [here](https://www.cockroachlabs.com/docs/v22.1/install-cockroachdb).
-ZITADEL is tested against CockroachDB v22.1.0.
-
-## Run CockroachDB and ZITADEL
-
-Run a CockroachDB instance
-
-```bash
-cockroach start-single-node --insecure --background --http-addr :9090
-```
-
-Configure your environment and generate a master encryption key
-
-```bash
-export ZITADEL_EXTERNALDOMAIN=localhost
-export ZITADEL_DEFAULTINSTANCE_CUSTOMDOMAIN=localhost
-export MY_ARCHITECTURE="arm64 or amd64 depeding on your mac"
-```
-
-# Download and Install ZITADEL
-
-Either use `Homebrew` ...
-
-```bash
-brew install zitadel/tap/zitadel
-```
-
-... or download the binary from GitHub
-
-```bash
-curl -s https://api.github.com/repos/zitadel/zitadel/releases/tags/v2.0.0-v2-alpha.33 | grep "browser_download_url.*zitadel_.*_darwin_${MY_ARCHITECTURE}" | cut -d '"' -f 4 | sudo wget -i - -O /usr/local/bin/zitadel && sudo chmod +x /usr/local/bin/zitadel && sudo chown $(id -u):$(id -g) /usr/local/bin/zitadel
-```
-
-Run ZITADEL
-
-```bash
-zitadel start-from-init --tlsMode disabled --masterkey "MasterkeyNeedsToHave32Characters"
-```
diff --git a/docs/docs/guides/installation/openlocal.mdx b/docs/docs/guides/installation/openlocal.mdx
deleted file mode 100644
index b19aec173a..0000000000
--- a/docs/docs/guides/installation/openlocal.mdx
+++ /dev/null
@@ -1,6 +0,0 @@
-Open your favorite internet browser and navigate to [http://localhost:8080/ui/console](http://localhost:8080/ui/console).
-If you didn't configure something else, this is the default IAM admin users login:
-- **username**: *zitadel-admin@zitadel.localhost*
-- **password**: *Password1!*
-
-If you configured a different username, replace the substring zitadel-admin above by the username you configured.
diff --git a/docs/docs/guides/installation/windows.mdx b/docs/docs/guides/installation/windows.mdx
deleted file mode 100644
index fe4d5d354b..0000000000
--- a/docs/docs/guides/installation/windows.mdx
+++ /dev/null
@@ -1 +0,0 @@
-Coming soon
\ No newline at end of file
diff --git a/docs/sidebars.js b/docs/sidebars.js
index 5318f7c4b7..825b4861a4 100644
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -36,7 +36,18 @@ module.exports = {
],
guides: [
"guides/overview",
- "guides/installation/installation",
+ {
+ type: "category",
+ label: "Install ZITADEL",
+ collapsed: false,
+ items: [
+ "guides/installation/get-started/get-started",
+ "guides/installation/configure/configure",
+ "guides/installation/custom-domain",
+ "guides/installation/http2-support",
+ "guides/installation/loadbalancing-example/loadbalancing-example",
+ ],
+ },
{
type: "category",
label: "Get to know ZITADEL",
diff --git a/example-zitadel-config.yaml b/example-zitadel-config.yaml
new file mode 120000
index 0000000000..bc31063777
--- /dev/null
+++ b/example-zitadel-config.yaml
@@ -0,0 +1 @@
+/tmp/example-zitadel-config.yaml
\ No newline at end of file