mirror of
https://github.com/zitadel/zitadel.git
synced 2025-01-07 23:07:45 +00:00
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
GitHub
parent
fb0f29aa32
commit
6dd4af01bf
@ -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:
|
|
||||||
@ -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
|
|
||||||
```
|
|
||||||
@ -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"
|
|
||||||
```
|
|
||||||
29
docs/docs/guides/installation/configure/compose.mdx
Normal file
29
docs/docs/guides/installation/configure/compose.mdx
Normal 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
|
||||||
|
```
|
||||||
76
docs/docs/guides/installation/configure/configure.mdx
Normal file
76
docs/docs/guides/installation/configure/configure.mdx
Normal 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)
|
||||||
68
docs/docs/guides/installation/configure/docker-compose.yaml
Normal file
68
docs/docs/guides/installation/configure/docker-compose.yaml
Normal 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:
|
||||||
@ -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"
|
||||||
@ -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!'
|
||||||
@ -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: ''
|
||||||
@ -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: ''
|
||||||
@ -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!'
|
||||||
24
docs/docs/guides/installation/configure/helm.mdx
Normal file
24
docs/docs/guides/installation/configure/helm.mdx
Normal 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
|
||||||
|
```
|
||||||
48
docs/docs/guides/installation/configure/linuxunix.mdx
Normal file
48
docs/docs/guides/installation/configure/linuxunix.mdx
Normal 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}"
|
||||||
|
```
|
||||||
2
docs/docs/guides/installation/configure/windows.mdx
Normal file
2
docs/docs/guides/installation/configure/windows.mdx
Normal file
@ -0,0 +1,2 @@
|
|||||||
|
<!-- TODO: Content -->
|
||||||
|
Coming soon
|
||||||
35
docs/docs/guides/installation/custom-domain.md
Normal file
35
docs/docs/guides/installation/custom-domain.md
Normal 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.
|
||||||
11
docs/docs/guides/installation/get-started/compose.mdx
Normal file
11
docs/docs/guides/installation/get-started/compose.mdx
Normal 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
|
||||||
|
```
|
||||||
@ -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:
|
||||||
@ -1,5 +1,5 @@
|
|||||||
---
|
---
|
||||||
title: Installation
|
title: Get Started
|
||||||
---
|
---
|
||||||
|
|
||||||
import Tabs from "@theme/Tabs";
|
import Tabs from "@theme/Tabs";
|
||||||
@ -9,12 +9,15 @@ import MacOS from './macos.mdx'
|
|||||||
import Windows from './windows.mdx'
|
import Windows from './windows.mdx'
|
||||||
import Compose from './compose.mdx'
|
import Compose from './compose.mdx'
|
||||||
import Helm from './helm.mdx'
|
import Helm from './helm.mdx'
|
||||||
import Configuration from './configuration.mdx'
|
import NextSelfHosted from './nextselfhosted.mdx'
|
||||||
import OpenLocal from './openlocal.mdx'
|
|
||||||
|
|
||||||
# Run ZITADEL
|
# Run ZITADEL
|
||||||
|
|
||||||
Choose your platform and run ZITADEL with the most minimal configuration possible.
|
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
|
<Tabs
|
||||||
groupId="installation-target"
|
groupId="installation-target"
|
||||||
@ -23,9 +26,8 @@ Choose your platform and run ZITADEL with the most minimal configuration possibl
|
|||||||
{'label': 'SaaS', 'value': 'saas'},
|
{'label': 'SaaS', 'value': 'saas'},
|
||||||
{'label': 'Linux', 'value': 'linux'},
|
{'label': 'Linux', 'value': 'linux'},
|
||||||
{'label': 'MacOS', 'value': 'macos'},
|
{'label': 'MacOS', 'value': 'macos'},
|
||||||
{'label': 'Windows', 'value': 'windows'},
|
|
||||||
{'label': 'Docker Compose', 'value': 'compose'},
|
{'label': 'Docker Compose', 'value': 'compose'},
|
||||||
{'label': 'Kubernetes', 'value': 'k8s'}
|
{'label': 'Kubernetes (Helm)', 'value': 'k8s'}
|
||||||
]}
|
]}
|
||||||
>
|
>
|
||||||
<TabItem value="saas">
|
<TabItem value="saas">
|
||||||
@ -33,23 +35,18 @@ Choose your platform and run ZITADEL with the most minimal configuration possibl
|
|||||||
</TabItem>
|
</TabItem>
|
||||||
<TabItem value="linux">
|
<TabItem value="linux">
|
||||||
<Linux/>
|
<Linux/>
|
||||||
<Configuration/>
|
<NextSelfHosted/>
|
||||||
<OpenLocal/>
|
|
||||||
</TabItem>
|
</TabItem>
|
||||||
<TabItem value="macos">
|
<TabItem value="macos">
|
||||||
<MacOS/>
|
<MacOS/>
|
||||||
<Configuration/>
|
<NextSelfHosted/>
|
||||||
<OpenLocal/>
|
|
||||||
</TabItem>
|
|
||||||
<TabItem value="windows">
|
|
||||||
<Windows/>
|
|
||||||
</TabItem>
|
</TabItem>
|
||||||
<TabItem value="compose">
|
<TabItem value="compose">
|
||||||
<Compose/>
|
<Compose/>
|
||||||
<Configuration/>
|
<NextSelfHosted/>
|
||||||
<OpenLocal/>
|
|
||||||
</TabItem>
|
</TabItem>
|
||||||
<TabItem value="k8s">
|
<TabItem value="k8s">
|
||||||
<Helm/>
|
<Helm/>
|
||||||
|
<NextSelfHosted/>
|
||||||
</TabItem>
|
</TabItem>
|
||||||
</Tabs>
|
</Tabs>
|
||||||
21
docs/docs/guides/installation/get-started/helm.mdx
Normal file
21
docs/docs/guides/installation/get-started/helm.mdx
Normal 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
|
||||||
|
```
|
||||||
17
docs/docs/guides/installation/get-started/linux.mdx
Normal file
17
docs/docs/guides/installation/get-started/linux.mdx
Normal 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
|
||||||
|
```
|
||||||
32
docs/docs/guides/installation/get-started/macos.mdx
Normal file
32
docs/docs/guides/installation/get-started/macos.mdx
Normal 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
|
||||||
13
docs/docs/guides/installation/get-started/nextselfhosted.mdx
Normal file
13
docs/docs/guides/installation/get-started/nextselfhosted.mdx
Normal 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)
|
||||||
2
docs/docs/guides/installation/get-started/windows.mdx
Normal file
2
docs/docs/guides/installation/get-started/windows.mdx
Normal file
@ -0,0 +1,2 @@
|
|||||||
|
<!-- TODO: Content -->
|
||||||
|
Coming soon
|
||||||
@ -1 +0,0 @@
|
|||||||
Coming soon
|
|
||||||
10
docs/docs/guides/installation/http2-support.md
Normal file
10
docs/docs/guides/installation/http2-support.md
Normal 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.
|
||||||
@ -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"
|
|
||||||
```
|
|
||||||
@ -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:
|
||||||
@ -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"
|
||||||
@ -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!'
|
||||||
@ -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: ''
|
||||||
@ -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).
|
||||||
@ -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
|
||||||
@ -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"
|
|
||||||
```
|
|
||||||
@ -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.
|
|
||||||
@ -1 +0,0 @@
|
|||||||
Coming soon
|
|
||||||
@ -36,7 +36,18 @@ module.exports = {
|
|||||||
],
|
],
|
||||||
guides: [
|
guides: [
|
||||||
"guides/overview",
|
"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",
|
type: "category",
|
||||||
label: "Get to know ZITADEL",
|
label: "Get to know ZITADEL",
|
||||||
|
|||||||
1
example-zitadel-config.yaml
Symbolic link
1
example-zitadel-config.yaml
Symbolic link
@ -0,0 +1 @@
|
|||||||
|
/tmp/example-zitadel-config.yaml
|
||||||
Loading…
x
Reference in New Issue
Block a user