docs(installation): improve guides (#3817)

* split config descriptions

* install and configure

* custom domains

* typo

* remove comments

* try compose with secure crdb

* secure crdb with compose

* describe ExternalSecure restriction

* add near production example

* add login credentials

* fix configure compose

* make the docs more transparent

* name archive amd64

* Revert "name archive amd64"

This reverts commit 0d4dae551b47e6bc7584a27a05f290ae92648966.

* fix download url

* extract archives

* fix dawin download

* fix start zitadel commands

* add helm installation docs

* remove windows

* make downloaded files description friendlier

* link to github raw

* link login process

* remove healthcheck from compose

* remove compose healthchecks

* use --tlsMode external for lb example

* uname -i

* disable tls mode locally

* Update docs/docs/guides/installation/get-started/macos.mdx

Co-authored-by: Fabi <38692350+hifabienne@users.noreply.github.com>

Co-authored-by: Fabi <38692350+hifabienne@users.noreply.github.com>
This commit is contained in:
Elio Bischof 2022-06-28 13:36:59 +02:00 committed by GitHub
parent fb0f29aa32
commit 6dd4af01bf
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
37 changed files with 754 additions and 187 deletions

View File

@ -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:

View File

@ -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
```

View File

@ -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"
```

View File

@ -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 </dev/urandom | head -c 32)"
# Run the database and application containers
docker compose up --detach
```

View File

@ -0,0 +1,76 @@
---
title: Configure
---
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
import LinuxUnix from './linuxunix.mdx'
import Windows from './windows.mdx'
import Compose from './compose.mdx'
import Helm from './helm.mdx'
# Configure ZITADEL
This guide assumes you are already familiar with [running ZITADEL with the most minimal configuration possible](./get-started).
## Configuration Files
### Runtime Configuration
See a description of all possible _runtime configuration_ options with their defaults [in the source code](https://github.com/zitadel/zitadel/blob/v2-alpha/cmd/defaults.yaml).
The `zitadel` binary expects the `--config` flag for this configuration.
### Database Initialization
Apart from these options, ZITADEL uses a [different configuration](https://github.com/zitadel/zitadel/blob/v2-alpha/cmd/admin/setup/steps.yaml) for _database initialization steps_.
The `zitadel` binary expects the `--steps` flag for this configuration.
### Split Configuration
ZITADEL merges multiple configurations passed via multiple `--config` and/or multiple `--steps` flags.
This is especially useful, if you want to treat secret configuration files differently from standard configuration.
For example, you can check configuration with information like the database hostname in to git.
Other configration that contains information like your databases admin username and password, you can hand to a secret manager.
## Environment variables
All configuration properties are also configurable via environemnt 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, make sure the ZITADEL binary runtime has the variables *ZITADEL_S3DEFAULTINSTANCE_ORG_HUMAN_USERNAME* and *ZITADEL_S3DEFAULTINSTANCE_ORG_HUMAN_PASSWORD* set.
## Passing the configuration
<Tabs
groupId="installation-target"
default="linux"
values={[
{'label': 'Linux', 'value': 'linux'},
{'label': 'Linux and Unix', 'value': 'linuxunix'},
{'label': 'Docker Compose', 'value': 'compose'},
{'label': 'Kubernetes (Helm)', 'value': 'k8s'}
]}
>
<TabItem value="linuxunix">
<LinuxUnix/>
</TabItem>
<TabItem value="compose">
<Compose/>
</TabItem>
<TabItem value="k8s">
<Helm/>
</TabItem>
</Tabs>
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@<span></span>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
<!-- TODO: Better mark the link in the UI -->
The ZITADEL management console [requires end-to-end HTTP/2 support](./http2-support)

View File

@ -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:

View File

@ -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"

View File

@ -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!'

View File

@ -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: ''

View File

@ -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: ''

View File

@ -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!'

View File

@ -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
```

View File

