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