mirror of
https://github.com/andwati/zitadel.git
synced 2026-11-06 06:12:16 +00:00
docs: split out self-hosting into new section (#4903)
* docs: split out self-hosting into section * check for broken links * fix netlify proxy forward * use full path
This commit is contained in:
Florian Forster
@@ -1,8 +0,0 @@
|
||||
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!*
|
||||
|
||||
:::info
|
||||
|
||||
In the above username, replace localhost with your configured external domain, if any. e.g. with *zitadel-admin@<span></span>zitadel.sso.my.domain.tld*
|
||||
@@ -1,8 +0,0 @@
|
||||
## Disclaimer
|
||||
|
||||
This guide is for development / demonstration purpose only and does NOT reflect a production setup.
|
||||
|
||||
Things such as TLS termination and email verification will not be available unless you
|
||||
|
||||
- Use an API gateway with valid certificates in front of the service
|
||||
- Configure an appropriate email server
|
||||
@@ -1,9 +0,0 @@
|
||||
|
||||
## What's next
|
||||
|
||||
For running a production grade ZITADEL instance in your environment, go on with the [configure ZITADEL](/guides/manage/self-hosted/configure) section.
|
||||
|
||||
:::caution
|
||||
|
||||
<!-- TODO: Better mark the link in the UI -->
|
||||
The ZITADEL management console [requires end-to-end HTTP/2 support](/guides/manage/self-hosted/http2)
|
||||
@@ -1,57 +0,0 @@
|
||||
---
|
||||
title: Docker Compose
|
||||
---
|
||||
|
||||
import CodeBlock from '@theme/CodeBlock';
|
||||
import DockerComposeSource from '!!raw-loader!./docker-compose.yaml'
|
||||
import DockerComposeSaSource from '!!raw-loader!./docker-compose-sa.yaml'
|
||||
import Disclaimer from './_disclaimer.mdx'
|
||||
import DefaultUser from './_defaultuser.mdx'
|
||||
import Next from './_next.mdx'
|
||||
|
||||
The setup is tested against Docker version 20.10.17 and Docker Compose version v2.2.3
|
||||
|
||||
## Docker compose
|
||||
|
||||
By executing the commands below, you will download the following file:
|
||||
|
||||
<details><summary>docker-compose.yaml</summary>
|
||||
<CodeBlock language="yaml">{DockerComposeSource}</CodeBlock>
|
||||
</details>
|
||||
|
||||
```bash
|
||||
# Download the docker compose example configuration.
|
||||
wget https://raw.githubusercontent.com/zitadel/zitadel/main/docs/docs/guides/deploy/docker-compose.yaml
|
||||
|
||||
# Run the database and application containers.
|
||||
docker compose up --detach
|
||||
```
|
||||
|
||||
<DefaultUser components={props.components} />
|
||||
|
||||
## VideoGuide
|
||||
<iframe width="100%" height="315" src="https://www.youtube.com/embed/-02FaoN9Fko" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
|
||||
|
||||
## Docker compose with service account
|
||||
|
||||
By executing the commands below, you will download the following file:
|
||||
|
||||
<details><summary>docker-compose-sa.yaml</summary>
|
||||
<CodeBlock language="yaml">{DockerComposeSaSource}</CodeBlock>
|
||||
</details>
|
||||
|
||||
```bash
|
||||
# Download the docker compose example configuration.
|
||||
wget https://raw.githubusercontent.com/zitadel/zitadel/main/docs/docs/guides/deploy/docker-compose-sa.yaml -O docker-compose.yaml
|
||||
|
||||
# Run the database and application containers.
|
||||
docker compose up --detach
|
||||
|
||||
# then you can move your machine key
|
||||
mv ./machinekey/zitadel-admin-sa.json $HOME/zitadel-admin-sa.json
|
||||
```
|
||||
|
||||
This key can be used to provision resources with for example [Terraform](../manage/terraform/basics.md).
|
||||
|
||||
<Next components={props.components} />
|
||||
<Disclaimer components={props.components} />
|
||||
@@ -1,42 +0,0 @@
|
||||
version: '3.8'
|
||||
|
||||
services:
|
||||
zitadel:
|
||||
restart: 'always'
|
||||
networks:
|
||||
- 'zitadel'
|
||||
image: 'ghcr.io/zitadel/zitadel:stable'
|
||||
command: 'start-from-init --masterkey "MasterkeyNeedsToHave32Characters" --tlsMode disabled'
|
||||
environment:
|
||||
- 'ZITADEL_DATABASE_COCKROACH_HOST=crdb'
|
||||
- 'ZITADEL_EXTERNALSECURE=false'
|
||||
- 'ZITADEL_FIRSTINSTANCE_MACHINEKEYPATH=/machinekey/zitadel-admin-sa.json'
|
||||
- 'ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINE_USERNAME=zitadel-admin-sa'
|
||||
- 'ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINE_NAME=Admin'
|
||||
- 'ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINEKEY_TYPE=1'
|
||||
depends_on:
|
||||
crdb:
|
||||
condition: 'service_healthy'
|
||||
ports:
|
||||
- '8080:8080'
|
||||
volumes:
|
||||
- ./machinekey:/machinekey
|
||||
|
||||
crdb:
|
||||
restart: 'always'
|
||||
networks:
|
||||
- 'zitadel'
|
||||
image: 'cockroachdb/cockroach:v22.1.3'
|
||||
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,36 +0,0 @@
|
||||
version: '3.8'
|
||||
|
||||
services:
|
||||
zitadel:
|
||||
restart: 'always'
|
||||
networks:
|
||||
- 'zitadel'
|
||||
image: 'ghcr.io/zitadel/zitadel:latest'
|
||||
command: 'start-from-init --masterkey "MasterkeyNeedsToHave32Characters" --tlsMode disabled'
|
||||
environment:
|
||||
- 'ZITADEL_DATABASE_COCKROACH_HOST=crdb'
|
||||
- 'ZITADEL_EXTERNALSECURE=false'
|
||||
depends_on:
|
||||
crdb:
|
||||
condition: 'service_healthy'
|
||||
ports:
|
||||
- '8080:8080'
|
||||
|
||||
crdb:
|
||||
restart: 'always'
|
||||
networks:
|
||||
- 'zitadel'
|
||||
image: 'cockroachdb/cockroach:v22.1.3'
|
||||
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,65 +0,0 @@
|
||||
---
|
||||
title: Knative
|
||||
---
|
||||
|
||||
import Disclaimer from './_disclaimer.mdx'
|
||||
import DefaultUser from './_defaultuser.mdx'
|
||||
import Next from './_next.mdx'
|
||||
|
||||
## Install Knative
|
||||
|
||||
Follow the [Knative quickstart guide](https://knative.dev/docs/getting-started/quickstart-install/) to get a local kind/minikube environment with Knative capabilities.
|
||||
|
||||
## Run CockroachDB
|
||||
|
||||
Start a single-node cockroachdb as statefulset
|
||||
|
||||
```bash
|
||||
kubectl apply -f https://raw.githubusercontent.com/zitadel/zitadel/main/deploy/knative/cockroachdb-statefulset-single-node.yaml
|
||||
```
|
||||
|
||||
## Start ZITADEL
|
||||
|
||||
### Knative Command
|
||||
|
||||
```bash
|
||||
kn service create zitadel \
|
||||
--image ghcr.io/zitadel/zitadel:stable \
|
||||
--port 8080 \
|
||||
--env ZITADEL_DATABASE_COCKROACH_HOST=cockroachdb \
|
||||
--env ZITADEL_EXTERNALSECURE=false \
|
||||
--env ZITADEL_EXTERNALPORT=80 \
|
||||
--env ZITADEL_TLS_ENABLED=false \
|
||||
--env ZITADEL_EXTERNALDOMAIN=zitadel.default.127.0.0.1.sslip.io \
|
||||
--arg "start-from-init" --arg "--masterkey" --arg "MasterkeyNeedsToHave32Characters"
|
||||
```
|
||||
|
||||
### Knavite yaml
|
||||
|
||||
```bash
|
||||
kubectl apply -f https://raw.githubusercontent.com/zitadel/zitadel/main/deploy/knative/zitadel-knative-service.yaml
|
||||
```
|
||||
|
||||
## Access ZITADEL
|
||||
|
||||
### Get the ZITADEL URL
|
||||
|
||||
```bash
|
||||
kn services list
|
||||
|
||||
NAME URL LATEST AGE CONDITIONS READY REASON
|
||||
zitadel http://zitadel.default.127.0.0.1.sslip.io zitadel-00001 10m 3 OK / 3 True
|
||||
```
|
||||
|
||||
Add the console path to the URL and open in browser
|
||||
http://zitadel.default.127.0.0.1.sslip.io/ui/console
|
||||
|
||||
If you didn't configure something else, this is the default IAM admin users login:
|
||||
|
||||
* username: zitadel-admin@<span></span>zitadel.zitadel.default.127.0.0.1.sslip.io
|
||||
* password: Password1!
|
||||
|
||||
## VideoGuide
|
||||
<iframe width="100%" height="315" src="https://www.youtube.com/embed/m3TXmz3cK7E" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
|
||||
<Next components={props.components} />
|
||||
<Disclaimer components={props.components} />
|
||||
@@ -1,79 +0,0 @@
|
||||
---
|
||||
title: Kubernetes
|
||||
---
|
||||
|
||||
import Disclaimer from './_disclaimer.mdx'
|
||||
import DefaultUser from './_defaultuser.mdx'
|
||||
import Next from './_next.mdx'
|
||||
|
||||
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.
|
||||
|
||||
## Helm
|
||||
|
||||
### Add the helm repositories for CockroachDB and ZITADEL
|
||||
|
||||
```bash
|
||||
helm repo add cockroachdb https://charts.cockroachdb.com/
|
||||
helm repo add zitadel https://charts.zitadel.com
|
||||
```
|
||||
|
||||
### Install zitadel
|
||||
|
||||
#### Install an insecure cockroachdb and zitadel release that works with localhost
|
||||
|
||||
```bash
|
||||
# CockroachDB
|
||||
helm install crdb cockroachdb/cockroachdb \
|
||||
--set fullnameOverride=crdb \
|
||||
--set single-node=true \
|
||||
--set statefulset.replicas=1
|
||||
|
||||
# ZITADEL
|
||||
helm install my-zitadel zitadel/zitadel \
|
||||
--set zitadel.masterkey="MasterkeyNeedsToHave32Characters" \
|
||||
--set zitadel.configmapConfig.ExternalSecure=false \
|
||||
--set zitadel.configmapConfig.TLS.Enabled=false \
|
||||
--set zitadel.secretConfig.Database.cockroach.User.Password="a-zitadel-db-user-password" \
|
||||
--set replicaCount=1 \
|
||||
--set cockroachdb.single-node=true \
|
||||
--set cockroachdb.statefulset.replicas=1
|
||||
```
|
||||
|
||||
<DefaultUser components={props.components} />
|
||||
|
||||
#### Install an insecure zitadel release that works with localhost with a service account
|
||||
|
||||
!!!Caution!!! With this setup you only get a service account with a key and no admin account where you can login directly into ZITADEL.
|
||||
|
||||
```bash
|
||||
helm install --namespace zitadel --create-namespace my-zitadel zitadel/zitadel \
|
||||
--set zitadel.masterkey="MasterkeyNeedsToHave32Characters" \
|
||||
--set zitadel.configmapConfig.ExternalSecure=false \
|
||||
--set zitadel.configmapConfig.TLS.Enabled=false \
|
||||
--set zitadel.secretConfig.Database.cockroach.User.Password="a-zitadel-db-user-password" \
|
||||
--set replicaCount=1 \
|
||||
--set cockroachdb.single-node=true \
|
||||
--set cockroachdb.statefulset.replicas=1 \
|
||||
--set zitadel.configmapConfig.FirstInstance.MachineKeyPath="/machinekey/zitadel-admin-sa.json" \
|
||||
--set zitadel.configmapConfig.FirstInstance.Org.Machine.Machine.Username="zitadel-admin-sa" \
|
||||
--set zitadel.configmapConfig.FirstInstance.Org.Machine.Machine.Name="Admin" \
|
||||
--set zitadel.configmapConfig.FirstInstance.Org.Machine.MachineKey.Type=1
|
||||
```
|
||||
|
||||
When helm is done, you get a command to retrieve your machine key, which is saved as a kubernetes secret, for example:
|
||||
```bash
|
||||
kubectl -n zitadel get secret zitadel-admin-sa -o jsonpath='{ .data.zitadel-admin-sa\.json }' | base64 -D
|
||||
```
|
||||
|
||||
This key can be used to provision resources with for example [Terraform](../manage/terraform/basics.md).
|
||||
|
||||
### Forward the ZITADEL service port to your local machine
|
||||
|
||||
```bash
|
||||
kubectl port-forward svc/my-zitadel 8080:8080
|
||||
```
|
||||
|
||||
<Next components={props.components} />
|
||||
<Disclaimer components={props.components} />
|
||||
@@ -1,56 +0,0 @@
|
||||
---
|
||||
title: Linux
|
||||
---
|
||||
|
||||
import Disclaimer from './_disclaimer.mdx'
|
||||
import DefaultUser from './_defaultuser.mdx'
|
||||
import Next from './_next.mdx'
|
||||
|
||||
## Install CockroachDB
|
||||
|
||||
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
|
||||
|
||||
```bash
|
||||
cockroach start-single-node --insecure --background --http-addr :9090 --listen-addr=localhost
|
||||
```
|
||||
|
||||
## Install ZITADEL
|
||||
|
||||
Download the ZITADEL release according to your architecture from [Github](https://github.com/zitadel/zitadel/releases/latest)
|
||||
|
||||
## Unpack the archive
|
||||
move to your download location and unpack the archive
|
||||
|
||||
```bash
|
||||
#unpack and copy to /usr/local/bin
|
||||
LATEST=$(curl -i https://github.com/zitadel/zitadel/releases/latest | grep location: | cut -d '/' -f 8 | tr -d '\r'); wget -qO- https://github.com/zitadel/zitadel/releases/download/$LATEST/zitadel_Linux_$(uname -m).tar.gz | tar -xz zitadel && sudo mv zitadel /usr/local/bin
|
||||
|
||||
```
|
||||
|
||||
## Run ZITADEL
|
||||
|
||||
```bash
|
||||
ZITADEL_EXTERNALSECURE=false zitadel start-from-init --masterkey "MasterkeyNeedsToHave32Characters" --tlsMode disabled
|
||||
```
|
||||
|
||||
<DefaultUser components={props.components} />
|
||||
|
||||
## VideoGuide
|
||||
<iframe width="100%" height="315" src="https://www.youtube.com/embed/YVLua-q7dbs" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
|
||||
|
||||
### Setup ZITADEL with a service account
|
||||
|
||||
```bash
|
||||
ZITADEL_EXTERNALSECURE=false ZITADEL_FIRSTINSTANCE_MACHINEKEYPATH=/tmp/zitadel-admin-sa.json ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINE_USERNAME=zitadel-admin-sa ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINE_NAME=Admin ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINEKEY_TYPE=1 zitadel start-from-init --masterkey "MasterkeyNeedsToHave32Characters" --tlsMode disabled
|
||||
|
||||
# then you can move your machine key
|
||||
mv /tmp/zitadel-admin-sa.json $HOME/zitadel-admin-sa.json
|
||||
```
|
||||
|
||||
This key can be used to provision resources with for example [Terraform](../manage/terraform/basics.md).
|
||||
|
||||
<Next components={props.components} />
|
||||
<Disclaimer components={props.components} />
|
||||
@@ -1,66 +0,0 @@
|
||||
version: '3.8'
|
||||
services:
|
||||
|
||||
traefik:
|
||||
networks:
|
||||
- 'zitadel'
|
||||
image: "traefik:v2.7"
|
||||
ports:
|
||||
- "80:80"
|
||||
- "443:443"
|
||||
volumes:
|
||||
- "./example-traefik.yaml:/etc/traefik/traefik.yaml"
|
||||
|
||||
zitadel:
|
||||
restart: 'always'
|
||||
networks:
|
||||
- 'zitadel'
|
||||
image: 'ghcr.io/zitadel/zitadel:stable'
|
||||
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:
|
||||
certs:
|
||||
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'
|
||||
|
||||
certs:
|
||||
image: 'cockroachdb/cockroach:v22.1.0'
|
||||
entrypoint: [ '/bin/bash', '-c' ]
|
||||
command: [ 'cp /certs/* /zitadel-certs/ && cockroach cert create-client --overwrite --certs-dir /zitadel-certs/ --ca-key /zitadel-certs/ca.key zitadel_user && chown 1000:1000 /zitadel-certs/*' ]
|
||||
volumes:
|
||||
- 'certs:/certs:ro'
|
||||
- 'zitadel-certs:/zitadel-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:
|
||||
@@ -1,63 +0,0 @@
|
||||
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,25 +0,0 @@
|
||||
# All possible options and their defaults: https://github.com/zitadel/zitadel/blob/main/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:
|
||||
cockroach:
|
||||
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"
|
||||
Admin:
|
||||
SSL:
|
||||
Mode: 'verify-full'
|
||||
RootCert: "/crdb-certs/ca.crt"
|
||||
Cert: "/crdb-certs/client.root.crt"
|
||||
Key: "/crdb-certs/client.root.key"
|
||||
@@ -1,8 +0,0 @@
|
||||
# All possible options and their defaults: https://github.com/zitadel/zitadel/blob/main/cmd/setup/steps.yaml
|
||||
FirstInstance:
|
||||
Org:
|
||||
Name: 'My Org'
|
||||
Human:
|
||||
# use the loginname [email protected]
|
||||
Username: 'root'
|
||||
Password: 'RootPassword1!'
|
||||
@@ -1,10 +0,0 @@
|
||||
# All possible options and their defaults: https://github.com/zitadel/zitadel/blob/main/cmd/defaults.yaml
|
||||
|
||||
# If not using the docker compose example, adjust these values for connecting ZITADEL to your CockroachDB
|
||||
Database:
|
||||
cockroach:
|
||||
User:
|
||||
# If the user doesn't exist already, it is created
|
||||
Username: 'zitadel_user'
|
||||
Admin:
|
||||
Username: 'root'
|
||||
@@ -1,72 +0,0 @@
|
||||
---
|
||||
title: Load Balancing Example
|
||||
---
|
||||
|
||||
import CodeBlock from '@theme/CodeBlock';
|
||||
import DockerComposeSource from '!!raw-loader!./docker-compose.yaml'
|
||||
import ExampleTraefikSource from '!!raw-loader!./example-traefik.yaml'
|
||||
import ExampleZITADELConfigSource from '!!raw-loader!./example-zitadel-config.yaml'
|
||||
import ExampleZITADELSecretsSource from '!!raw-loader!./example-zitadel-secrets.yaml'
|
||||
import ExampleZITADELInitStepsSource from '!!raw-loader!./example-zitadel-init-steps.yaml'
|
||||
|
||||
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:
|
||||
|
||||
<details><summary>docker-compose.yaml</summary>
|
||||
<CodeBlock language="yaml">{DockerComposeSource}</CodeBlock>
|
||||
</details>
|
||||
<details><summary>example-traefik.yaml</summary>
|
||||
<CodeBlock language="yaml">{ExampleTraefikSource}</CodeBlock>
|
||||
</details>
|
||||
<details><summary>example-zitadel-config.yaml</summary>
|
||||
<CodeBlock language="yaml">{ExampleZITADELConfigSource}</CodeBlock>
|
||||
</details>
|
||||
<details><summary>example-zitadel-secrets.yaml</summary>
|
||||
<CodeBlock language="yaml">{ExampleZITADELSecretsSource}</CodeBlock>
|
||||
</details>
|
||||
<details><summary>example-zitadel-init-steps.yaml</summary>
|
||||
<CodeBlock language="yaml">{ExampleZITADELInitStepsSource}</CodeBlock>
|
||||
</details>
|
||||
|
||||
```bash
|
||||
# Download the docker compose example configuration.
|
||||
wget https://raw.githubusercontent.com/zitadel/zitadel/main/docs/docs/guides/deploy/loadbalancing-example/docker-compose.yaml
|
||||
|
||||
# Download the Traefik example configuration.
|
||||
wget https://raw.githubusercontent.com/zitadel/zitadel/main/docs/docs/guides/deploy/loadbalancing-example/example-traefik.yaml
|
||||
|
||||
# Download and adjust the example configuration file containing standard configuration.
|
||||
wget https://raw.githubusercontent.com/zitadel/zitadel/main/docs/docs/guides/deploy/loadbalancing-example/example-zitadel-config.yaml
|
||||
|
||||
# Download and adjust the example configuration file containing secret configuration.
|
||||
wget https://raw.githubusercontent.com/zitadel/zitadel/main/docs/docs/guides/deploy/loadbalancing-example/example-zitadel-secrets.yaml
|
||||
|
||||
# Download and adjust the example configuration file containing database initialization configuration.
|
||||
wget https://raw.githubusercontent.com/zitadel/zitadel/main/docs/docs/guides/deploy/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).
|
||||
@@ -1,63 +0,0 @@
|
||||
---
|
||||
title: MacOS
|
||||
---
|
||||
|
||||
import Disclaimer from './_disclaimer.mdx'
|
||||
import DefaultUser from './_defaultuser.mdx'
|
||||
import Next from './_next.mdx'
|
||||
|
||||
## Install CockroachDB
|
||||
|
||||
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
|
||||
|
||||
```bash
|
||||
cockroach start-single-node --insecure --background --http-addr :9090 --listen-addr=localhost
|
||||
```
|
||||
|
||||
## Install ZITADEL
|
||||
|
||||
### Homebrew
|
||||
|
||||
```bash
|
||||
brew install zitadel/tap/zitadel
|
||||
```
|
||||
|
||||
### Download from GitHub
|
||||
|
||||
Download the ZITADEL release according to your architecture from [Github](https://github.com/zitadel/zitadel/releases/latest)
|
||||
|
||||
## Unpack the archive
|
||||
move to your download location and unpack the archive
|
||||
|
||||
```bash
|
||||
#unpack and copy to /usr/local/bin
|
||||
LATEST=$(curl -i https://github.com/zitadel/zitadel/releases/latest | grep location: | cut -d '/' -f 8 | tr -d '\r'); wget -qO- https://github.com/zitadel/zitadel/releases/download/$LATEST/zitadel_Darwin_$(uname -m).tar.gz | tar -xJ zitadel && sudo mv zitadel /usr/local/bin
|
||||
```
|
||||
|
||||
## Run ZITADEL
|
||||
|
||||
```bash
|
||||
ZITADEL_EXTERNALSECURE=false zitadel start-from-init --masterkey "MasterkeyNeedsToHave32Characters" --tlsMode disabled
|
||||
```
|
||||
|
||||
<DefaultUser components={props.components} />
|
||||
|
||||
## VideoGuide
|
||||
<iframe width="100%" height="315" src="https://www.youtube.com/embed/Ob-kBzmezeg" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
|
||||
|
||||
### Setup ZITADEL with a service account
|
||||
|
||||
```bash
|
||||
ZITADEL_EXTERNALSECURE=false ZITADEL_FIRSTINSTANCE_MACHINEKEYPATH=/tmp/zitadel-admin-sa.json ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINE_USERNAME=zitadel-admin-sa ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINE_NAME=Admin ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINEKEY_TYPE=1 zitadel start-from-init --masterkey "MasterkeyNeedsToHave32Characters" --tlsMode disabled
|
||||
|
||||
# then you can move your machine key
|
||||
mv /tmp/zitadel-admin-sa.json $HOME/zitadel-admin-sa.json
|
||||
```
|
||||
|
||||
This key can be used to provision resources with for example [Terraform](../manage/terraform/basics.md).
|
||||
|
||||
<Next components={props.components} />
|
||||
<Disclaimer components={props.components} />
|
||||
@@ -1,33 +0,0 @@
|
||||
---
|
||||
title: Overview
|
||||
---
|
||||
|
||||
Choose your platform and run ZITADEL with the most minimal configuration possible.
|
||||
|
||||
- [Linux](./linux)
|
||||
- [MacOS](./macos)
|
||||
- [Docker Compose](./compose)
|
||||
- [Knative](./knative)
|
||||
- [Kubernetes](./kubernetes)
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- For test environments, ZITADEL does not need many resources, 1 CPU and 512MB memory are more than enough. (With more CPU, the password hashing might be faster)
|
||||
- A cockroachDB or Postgresql (currently in beta) as only needed storage
|
||||
|
||||
## Releases
|
||||
|
||||
The easiest way to use ZITADEL is to run one of our container releases
|
||||
|
||||
- ZITADEL does provide latest and stable [container images](https://github.com/zitadel/zitadel/pkgs/container/zitadel)
|
||||
- **stable** is the current **production** release of ZITADEL.
|
||||
- **latest** is the **last created** release from our pipelines that gets updated in a high frequency.
|
||||
|
||||
# Production Setup
|
||||
|
||||
As soon as you successfully created your first test environment using one of the deployment guides in this section,
|
||||
you might want to configure ZITADEL for production and embed it into your system landscape.
|
||||
To do so, jump straight to the [production setup guide](../manage/self-hosted/production).
|
||||
|
||||
To achieving high availability, we recommend to use a [Kubernetes](https://kubernetes.io/docs/home/) Cluster.
|
||||
We have an official [Helm chart](https://artifacthub.io/packages/helm/zitadel/zitadel) for easy deployment and maintenance.
|
||||
@@ -9,7 +9,7 @@ The ZITADEL System API is currently only available for ZITADEL Self-Hosted deplo
|
||||
## System API User
|
||||
|
||||
The System API works superordinate over all instances. Therefore, you need to define a separate users to get access to this API.
|
||||
You can do so by customizing the [runtime configuration](/guides/manage/self-hosted/configure#runtime-configuration).
|
||||
You can do so by customizing the [runtime configuration](/self-hosting/manage/configure#runtime-configuration).
|
||||
|
||||
To authenticate the user a self-signed JWT will be created and utilized.
|
||||
|
||||
|
||||
@@ -1,44 +0,0 @@
|
||||
import CodeBlock from '@theme/CodeBlock';
|
||||
import DockerComposeSource from '!!raw-loader!./docker-compose.yaml'
|
||||
import ExampleZITADELConfigSource from '!!raw-loader!./example-zitadel-config.yaml'
|
||||
import ExampleZITADELSecretsSource from '!!raw-loader!./example-zitadel-secrets.yaml'
|
||||
import ExampleZITADELInitStepsSource from '!!raw-loader!./example-zitadel-init-steps.yaml'
|
||||
|
||||
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:
|
||||
|
||||
<details><summary>docker-compose.yaml</summary>
|
||||
<CodeBlock language="yaml">{DockerComposeSource}</CodeBlock>
|
||||
</details>
|
||||
<details><summary>example-zitadel-config.yaml</summary>
|
||||
<CodeBlock language="yaml">{ExampleZITADELConfigSource}</CodeBlock>
|
||||
</details>
|
||||
<details><summary>example-zitadel-secrets.yaml</summary>
|
||||
<CodeBlock language="yaml">{ExampleZITADELSecretsSource}</CodeBlock>
|
||||
</details>
|
||||
<details><summary>example-zitadel-init-steps.yaml</summary>
|
||||
<CodeBlock language="yaml">{ExampleZITADELInitStepsSource}</CodeBlock>
|
||||
</details>
|
||||
|
||||
```bash
|
||||
# Download the docker compose example configuration for a secure CockroachDB.
|
||||
wget https://raw.githubusercontent.com/zitadel/zitadel/main/docs/docs/guides/manage/self-hosted/configure/docker-compose.yaml
|
||||
|
||||
# Download and adjust the example configuration file containing standard configuration.
|
||||
wget https://raw.githubusercontent.com/zitadel/zitadel/main/docs/docs/guides/manage/self-hosted/configure/example-zitadel-config.yaml
|
||||
|
||||
# Download and adjust the example configuration file containing secret configuration.
|
||||
wget https://raw.githubusercontent.com/zitadel/zitadel/main/docs/docs/guides/manage/self-hosted/configure/example-zitadel-secrets.yaml
|
||||
|
||||
# Download and adjust the example configuration file containing database initialization configuration.
|
||||
wget https://raw.githubusercontent.com/zitadel/zitadel/main/docs/docs/guides/manage/self-hosted/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
|
||||
```
|
||||
@@ -1,33 +0,0 @@
|
||||
import CodeBlock from '@theme/CodeBlock';
|
||||
import ExampleZITADELValuesSource from '!!raw-loader!./example-zitadel-values.yaml'
|
||||
import ExampleZITADELValuesSecretsSource from '!!raw-loader!./example-zitadel-values-secrets.yaml'
|
||||
|
||||
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](../../deploy/loadbalancing-example)
|
||||
|
||||
By executing the commands below, you will download the following files:
|
||||
|
||||
<details><summary>example-zitadel-values.yaml</summary>
|
||||
<CodeBlock language="yaml">{ExampleZITADELValuesSource}</CodeBlock>
|
||||
</details>
|
||||
<details><summary>example-zitadel-values-secrets.yaml</summary>
|
||||
<CodeBlock language="yaml">{ExampleZITADELValuesSecretsSource}</CodeBlock>
|
||||
</details>
|
||||
|
||||
```bash
|
||||
# Download and adjust the example configuration file containing standard configuration
|
||||
wget https://raw.githubusercontent.com/zitadel/zitadel/main/docs/docs/guides/manage/self-hosted/configure/example-zitadel-values.yaml
|
||||
|
||||
# Download and adjust the example configuration file containing secret configuration
|
||||
wget https://raw.githubusercontent.com/zitadel/zitadel/main/docs/docs/guides/manage/self-hosted/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
|
||||
```
|
||||
@@ -1,60 +0,0 @@
|
||||
import CodeBlock from '@theme/CodeBlock';
|
||||
import ExampleZITADELConfigSource from '!!raw-loader!./example-zitadel-config.yaml'
|
||||
import ExampleZITADELSecretsSource from '!!raw-loader!./example-zitadel-secrets.yaml'
|
||||
import ExampleZITADELInitStepsSource from '!!raw-loader!./example-zitadel-init-steps.yaml'
|
||||
|
||||
### Configure by Files
|
||||
|
||||
By executing the commands below, you will download the following files:
|
||||
|
||||
<details><summary>example-zitadel-config.yaml</summary>
|
||||
<CodeBlock language="yaml">{ExampleZITADELConfigSource}</CodeBlock>
|
||||
</details>
|
||||
<details><summary>example-zitadel-secrets.yaml</summary>
|
||||
<CodeBlock language="yaml">{ExampleZITADELSecretsSource}</CodeBlock>
|
||||
</details>
|
||||
<details><summary>example-zitadel-init-steps.yaml</summary>
|
||||
<CodeBlock language="yaml">{ExampleZITADELInitStepsSource}</CodeBlock>
|
||||
</details>
|
||||
|
||||
```bash
|
||||
# Download and adjust the example configuration file containing standard configuration
|
||||
wget https://raw.githubusercontent.com/zitadel/zitadel/main/docs/docs/guides/manage/self-hosted/configure/example-zitadel-config.yaml
|
||||
|
||||
# Download and adjust the example configuration file containing secret configuration
|
||||
wget https://raw.githubusercontent.com/zitadel/zitadel/main/docs/docs/guides/manage/self-hosted/configure/example-zitadel-secrets.yaml
|
||||
|
||||
# Download and adjust the example configuration file containing database initialization configuration
|
||||
wget https://raw.githubusercontent.com/zitadel/zitadel/main/docs/docs/guides/manage/self-hosted/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_COCKROACH_HOST="my.database"
|
||||
export ZITADEL_DATABASE_COCKROACH_USER_USERNAME="my_zitadel_db_user"
|
||||
export ZITADEL_DATABASE_COCKROACH_USER_PASSWORD="Secret_DB_User_Password"
|
||||
export ZITADEL_FIRSTINSTANCE_ORG_HUMAN_USERNAME="root"
|
||||
export ZITADEL_FIRSTINSTANCE_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 start-from-init --masterkey "${ZITADEL_MASTERKEY}" --tlsMode disabled
|
||||
```
|
||||
@@ -1,83 +0,0 @@
|
||||
---
|
||||
title: Configuration Options
|
||||
---
|
||||
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem";
|
||||
import LinuxUnix from './_linuxunix.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](../../deploy/overview).
|
||||
|
||||
## 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/main/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/main/cmd/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_FIRSTINSTANCE_ORG_HUMAN_USERNAME* and *ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD* set.
|
||||
|
||||
## Masterkey
|
||||
|
||||
The masterkey is used to AES256-encrypt other generated encryption keys.
|
||||
It needs to have 32 bytes.
|
||||
You can pass the masterkey in either of three possible ways to the zitadel binary:
|
||||
- By value: Use the flag `--masterkey My_Master_Key_Which_Has_32_Bytes`
|
||||
- By environment variable `ZITADEL_MASTERKEY`: Use the flag `--masterkeyFromEnv`
|
||||
- By file: Use the flag `--masterkeyFile /path/to/file`
|
||||
|
||||
## Passing the configuration
|
||||
|
||||
<Tabs
|
||||
groupId="installation-target"
|
||||
default="linuxunix"
|
||||
values={[
|
||||
{'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/main/cmd/defaults.yaml)
|
||||
- Check out all possible [setup step configuration properties and their defaults in the source code](https://github.com/zitadel/zitadel/blob/main/cmd/setup/steps.yaml)
|
||||
|
||||
:::caution
|
||||
|
||||
<!-- TODO: Better mark the link in the UI -->
|
||||
The ZITADEL management console [requires end-to-end HTTP/2 support](/guides/manage/self-hosted/http2)
|
||||
@@ -1,60 +0,0 @@
|
||||
version: "3.8"
|
||||
|
||||
services:
|
||||
zitadel:
|
||||
restart: "always"
|
||||
networks:
|
||||
- "zitadel"
|
||||
image: "ghcr.io/zitadel/zitadel:stable"
|
||||
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:
|
||||
certs:
|
||||
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"
|
||||
|
||||
certs:
|
||||
image: "cockroachdb/cockroach:v22.1.0"
|
||||
entrypoint: ["/bin/bash", "-c"]
|
||||
command:
|
||||
[
|
||||
"cp /certs/* /zitadel-certs/ && cockroach cert create-client --overwrite --certs-dir /zitadel-certs/ --ca-key /zitadel-certs/ca.key zitadel_user && chown 1000:1000 /zitadel-certs/*",
|
||||
]
|
||||
volumes:
|
||||
- "certs:/certs:ro"
|
||||
- "zitadel-certs:/zitadel-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:
|
||||
@@ -1,23 +0,0 @@
|
||||
# All possible options and their defaults: https://github.com/zitadel/zitadel/blob/main/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:
|
||||
cockroach:
|
||||
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"
|
||||
Admin:
|
||||
SSL:
|
||||
Mode: 'verify-full'
|
||||
RootCert: "/crdb-certs/ca.crt"
|
||||
Cert: "/crdb-certs/client.root.crt"
|
||||
Key: "/crdb-certs/client.root.key"
|
||||
@@ -1,7 +0,0 @@
|
||||
# All possible options and their defaults: https://github.com/zitadel/zitadel/blob/main/cmd/setup/steps.yaml
|
||||
FirstInstance:
|
||||
Org:
|
||||
Human:
|
||||
# use the loginname [email protected]
|
||||
Username: 'root'
|
||||
Password: 'RootPassword1!'
|
||||
@@ -1,10 +0,0 @@
|
||||
# All possible options and their defaults: https://github.com/zitadel/zitadel/blob/main/cmd/defaults.yaml
|
||||
|
||||
# If not using the docker compose example, adjust these values for connecting ZITADEL to your CockroachDB
|
||||
Database:
|
||||
cockroach:
|
||||
User:
|
||||
# If the user doesn't exist already, it is created
|
||||
Username: 'zitadel_user'
|
||||
Admin:
|
||||
Username: 'root'
|
||||
@@ -1,16 +0,0 @@
|
||||
# All possible options and their defaults: https://github.com/zitadel/zitadel/blob/main/cmd/defaults.yaml
|
||||
zitadel:
|
||||
|
||||
masterkey: 'MasterkeyNeedsToHave32Characters'
|
||||
|
||||
secretConfig:
|
||||
|
||||
Database:
|
||||
cockroach:
|
||||
User:
|
||||
# If the user doesn't exist already, it is created
|
||||
Username: 'zitadel_user'
|
||||
Password: 'Secret_DB_User_Password'
|
||||
Admin:
|
||||
Username: 'root'
|
||||
Password: ''
|
||||
@@ -1,17 +0,0 @@
|
||||
# All possible options and their defaults: https://github.com/zitadel/zitadel/blob/main/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
|
||||
FirstInstance:
|
||||
Org:
|
||||
Human:
|
||||
# use the loginname [email protected]
|
||||
Username: 'root'
|
||||
Password: 'RootPassword1!'
|
||||
@@ -1,30 +0,0 @@
|
||||
---
|
||||
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 first instance, this is most probably not the desired behavior.
|
||||
In this case the `ExternalDomain`-field of the configuration is used.
|
||||
|
||||
## Example
|
||||
|
||||
Go to the [loadbalancing example with Traefik](../../deploy/loadbalancing-example) for seeing a working example configuration.
|
||||
@@ -1,33 +0,0 @@
|
||||
## Cockroach
|
||||
|
||||
The default database of ZITADEL is [CockroachDB](https://www.cockroachlabs.com). The SQL database provides a bunch of features like horizontal scalability, data regionality and many more.
|
||||
|
||||
The default configuration of the database looks like this:
|
||||
|
||||
```yaml
|
||||
Database:
|
||||
cockroach:
|
||||
Host: localhost
|
||||
Port: 26257
|
||||
Database: zitadel
|
||||
MaxOpenConns: 20
|
||||
MaxConnLifetime: 30m
|
||||
MaxConnIdleTime: 30m
|
||||
Options: ""
|
||||
User:
|
||||
Username: zitadel
|
||||
Password: ""
|
||||
SSL:
|
||||
Mode: disable
|
||||
RootCert: ""
|
||||
Cert: ""
|
||||
Key: ""
|
||||
Admin:
|
||||
Username: root
|
||||
Password: ""
|
||||
SSL:
|
||||
Mode: disable
|
||||
RootCert: ""
|
||||
Cert: ""
|
||||
Key: ""
|
||||
```
|
||||
@@ -1,38 +0,0 @@
|
||||
## Postgres
|
||||
|
||||
:::caution
|
||||
Postgres extension is currently in beta.
|
||||
:::
|
||||
|
||||
If you want to use a PostgreSQL database instead of CockroachDB you can [overwrite the default configuration](../configure/configure.mdx).
|
||||
|
||||
Currently versions >= 14 are supported.
|
||||
|
||||
Postgres can be configured as follows:
|
||||
```yaml
|
||||
Database:
|
||||
postgres:
|
||||
Host: localhost
|
||||
Port: 5432
|
||||
Database: zitadel
|
||||
MaxOpenConns: 25
|
||||
MaxConnLifetime: 1h
|
||||
MaxConnIdleTime: 5m
|
||||
Options:
|
||||
User:
|
||||
Username: zitadel
|
||||
Password: zitadel
|
||||
SSL:
|
||||
Mode: disable
|
||||
RootCert:
|
||||
Cert:
|
||||
Key:
|
||||
Admin:
|
||||
Username: postgres
|
||||
Password: postgres
|
||||
SSL:
|
||||
Mode: disable
|
||||
RootCert:
|
||||
Cert:
|
||||
Key:
|
||||
```
|
||||
@@ -1,28 +0,0 @@
|
||||
---
|
||||
title: Database
|
||||
---
|
||||
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem";
|
||||
import Cockroach from './_cockroachdb.mdx'
|
||||
import Postgres from './_postgres.mdx'
|
||||
|
||||
# Database Configuration
|
||||
|
||||
<Tabs
|
||||
groupId="database-vendor"
|
||||
default="cockroach"
|
||||
values={[
|
||||
{'label': 'Cockroach', 'value': 'crdb'},
|
||||
{'label': 'Postgres', 'value': 'pg'},
|
||||
]}
|
||||
>
|
||||
<TabItem value="crdb">
|
||||
<Cockroach/>
|
||||
<More/>
|
||||
</TabItem>
|
||||
<TabItem value="pg">
|
||||
<Postgres/>
|
||||
<More/>
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
@@ -1,15 +0,0 @@
|
||||
---
|
||||
title: HTTP/2 Support
|
||||
---
|
||||
|
||||
ZITADEL follows a strict API first approach and makes heavy use of the modern API framework called [gRPC](https://grpc.io/).
|
||||
Besides gRPC all APIs are also available in an openapi Rest fashion as well as in gRPC-web for compatibilty towards browser integrations.
|
||||
|
||||
To make use of gRPC it is vital to allow your clients to communicate with ZITADEL with [HTTP/2](https://en.wikipedia.org/wiki/HTTP/2).
|
||||
|
||||
Sometimes you need to configure explicitly that you want to use HTTP/2 if you run ZITADEL behind a reverse proxy and below you should find examples for different vendors and projects.
|
||||
|
||||
Furthermore it is important to notice that by default HTTP/2 is always encrypted, but if you want to run ZITADEL without TLS from your reverse proxy or service mesh this is possible through [h2c](https://httpd.apache.org/docs/2.4/howto/http2.html).
|
||||
Oftentimes when you run ZITADEL inside a service mesh, or a servelerss offering (e.g. Google Cloud Run, Knative, ...) you will need h2c.
|
||||
|
||||
You can read more about ZITADEL's [TLSs modes here](/guides/manage/self-hosted/tls_modes).
|
||||
@@ -1,132 +0,0 @@
|
||||
---
|
||||
title: Production Checklist
|
||||
---
|
||||
|
||||
As soon as you successfully deployed ZITADEL as a proof of concept using one of our [deployment guides](/guides/deploy/overview),
|
||||
you are ready to configure ZITADEL for production usage.
|
||||
|
||||
## High Availability
|
||||
|
||||
We recommend running ZITADEL highly available using an orchestrator that schedules ZITADEL on multiple servers, like [Kubernetes](/guides/deploy/kubernetes). For keeping startup times fast when scaling ZITADEL, you should also consider using separate jobs with `zitadel init` and `zitadel setup`, so your workload containers just have to execute `zitadel start`.
|
||||
|
||||
## Configuration
|
||||
|
||||
Read [on the configure page](/guides/manage/self-hosted/configure) about the available options you have to configure ZITADEL.
|
||||
|
||||
## Networking
|
||||
|
||||
- To make ZITADEL available at the domain of your choice, [you need to configure the ExternalDomain property](/guides/manage/self-hosted/custom-domain).
|
||||
- To enable and restrict access to **HTTPS**, head over to [the description of your TLS options](/guides/manage/self-hosted/tls_modes).
|
||||
- If you want to front ZITADEL with a reverse proxy, web application firewall or content delivery network, make sure to support **[HTTP/2](/guides/manage/self-hosted/http2)**.
|
||||
- You can also refer to some **[example reverse proxy configurations](/guides/manage/self-hosted/reverseproxy/reverse_proxy)**.
|
||||
- The ZITADEL Console web GUI uses many gRPC-Web stubs. This results in a fairly big JavaScript bundle. You might want to compress it using [Gzip](https://www.gnu.org/software/gzip/) or [Brotli](https://github.com/google/brotli).
|
||||
- Serving and caching the assets using a content delivery network could improve network latencies and shield your ZITADEL runtime.
|
||||
|
||||
## Monitoring
|
||||
|
||||
By default, [**metrics**](/apis/observability/metrics) are exposed at /debug/metrics in OpenTelemetry (otel) format.
|
||||
|
||||
Also, you can enable **tracing** in the ZITADEL configuration.
|
||||
|
||||
```yaml
|
||||
Tracing:
|
||||
# Choose one in "otel", "google", "log" and "none"
|
||||
Type: google
|
||||
Fraction: 1
|
||||
MetricPrefix: zitadel
|
||||
```
|
||||
|
||||
## Database
|
||||
|
||||
### Prefer CockroachDB
|
||||
|
||||
ZITADEL supports [CockroachDB](https://www.cockroachlabs.com/) and [PostgreSQL](https://www.postgresql.org/).
|
||||
We highly recommend using CockroachDB,
|
||||
as horizontal scaling is much easier than with PostgreSQL.
|
||||
Also, if you are concerned about multi-regional data locality,
|
||||
[the way to go is with CockroachDB](https://www.cockroachlabs.com/docs/stable/multiregion-overview.html).
|
||||
|
||||
### Configure ZITADEL
|
||||
|
||||
Depending on your environment, you maybe would want to tweak some settings about how ZITADEL interacts with the database in the database section of your ZITADEL configuration. Read more about your [database configuration options](/guides/manage/self-hosted/database).
|
||||
|
||||
```yaml
|
||||
Database:
|
||||
cockroach:
|
||||
Host: localhost
|
||||
Port: 26257
|
||||
Database: zitadel
|
||||
//highlight-start
|
||||
MaxOpenConns: 20
|
||||
MaxConnLifetime: 30m
|
||||
MaxConnIdleTime: 30m
|
||||
//highlight-end
|
||||
Options: ""
|
||||
```
|
||||
|
||||
You also might want to configure how [projections](/concepts/eventstore/implementation#projections) are computed. These are the default values:
|
||||
|
||||
```yaml
|
||||
Projections:
|
||||
RequeueEvery: 60s
|
||||
RetryFailedAfter: 1s
|
||||
MaxFailureCount: 5
|
||||
ConcurrentInstances: 1
|
||||
BulkLimit: 200
|
||||
MaxIterators: 1
|
||||
Customizations:
|
||||
projects:
|
||||
BulkLimit: 2000
|
||||
```
|
||||
|
||||
### Manage your Data
|
||||
|
||||
When designing your backup strategy,
|
||||
it is worth knowing that
|
||||
[ZITADEL is event sourced](/docs/concepts/eventstore/overview).
|
||||
That means, ZITADEL itself is able to recompute its
|
||||
whole state from the records in the table eventstore.events.
|
||||
The timestamp of your last record in the events table
|
||||
defines up to which point in time ZITADEL can restore its state.
|
||||
|
||||
The ZITADEL binary itself is stateless,
|
||||
so there is no need for a special backup job.
|
||||
|
||||
Generally, for maintaining your database management system in production,
|
||||
please refer to the corresponding docs
|
||||
[for CockroachDB](https://www.cockroachlabs.com/docs/stable/recommended-production-settings.html)
|
||||
or [for PostgreSQL](https://www.postgresql.org/docs/current/admin.html).
|
||||
|
||||
|
||||
## Data Initialization
|
||||
|
||||
- You can configure instance defaults in the DefaultInstance section.
|
||||
If you plan to eventually create [multiple virtual instances](/concepts/structure/instance#multiple-virtual-instances), these defaults take effect.
|
||||
Also, these configurations apply to the first instance, that ZITADEL automatically creates for you.
|
||||
Especially the following properties are of special interest for your production setup.
|
||||
|
||||
```yaml
|
||||
DefaultInstance:
|
||||
OIDCSettings:
|
||||
AccessTokenLifetime: 12h
|
||||
IdTokenLifetime: 12h
|
||||
RefreshTokenIdleExpiration: 720h #30d
|
||||
RefreshTokenExpiration: 2160h #90d
|
||||
# this configuration sets the default email configuration
|
||||
SMTPConfiguration:
|
||||
# configuration of the host
|
||||
SMTP:
|
||||
#for example smtp.mailtrap.io:2525
|
||||
Host:
|
||||
User:
|
||||
Password:
|
||||
TLS:
|
||||
# if the host of the sender is different from ExternalDomain set DefaultInstance.DomainPolicy.SMTPSenderAddressMatchesInstanceDomain to false
|
||||
From:
|
||||
FromName:
|
||||
```
|
||||
|
||||
- If you don't want to use the DefaultInstance configuration for the first instance that ZITADEL automatically creates for you during the [setup phase](/guides/manage/self-hosted/configure#database-initialization), you can provide a FirstInstance YAML section using the --steps argument.
|
||||
- Learn how to configure ZITADEL via the [Console user interface](/guides/manage/console/overview).
|
||||
- Probably, you also want to [apply your custom branding](/guides/manage/customize/branding), [hook into certain events](/guides/manage/customize/behavior), [customize texts](/guides/manage/customize/texts) or [add metadata to your users](/guides/manage/customize/user-metadata).
|
||||
- If you want to automatically create ZITADEL resources, you can use the [ZITADEL Terraform Provider](/guides/manage/terraform/basics).
|
||||
@@ -1,25 +0,0 @@
|
||||
## TLS mode external
|
||||
|
||||
```
|
||||
https://localhost {
|
||||
reverse_proxy h2c://localhost:8080
|
||||
tls internal #only non production
|
||||
}
|
||||
```
|
||||
|
||||
## TLS mode enabled
|
||||
|
||||
```
|
||||
https://localhost {
|
||||
reverse_proxy https://localhost:8080
|
||||
tls internal #only non production
|
||||
}
|
||||
```
|
||||
|
||||
## TLS mode disabled
|
||||
|
||||
```
|
||||
http://localhost {
|
||||
reverse_proxy h2c://localhost:8080
|
||||
}
|
||||
```
|
||||
@@ -1,18 +0,0 @@
|
||||
## Settings
|
||||
|
||||
- [Make sure HTTP/2 is enabled](https://support.cloudflare.com/hc/en-us/articles/200168076-Understanding-Cloudflare-HTTP-2-and-HTTP-3-Support)
|
||||
- [Verify that gRPC is enabled](https://support.cloudflare.com/hc/en-us/articles/360050483011-Understanding-Cloudflare-gRPC-support)
|
||||
- [Verify that traffic is proxied through cloudflare](https://developers.cloudflare.com/dns/manage-dns-records/reference/proxied-dns-records/)
|
||||
- [Configure ZITADEL to use the TLS Mode enabled](/guides/manage/self-hosted/tls_modes#enabled)
|
||||
|
||||
:::info
|
||||
[Cloudflare does only support gRPC with TLS!](https://support.cloudflare.com/hc/en-us/articles/360050483011-Understanding-Cloudflare-gRPC-support)
|
||||
:::
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If something is not working please check the cloudflare WAF rules for potential violations.
|
||||
These two rules are known to be triggered:
|
||||
|
||||
- 100001 Anomaly:Header:User-Agent - Missing Cloudflare Specials
|
||||
- 100004 Anomaly:Header:User-Agent, Anomaly:Header:Referer - Missing or empty
|
||||
@@ -1,3 +0,0 @@
|
||||
:::caution
|
||||
|
||||
[The Cloudflare tunnel client currently has an issue which allows it not to force HTTP/2 usage towards the origin.](https://github.com/cloudflare/cloudflared/issues/682)
|
||||
@@ -1,166 +0,0 @@
|
||||
## TLS mode external
|
||||
|
||||
```
|
||||
LoadModule mpm_event_module modules/mod_mpm_event.so
|
||||
LoadModule authn_file_module modules/mod_authn_file.so
|
||||
LoadModule authn_core_module modules/mod_authn_core.so
|
||||
LoadModule authz_host_module modules/mod_authz_host.so
|
||||
LoadModule authz_groupfile_module modules/mod_authz_groupfile.so
|
||||
LoadModule authz_user_module modules/mod_authz_user.so
|
||||
LoadModule authz_core_module modules/mod_authz_core.so
|
||||
LoadModule access_compat_module modules/mod_access_compat.so
|
||||
LoadModule auth_basic_module modules/mod_auth_basic.so
|
||||
LoadModule reqtimeout_module modules/mod_reqtimeout.so
|
||||
LoadModule filter_module modules/mod_filter.so
|
||||
LoadModule mime_module modules/mod_mime.so
|
||||
LoadModule log_config_module modules/mod_log_config.so
|
||||
LoadModule env_module modules/mod_env.so
|
||||
LoadModule headers_module modules/mod_headers.so
|
||||
LoadModule setenvif_module modules/mod_setenvif.so
|
||||
LoadModule version_module modules/mod_version.so
|
||||
LoadModule proxy_module modules/mod_proxy.so
|
||||
LoadModule proxy_http_module modules/mod_proxy_http.so
|
||||
LoadModule ssl_module modules/mod_ssl.so
|
||||
LoadModule proxy_http2_module modules/mod_proxy_http2.so
|
||||
LoadModule unixd_module modules/mod_unixd.so
|
||||
LoadModule status_module modules/mod_status.so
|
||||
LoadModule autoindex_module modules/mod_autoindex.so
|
||||
LoadModule dir_module modules/mod_dir.so
|
||||
LoadModule alias_module modules/mod_alias.so
|
||||
LoadModule rewrite_module modules/mod_rewrite.so
|
||||
|
||||
ServerRoot "/usr/local/apache2"
|
||||
LogLevel warn
|
||||
ErrorLog /proc/self/fd/2
|
||||
CustomLog /proc/self/fd/1 "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\""
|
||||
|
||||
ServerName my.domain
|
||||
Listen 80
|
||||
Listen 443
|
||||
|
||||
SSLRandomSeed startup builtin
|
||||
SSLRandomSeed connect builtin
|
||||
|
||||
<VirtualHost *:80>
|
||||
ServerName my.domain
|
||||
RewriteEngine On
|
||||
RewriteCond %{HTTPS} off
|
||||
RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI}
|
||||
</VirtualHost>
|
||||
|
||||
<VirtualHost *:443>
|
||||
ServerName my.domain
|
||||
ProxyPreserveHost On
|
||||
SSLCertificateFile /certs/server.crt
|
||||
SSLCertificateKeyFile /certs/server.key
|
||||
ProxyPass / h2c://localhost:8080/
|
||||
ProxyPassReverse / h2c://localhost:8080/
|
||||
</VirtualHost>
|
||||
```
|
||||
|
||||
## TLS mode enabled
|
||||
|
||||
```
|
||||
LoadModule mpm_event_module modules/mod_mpm_event.so
|
||||
LoadModule authn_file_module modules/mod_authn_file.so
|
||||
LoadModule authn_core_module modules/mod_authn_core.so
|
||||
LoadModule authz_host_module modules/mod_authz_host.so
|
||||
LoadModule authz_groupfile_module modules/mod_authz_groupfile.so
|
||||
LoadModule authz_user_module modules/mod_authz_user.so
|
||||
LoadModule authz_core_module modules/mod_authz_core.so
|
||||
LoadModule access_compat_module modules/mod_access_compat.so
|
||||
LoadModule auth_basic_module modules/mod_auth_basic.so
|
||||
LoadModule reqtimeout_module modules/mod_reqtimeout.so
|
||||
LoadModule filter_module modules/mod_filter.so
|
||||
LoadModule mime_module modules/mod_mime.so
|
||||
LoadModule log_config_module modules/mod_log_config.so
|
||||
LoadModule env_module modules/mod_env.so
|
||||
LoadModule headers_module modules/mod_headers.so
|
||||
LoadModule setenvif_module modules/mod_setenvif.so
|
||||
LoadModule version_module modules/mod_version.so
|
||||
LoadModule proxy_module modules/mod_proxy.so
|
||||
LoadModule proxy_http_module modules/mod_proxy_http.so
|
||||
LoadModule ssl_module modules/mod_ssl.so
|
||||
LoadModule proxy_http2_module modules/mod_proxy_http2.so
|
||||
LoadModule unixd_module modules/mod_unixd.so
|
||||
LoadModule status_module modules/mod_status.so
|
||||
LoadModule autoindex_module modules/mod_autoindex.so
|
||||
LoadModule dir_module modules/mod_dir.so
|
||||
LoadModule alias_module modules/mod_alias.so
|
||||
LoadModule rewrite_module modules/mod_rewrite.so
|
||||
LoadModule http2_module modules/mod_http2.so
|
||||
|
||||
ServerRoot "/usr/local/apache2"
|
||||
LogLevel debug
|
||||
ErrorLog /proc/self/fd/2
|
||||
CustomLog /proc/self/fd/1 "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\""
|
||||
|
||||
ServerName my.domain
|
||||
Listen 80
|
||||
Listen 443
|
||||
|
||||
SSLRandomSeed startup builtin
|
||||
SSLRandomSeed connect builtin
|
||||
|
||||
<VirtualHost *:80>
|
||||
RewriteEngine On
|
||||
RewriteCond %{HTTPS} off
|
||||
RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI}
|
||||
</VirtualHost>
|
||||
|
||||
<VirtualHost *:443>
|
||||
ProxyPreserveHost On
|
||||
SSLEngine on
|
||||
SSLProxyEngine on
|
||||
SSLCertificateFile /certs/server.crt
|
||||
SSLCertificateKeyFile /certs/server.key
|
||||
ProxyPass / h2://localhost:8080/
|
||||
</VirtualHost>
|
||||
```
|
||||
|
||||
## TLS mode disabled
|
||||
|
||||
```
|
||||
LoadModule mpm_event_module modules/mod_mpm_event.so
|
||||
LoadModule authn_file_module modules/mod_authn_file.so
|
||||
LoadModule authn_core_module modules/mod_authn_core.so
|
||||
LoadModule authz_host_module modules/mod_authz_host.so
|
||||
LoadModule authz_groupfile_module modules/mod_authz_groupfile.so
|
||||
LoadModule authz_user_module modules/mod_authz_user.so
|
||||
LoadModule authz_core_module modules/mod_authz_core.so
|
||||
LoadModule access_compat_module modules/mod_access_compat.so
|
||||
LoadModule auth_basic_module modules/mod_auth_basic.so
|
||||
LoadModule reqtimeout_module modules/mod_reqtimeout.so
|
||||
LoadModule filter_module modules/mod_filter.so
|
||||
LoadModule mime_module modules/mod_mime.so
|
||||
LoadModule log_config_module modules/mod_log_config.so
|
||||
LoadModule env_module modules/mod_env.so
|
||||
LoadModule headers_module modules/mod_headers.so
|
||||
LoadModule setenvif_module modules/mod_setenvif.so
|
||||
LoadModule version_module modules/mod_version.so
|
||||
LoadModule proxy_module modules/mod_proxy.so
|
||||
LoadModule proxy_http_module modules/mod_proxy_http.so
|
||||
LoadModule ssl_module modules/mod_ssl.so
|
||||
LoadModule proxy_http2_module modules/mod_proxy_http2.so
|
||||
LoadModule unixd_module modules/mod_unixd.so
|
||||
LoadModule status_module modules/mod_status.so
|
||||
LoadModule autoindex_module modules/mod_autoindex.so
|
||||
LoadModule dir_module modules/mod_dir.so
|
||||
LoadModule alias_module modules/mod_alias.so
|
||||
LoadModule rewrite_module modules/mod_rewrite.so
|
||||
|
||||
ServerRoot "/usr/local/apache2"
|
||||
LogLevel warn
|
||||
ErrorLog /proc/self/fd/2
|
||||
CustomLog /proc/self/fd/1 "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\""
|
||||
|
||||
ServerName my.domain
|
||||
Listen 80
|
||||
|
||||
<VirtualHost *:80>
|
||||
ServerName my.domain
|
||||
ProxyPreserveHost On
|
||||
ProxyPass / h2c://localhost:8080/
|
||||
ProxyPassReverse / h2c://localhost:8080/
|
||||
</VirtualHost>
|
||||
```
|
||||
@@ -1,4 +0,0 @@
|
||||
## More information
|
||||
|
||||
- [You can read here about the TLS Modes](/guides/manage/self-hosted/tls_modes)
|
||||
- [And here about how ZITADEL makes use of HTTP/2](/guides/manage/self-hosted/http2)
|
||||
@@ -1,95 +0,0 @@
|
||||
## TLS mode external
|
||||
|
||||
```
|
||||
worker_processes 1;
|
||||
events {
|
||||
worker_connections 1024;
|
||||
}
|
||||
|
||||
http {
|
||||
server {
|
||||
listen 443;
|
||||
|
||||
ssl_certificate ssl/certificate.pem;
|
||||
ssl_certificate_key ssl/key.pem;
|
||||
|
||||
location / {
|
||||
grpc_pass grpc://localhost:8080;
|
||||
grpc_set_header Host $host;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
:::info
|
||||
If another port than the default HTTPS port 443 is used replace
|
||||
|
||||
` grpc_set_header Host $host;`
|
||||
|
||||
with
|
||||
|
||||
` grpc_set_header Host $host:$server_port;`
|
||||
:::
|
||||
|
||||
## TLS mode enabled
|
||||
|
||||
```
|
||||
worker_processes 1;
|
||||
events {
|
||||
worker_connections 1024;
|
||||
}
|
||||
|
||||
http {
|
||||
server {
|
||||
listen 443;
|
||||
|
||||
ssl_certificate ssl/certificate.pem;
|
||||
ssl_certificate_key ssl/key.pem;
|
||||
|
||||
location / {
|
||||
grpc_pass grpcs://localhost:8080;
|
||||
grpc_set_header Host $host;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
:::info
|
||||
If another port than the default HTTPS port 443 is used replace
|
||||
|
||||
` grpc_set_header Host $host;`
|
||||
|
||||
with
|
||||
|
||||
` grpc_set_header Host $host:$server_port;`
|
||||
:::
|
||||
|
||||
## TLS mode disabled
|
||||
|
||||
```
|
||||
worker_processes 1;
|
||||
events {
|
||||
worker_connections 1024;
|
||||
}
|
||||
|
||||
http {
|
||||
server {
|
||||
listen 80;
|
||||
|
||||
location / {
|
||||
grpc_pass grpc://localhost:8080;
|
||||
grpc_set_header Host $host;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
:::info
|
||||
If another port than the default HTTP port 80 is used replace
|
||||
|
||||
` grpc_set_header Host $host;`
|
||||
|
||||
with
|
||||
|
||||
` grpc_set_header Host $host:$server_port;`
|
||||
:::
|
||||
@@ -1,144 +0,0 @@
|
||||
## TLS mode external
|
||||
|
||||
```yaml
|
||||
entrypoints:
|
||||
web:
|
||||
address: ":80"
|
||||
websecure:
|
||||
address: ":443"
|
||||
tls:
|
||||
stores:
|
||||
default:
|
||||
defaultCertificate:
|
||||
providers:
|
||||
file:
|
||||
filename: /etc/traefik/traefik.yaml
|
||||
http:
|
||||
middlewares:
|
||||
zitadel:
|
||||
headers:
|
||||
isDevelopment: false
|
||||
allowedHosts:
|
||||
- 'localhost'
|
||||
redirect-to-https:
|
||||
redirectScheme:
|
||||
scheme: https
|
||||
port: 443
|
||||
permanent: true
|
||||
routers:
|
||||
router0:
|
||||
entryPoints:
|
||||
- web
|
||||
middlewares:
|
||||
- redirect-to-https
|
||||
rule: 'HostRegexp(`localhost`, `{subdomain:[a-z]+}.localhost`)'
|
||||
service: zitadel
|
||||
router1:
|
||||
entryPoints:
|
||||
- websecure
|
||||
service: zitadel
|
||||
middlewares:
|
||||
- zitadel
|
||||
rule: 'HostRegexp(`localhost`, `{subdomain:[a-z]+}.localhost`)'
|
||||
tls:
|
||||
domains:
|
||||
- main: "localhost"
|
||||
sans:
|
||||
- "*.localhost"
|
||||
- "localhost"
|
||||
services:
|
||||
zitadel:
|
||||
loadBalancer:
|
||||
servers:
|
||||
- url: h2c://localhost:8080
|
||||
passHostHeader: true
|
||||
```
|
||||
|
||||
## TLS mode enabled
|
||||
|
||||
```yaml
|
||||
entrypoints:
|
||||
web:
|
||||
address: ":80"
|
||||
websecure:
|
||||
address: ":443"
|
||||
tls:
|
||||
stores:
|
||||
default:
|
||||
defaultCertificate:
|
||||
providers:
|
||||
file:
|
||||
filename: /etc/traefik/traefik.yaml
|
||||
http:
|
||||
middlewares:
|
||||
zitadel:
|
||||
headers:
|
||||
isDevelopment: false
|
||||
allowedHosts:
|
||||
- 'localhost'
|
||||
redirect-to-https:
|
||||
redirectScheme:
|
||||
scheme: https
|
||||
port: 443
|
||||
permanent: true
|
||||
routers:
|
||||
router0:
|
||||
entryPoints:
|
||||
- web
|
||||
middlewares:
|
||||
- redirect-to-https
|
||||
rule: 'HostRegexp(`localhost`, `{subdomain:[a-z]+}.localhost`)'
|
||||
service: zitadel
|
||||
# The actual ZITADEL router
|
||||
router1:
|
||||
entryPoints:
|
||||
- websecure
|
||||
service: zitadel
|
||||
middlewares:
|
||||
- zitadel
|
||||
rule: 'HostRegexp(`localhost`, `{subdomain:[a-z]+}.localhost`)'
|
||||
tls:
|
||||
domains:
|
||||
- main: "localhost"
|
||||
sans:
|
||||
- "*.localhost"
|
||||
- "localhost"
|
||||
services:
|
||||
zitadel:
|
||||
loadBalancer:
|
||||
servers:
|
||||
- url: https://localhost:8080
|
||||
passHostHeader: true
|
||||
```
|
||||
|
||||
## TLS mode disabled
|
||||
|
||||
```yaml
|
||||
entrypoints:
|
||||
web:
|
||||
address: ":80"
|
||||
providers:
|
||||
file:
|
||||
filename: /etc/traefik/traefik.yaml
|
||||
http:
|
||||
middlewares:
|
||||
zitadel:
|
||||
headers:
|
||||
isDevelopment: false
|
||||
allowedHosts:
|
||||
- 'localhost'
|
||||
routers:
|
||||
router0:
|
||||
entryPoints:
|
||||
- web
|
||||
middlewares:
|
||||
- redirect-to-https
|
||||
rule: 'HostRegexp(`localhost`, `{subdomain:[a-z]+}.localhost`)'
|
||||
service: zitadel
|
||||
services:
|
||||
zitadel:
|
||||
loadBalancer:
|
||||
servers:
|
||||
- url: h2c://localhost:8080
|
||||
passHostHeader: true
|
||||
```
|
||||
@@ -1,11 +0,0 @@
|
||||
## Fronting ZITADEL Cloud
|
||||
|
||||
You can use your reverseproxy, content delivery network (CDN) or web application firewall (WAF) to front ZITADEL Cloud.
|
||||
However we currently do not recommend this for production settings.
|
||||
|
||||
To configure your service that fronts ZITADEL please have a look at the vendors in this page.
|
||||
|
||||
## Things to look out for when fronting ZITADEL Cloud
|
||||
|
||||
- Cache-control - ZITADEL Cloud uses a CDN to globally distribute data. Please try to avoid overriding this header as it may lead to sideeffects
|
||||
- Rate Limits - ZITADEL Cloud uses a combination of static and dynamic rate limits. If you recieve occasional 429 headers you are rate limited.
|
||||
@@ -1,59 +0,0 @@
|
||||
---
|
||||
title: Reverse Proxy Configuration
|
||||
---
|
||||
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem";
|
||||
import Zcloud from "./_zitadel_cloud.mdx";
|
||||
import Nginx from "./_nginx.mdx";
|
||||
import Traefik from "./_traefik.mdx";
|
||||
import Caddy from "./_caddy.mdx";
|
||||
import Httpd from "./_httpd.mdx";
|
||||
import Cftunnel from "./_cloudflare_tunnel.mdx";
|
||||
import Cloudflare from "./_cloudflare.mdx";
|
||||
import More from "./_more.mdx";
|
||||
|
||||
# Proxy Configuration
|
||||
|
||||
<Tabs
|
||||
groupId="proxy-vendor"
|
||||
default="zcloud"
|
||||
values={[
|
||||
{ label: "ZITADEL Cloud", value: "zcloud" },
|
||||
{ label: "NGINX", value: "nginx" },
|
||||
{ label: "Traefik", value: "traefik" },
|
||||
{ label: "Caddy", value: "caddy" },
|
||||
{ label: "Apache httpd", value: "httpd" },
|
||||
{ label: "Cloudflare Tunnel", value: "cftunnel" },
|
||||
{ label: "Cloudflare", value: "cf" },
|
||||
]}
|
||||
>
|
||||
<TabItem value="zcloud">
|
||||
<Zcloud />
|
||||
<More />
|
||||
</TabItem>
|
||||
<TabItem value="nginx">
|
||||
<Nginx />
|
||||
<More />
|
||||
</TabItem>
|
||||
<TabItem value="traefik">
|
||||
<Traefik />
|
||||
<More />
|
||||
</TabItem>
|
||||
<TabItem value="caddy">
|
||||
<Caddy />
|
||||
<More />
|
||||
</TabItem>
|
||||
<TabItem value="httpd">
|
||||
<Httpd />
|
||||
<More />
|
||||
</TabItem>
|
||||
<TabItem value="cftunnel">
|
||||
<Cftunnel />
|
||||
<More />
|
||||
</TabItem>
|
||||
<TabItem value="cf">
|
||||
<Cloudflare />
|
||||
<More />
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
@@ -1,58 +0,0 @@
|
||||
---
|
||||
title: TLS Modes
|
||||
---
|
||||
|
||||
To allow ZITADEL to be run on any kind of infrastrucute it allows to configure on how tho handle TLS connections.
|
||||
There are three mode of operation: `external`, `enabled`, `disabled`.
|
||||
|
||||
Generally this command is set as argument while starting ZITADEL. For example like this:
|
||||
|
||||
```bash
|
||||
zitadel start-from-init --masterkey "MasterkeyNeedsToHave32Characters" --tlsMode disabled
|
||||
```
|
||||
|
||||
## External
|
||||
|
||||
The mode `external` allows you to configure ZITADEL in such a way that it will instruct its clients to use https.
|
||||
However ZITADEL delegates the management of TLS connections to a reverseproxy, web application firewall or a service mesh.
|
||||
|
||||
## Enabled
|
||||
|
||||
When using the mode `enabled` ZITADEL is setup to await incoming connections in an encrypted fashion.
|
||||
Wether it is from a client directly, a reverseproxy or web application firewall.
|
||||
This allows http connections to be secured at the transport level the whole way.
|
||||
|
||||
If you use the mode `enabled` you need to configure ZITADEL with the nessecary TLS settings.
|
||||
|
||||
```yaml
|
||||
TLS:
|
||||
# if enabled, ZITADEL will serve all traffic over TLS (HTTPS and gRPC)
|
||||
# you must then also provide a private key and certificate to be used for the connection
|
||||
# either directly or by a path to the corresponding file
|
||||
Enabled: true
|
||||
# Path to the private key of the TLS certificate, it will be loaded into the Key
|
||||
# and overwrite any exising value
|
||||
KeyPath: #/path/to/key/file.pem
|
||||
# Private key of the TLS certificate (KeyPath will this overwrite, if specified)
|
||||
Key: #<bas64 encoded content of a pem file>
|
||||
# Path to the certificate for the TLS connection, it will be loaded into the Cert
|
||||
# and overwrite any exising value
|
||||
CertPath: #/path/to/cert/file.pem
|
||||
# Certificate for the TLS connection (CertPath will this overwrite, if specified)
|
||||
Cert: #<bas64 encoded content of a pem file>
|
||||
```
|
||||
|
||||
## Disabled
|
||||
|
||||
With the mode `disabled` ZITADEL is instructed to await all connections with plain http without TLS.
|
||||
|
||||
:::caution
|
||||
|
||||
Be aware this is not a secure setup and should only be used for test systems!
|
||||
|
||||
:::
|
||||
|
||||
## HTTP/2
|
||||
|
||||
To allow ZITADEL to function properly please make sure that HTTP/2 is enabled. If you are using the mode `external` or `disabled` make sure to verify h2c compatibilty.
|
||||
You can read more about how ZITADEL utilizes in our [HTTP/2 docs](/guides/manage/self-hosted/http2).
|
||||
@@ -1 +1 @@
|
||||
If you choose to run a local instance have a look at our [deploy](../deploy/overview) section, where we show you different possibilities on how to run ZITADEL.
|
||||
If you choose to run a local instance have a look at our [deploy](/self-hosting/deploy/overview) section, where we show you different possibilities on how to run ZITADEL.
|
||||
@@ -29,7 +29,7 @@ Chose [ZITADEL Cloud](../manage/cloud/overview) if you want:
|
||||
- Global scalability without the headache of running
|
||||
- Data residency compliance for your customers
|
||||
|
||||
Chose [ZITADEL Self-Hosted](../deploy/overview) if you want:
|
||||
Chose [ZITADEL Self-Hosted](/self-hosting/deploy/overview) if you want:
|
||||
|
||||
- Total control over all components and your data
|
||||
- Run ZITADEL in air gapped or regulated environemnts
|
||||
@@ -78,4 +78,4 @@ This takes place in the ZITADEL Console
|
||||
ZITADEL allows you to give other users control over the ZITADEL Console. The manager role can be restricted to some kind of write and/or read.
|
||||
This is especially useful for direct administration over several users. You can have managers able to edit project settings and others able to create/add users only.
|
||||
|
||||
> Note: ZITADEL Managers are located on the right side panel of the ZITADEL Console.
|
||||
> Note: ZITADEL Managers are located on the right side panel of the ZITADEL Console.
|
||||
Reference in New Issue
Block a user