TheArchive/zitadel
1
0
Fork 0
mirror of https://github.com/zitadel/zitadel.git synced 2025-08-11 17:27:31 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(self-hosting): use postgres for deployment docs (#9571)

Browse Source 
# Which Problems Are Solved

The Kubernetes and Knative deployment docs suggest to depend on
CockroachDB installations even though we sunset the CockroachDB support
with the upcoming major version. This can be annoying for users who
create new environments using CockroachDB.

# How the Problems Are Solved

- The Kubernetes deployment is removed and points to examples in the
chart repo directy. This removes redundancies that are prone to getting
outdated without notice.

- The Knative deployment uses commands to deploy a PostgreSQL
StatefulSet instead of a CockroachDB StatefulSet. The DB command from
the Knative Tutorial is used, as users are likely to be familiar with
the tutorials configuration already. The static Kubernetes YAML files
for the DB as well as for the Zitadel Knative service are removed
altogether, as they are prone to getting outdated without notice and
don't serve any purpose.

# Additional Changes

- The outdated and boring video guide for Knative is removed.
- The Knative configuration is changed, so the first-time login becomes
easier which improves DevX.
- The current docker compose file doesn't work, this PR fixes it and
upgrades the used Postgres to v17.

# Additional Context

- Closes https://github.com/zitadel/zitadel-charts/issues/322
- Replaces https://github.com/zitadel/zitadel/pull/9540

Co-authored-by: Silvan <27845747+adlerhurst@users.noreply.github.com>
This commit is contained in:
Elio Bischof
2025-03-21 16:49:37 +01:00
committed by GitHub
parent 8b1b9cbb98
commit 103b190af7
9 changed files with 37 additions and 312 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
docs/docs/self-hosting/deploy/knative.mdx
View File

@@ -13,34 +13,39 @@ import NoteInstanceNotFound from './troubleshooting/_note_instance_not_found.mdx
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
For example, to install Knative on a kind cluster, run `kn quickstart kind`.
Start a single-node cockroachdb as statefulset
## Run PostgreSQL
If you are following the Knative Tutorial, you can deploy Postgres as a StatefulSet for the tutorials Bookstore sample app. For example:
```bash
kubectl apply -f https://raw.githubusercontent.com/zitadel/zitadel/main/deploy/knative/cockroachdb-statefulset-single-node.yaml
git clone https://github.com/knative/docs.git
kubectl apply -f docs/code-samples/eventing/bookstore-sample-app/solution/db-service/
```
## Start ZITADEL
### Knative Command
## Start Zitadel as a Knative Service
```bash
kn service create zitadel \
--image ghcr.io/zitadel/zitadel:latest \
--port 8080 \
--env ZITADEL_DATABASE_COCKROACH_HOST=cockroachdb \
--env ZITADEL_EXTERNALDOMAIN=zitadel.default.127.0.0.1.sslip.io \
--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
--env ZITADEL_DATABASE_POSTGRES_HOST=postgresql \
--env ZITADEL_DATABASE_POSTGRES_PORT=5432 \
--env ZITADEL_DATABASE_POSTGRES_DATABASE=zitadel \
--env ZITADEL_DATABASE_POSTGRES_USER_USERNAME=myzitadeluser \
--env ZITADEL_DATABASE_POSTGRES_USER_PASSWORD=myzitadelpassword \
--env ZITADEL_DATABASE_POSTGRES_USER_SSL_MODE=disable \
--env ZITADEL_DATABASE_POSTGRES_ADMIN_USERNAME=myuser \
--env ZITADEL_DATABASE_POSTGRES_ADMIN_PASSWORD=mypassword \
--env ZITADEL_DATABASE_POSTGRES_ADMIN_SSL_MODE=disable \
--env ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED=false \
--env ZITADEL_DEFAULTINSTANCE_LOGINPOLICY_MFAINITSKIPLIFETIME="0s" \
--arg "start-from-init" --arg "--masterkey=MasterkeyNeedsToHave32Characters"
```
## Access ZITADEL
@@ -54,17 +59,9 @@ NAME URL LATEST AGE COND
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!
Open your browser at http://zitadel.default.127.0.0.1.sslip.io/ui/console?login_hint=zitadel-admin@zitadel.zitadel.default.127.0.0.1.sslip.io and use the initial password _Password1!_
<NoteInstanceNotFound/>
## 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} />

42
docs/docs/self-hosting/manage/configure/_helm.mdx
View File

@@ -1,36 +1,6 @@
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](/self-hosting/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/self-hosting/manage/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/self-hosting/manage/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
```
To run Zitadel on Kubernetes, use [the official Zitadel Helm chart](https://github.com/zitadel/zitadel-charts).
Configure Zitadel using native Helm values.
You can manage secrets through Helm values, letting Helm create Kubernetes secrets.
Alternatively, reference existing Kubernetes secrets managed outside of Helm.
See the [referenced secrets example](https://github.com/zitadel/zitadel-charts/tree/main/examples/3-referenced-secrets) in the charts */examples* folder.
For a quick setup, check out the [insecure Postgres example](https://github.com/zitadel/zitadel-charts/tree/main/examples/1-insecure-postgres).

1
docs/docs/self-hosting/manage/configure/_login.md Normal file
View File

@@ -0,0 +1 @@
Open your favorite internet browser at http://localhost:8080/ui/console?login_hint=root@zitadel.localhost and use the password _RootPassword1!_

9
docs/docs/self-hosting/manage/configure/configure.mdx
View File

@@ -8,6 +8,7 @@ import TabItem from "@theme/TabItem";
import LinuxUnix from "./_linuxunix.mdx";
import Compose from "./_compose.mdx";
import Helm from "./_helm.mdx";
import Login from "./_login.md";
import CodeBlock from "@theme/CodeBlock";
import DefaultsYamlSource from "!!raw-loader!./defaults.yaml";
import StepsYamlSource from "!!raw-loader!./steps.yaml";
@@ -90,21 +91,17 @@ There are three ways to pass the masterkey to the `zitadel` binary:
>
<TabItem value="linuxunix">
<LinuxUnix />
<Login/>
</TabItem>
<TabItem value="compose">
<Compose />
<Login/>
</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](/guides/integrate/login/login-users).

8
docs/docs/self-hosting/manage/configure/docker-compose.yaml
View File

@@ -11,9 +11,12 @@ services:
- "./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"
depends_on:
db:
condition: "service_healthy"
db:
image: postgres:16-alpine
image: postgres:17-alpine
restart: always
environment:
- POSTGRES_USER=root
@@ -25,7 +28,7 @@ services:
interval: 10s
timeout: 60s
retries: 5
start_period: 10s
start_period: 10s
volumes:
- 'data:/var/lib/postgresql/data:rw'
@@ -34,3 +37,4 @@ networks:
volumes:
data:

16
docs/docs/self-hosting/manage/configure/example-zitadel-values-secrets.yaml
View File

@@ -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:
postgres:
User:
# If the user doesn't exist already, it is created
Username: 'root'
Password: 'Secret_DB_User_Password'
Admin:
Username: 'root'
Password: ''

17
docs/docs/self-hosting/manage/configure/example-zitadel-values.yaml
View File

@@ -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 root@zitadel.localhost
Username: 'root'
Password: 'RootPassword1!'