@ -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 </dev/urandom | head -c 32)"
# Pass zitadel configuration by configuration files
zitadel start-from-init \
--config ./example-zitadel-config.yaml \
--config ./example-zitadel-secrets.yaml \
--steps ./example-zitadel-init-steps.yaml \
--masterkey "${ZITADEL_MASTERKEY}"
```
### Configure by Environment Variables
```bash
# Set runtime environment variables
export ZITADEL_DATABASE_HOST="my.database"
export ZITADEL_DATABASE_USER_USERNAME="my_zitadel_db_user"
export ZITADEL_DATABASE_USER_PASSWORD="Secret_DB_User_Password"
export ZITADEL_S3DEFAULTINSTANCE_ORG_HUMAN_USERNAME="root"
export ZITADEL_S3DEFAULTINSTANCE_ORG_HUMAN_PASSWORD="RootPassword1!"
# 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
export ZITADEL_MASTERKEY="$(tr -dc A-Za-z0-9 </dev/urandom | head -c 32)"
# Let the zitadel binary read configuration from environment variables
zitadel admin start-from-init --masterkey "${ZITADEL_MASTERKEY}"
```

View File

@ -0,0 +1,2 @@
<!-- TODO: Content -->
Coming soon

View File

@ -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.

View File

@ -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
```

View File

@ -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:

View File

@ -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.
<!-- TODO: Destroy -->
<Tabs
groupId="installation-target"
@ -23,9 +26,8 @@ Choose your platform and run ZITADEL with the most minimal configuration possibl
{'label': 'SaaS', 'value': 'saas'},
{'label': 'Linux', 'value': 'linux'},
{'label': 'MacOS', 'value': 'macos'},
{'label': 'Windows', 'value': 'windows'},
{'label': 'Docker Compose', 'value': 'compose'},
{'label': 'Kubernetes', 'value': 'k8s'}
{'label': 'Kubernetes (Helm)', 'value': 'k8s'}
]}
>
<TabItem value="saas">
@ -33,23 +35,18 @@ Choose your platform and run ZITADEL with the most minimal configuration possibl
</TabItem>
<TabItem value="linux">
<Linux/>
<Configuration/>
<OpenLocal/>
<NextSelfHosted/>
</TabItem>
<TabItem value="macos">
<MacOS/>
<Configuration/>
<OpenLocal/>
</TabItem>
<TabItem value="windows">
<Windows/>
<NextSelfHosted/>
</TabItem>
<TabItem value="compose">
<Compose/>
<Configuration/>
<OpenLocal/>
<NextSelfHosted/>
</TabItem>
<TabItem value="k8s">
<Helm/>
<NextSelfHosted/>
</TabItem>
</Tabs>

View File

@ -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
```

View File

@ -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
```

View File

@ -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

View File

@ -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@<span></span>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
<!-- TODO: Better mark the link in the UI -->
The ZITADEL management console [requires end-to-end HTTP/2 support](./http2-support)

View File

@ -0,0 +1,2 @@
<!-- TODO: Content -->
Coming soon

View File

@ -1 +0,0 @@
Coming soon

View File

@ -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.

View File

@ -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"
```

View File

@ -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:

View File

@ -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"

View File

@ -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!'

View File

@ -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: ''

View File

@ -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 </dev/urandom | head -c 32)"
# Run the database and application containers
docker compose up --detach
```
Make `127.0.0.1` available at `my.domain`. For example, this can be achived with an entry `127.0.1.1 my.domain` in the `/etc/hosts` file.
Open your favorite internet browser at [https://my.domain/ui/console/](https://my.domain/ui/console/).
You can safely proceed, if your browser warns you about the insecure self-signed TLS certificate.
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@<span></span>my-org.my.domain*
- **password**: *RootPassword1!*
Read more about [the login process](../../manuals/user-login).

View File

@ -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

View File

@ -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"
```

View File

@ -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@<span></span>zitadel.localhost*
- **password**: *Password1!*
If you configured a different username, replace the substring zitadel-admin above by the username you configured.

View File

@ -1 +0,0 @@
Coming soon

View File

@ -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",

1
example-zitadel-config.yaml Symbolic link
View File

@ -0,0 +1 @@
/tmp/example-zitadel-config.yaml