docs: self-hosting with login v2

2025-08-12 13:37:35 +00:00 · 2025-07-02 10:47:51 +02:00
parent 2928c6ac2b
commit a6ccb34eff
6 changed files with 56 additions and 66 deletions
--- a/docs/docs/self-hosting/deploy/loadbalancing-example/.gitignore
+++ b/docs/docs/self-hosting/deploy/loadbalancing-example/.gitignore
@@ -1 +1 @@
-.env-file
+pat
--- a/docs/docs/self-hosting/deploy/loadbalancing-example/docker-compose.yaml
+++ b/docs/docs/self-hosting/deploy/loadbalancing-example/docker-compose.yaml
@@ -22,7 +22,10 @@ services:
    networks:
      - 'storage'
    image: 'ghcr.io/zitadel/zitadel:latest'
-    command: 'init --config /example-zitadel-config.yaml --config /example-zitadel-secrets.yaml'
+    command: >
+      init
+      --config /example-zitadel-config.yaml
+      --config /example-zitadel-secrets.yaml
    depends_on:
      db:
        condition: 'service_healthy'
@@ -34,32 +37,18 @@ services:
    restart: 'no'
    networks:
      - 'storage'
-    # We use the debug image so we have the environment to
-    # - create the .env file for the login to authenticate at Zitadel
-    # - set the correct permissions for the .env-file folder
-    image: 'ghcr.io/zitadel/zitadel:latest-debug'
-    user: root
-    entrypoint: '/bin/sh'
-    command:
-    - -c
-    - >
-      /app/zitadel setup
+    image: 'ghcr.io/zitadel/zitadel:latest'
+    command: >
+      setup 
      --config /example-zitadel-config.yaml
      --config /example-zitadel-secrets.yaml
      --steps /example-zitadel-init-steps.yaml
-      --masterkey ${ZITADEL_MASTERKEY} &&
-      mv /pat /.env-file/pat || exit 0 &&
-      echo ZITADEL_SERVICE_USER_TOKEN=$(cat /.env-file/pat) > /.env-file/.env &&
-      chown -R 1001:${GID} /.env-file &&
-      chmod -R 770 /.env-file
-    environment:
-      - GID
+      --masterkey ${ZITADEL_MASTERKEY}
    depends_on:
      zitadel-init:
        condition: 'service_completed_successfully'
-        restart: false
    volumes:
-      - './.env-file:/.env-file:rw'
+      - '.:/pat-dir:rw'
      - './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'
@@ -71,7 +60,8 @@ services:
      - 'storage'
    image: 'ghcr.io/zitadel/zitadel:latest'
    command: >
-      start --config /example-zitadel-config.yaml
+      start
+      --config /example-zitadel-config.yaml
      --config /example-zitadel-secrets.yaml
      --masterkey ${ZITADEL_MASTERKEY}
    depends_on:
@@ -94,40 +84,18 @@ services:
      retries: 5
      start_period: 10s

-  # The use-new-login service configures Zitadel to use the new login v2 for all applications.
-  # It also gives the setupped machine user the necessary IAM_LOGIN_CLIENT role.
-  use-new-login:
-    restart: 'on-failure'
-    user: "1001"
-    networks:
-      - 'backend'
-    image: 'badouralix/curl-jq:alpine'
-    entrypoint: '/bin/sh'
-    command:
-      - -c
-      - >
-        curl -X PUT -H "Host: 127.0.0.1.sslip.io" -H "Authorization: Bearer $(cat ./.env-file/pat)" --insecure http://zitadel:8080/v2/features/instance -d '{"loginV2": {"required": true}}' &&
-        LOGIN_USER=$(curl --fail-with-body  -H "Host: 127.0.0.1.sslip.io" -H "Authorization: Bearer $(cat ./.env-file/pat)" --insecure http://zitadel:8080/auth/v1/users/me | jq -r '.user.id') &&
-        curl -X PUT  -H "Host: 127.0.0.1.sslip.io" -H "Authorization: Bearer $(cat ./.env-file/pat)" --insecure http://zitadel:8080/admin/v1/members/$${LOGIN_USER} -d '{"roles": ["IAM_OWNER", "IAM_LOGIN_CLIENT"]}'
-    volumes:
-      - './.env-file:/.env-file:ro'
-    depends_on:
-      zitadel:
-        condition: 'service_healthy'
-        restart: false
-
  login:
    restart: 'unless-stopped'
    networks:
      - 'backend'
-    image: 'ghcr.io/zitadel/login:main'
+    image: 'ghcr.io/zitadel/login:latest'
    environment:
      - ZITADEL_API_URL=http://zitadel:8080
      - CUSTOM_REQUEST_HEADERS=Host:127.0.0.1.sslip.io
      - NEXT_PUBLIC_BASE_PATH="/ui/v2/login"
-    user: "${UID:-1000}"
-    volumes:
-      - './.env-file:/.env-file:ro'
+      - ZITADEL_SERVICE_USER_TOKEN_FILE=/run/secrets/login-client-pat
+    secrets:
+      - login-client-pat
    depends_on:
      zitadel:
        condition: 'service_healthy'
@@ -149,6 +117,11 @@ services:
      login:
        condition: 'service_started'

+secrets:
+  login-client-pat:
+    file: './login-client-pat'
+
+
 networks:
  storage:
  backend:
--- a/docs/docs/self-hosting/deploy/loadbalancing-example/example-zitadel-config.yaml
+++ b/docs/docs/self-hosting/deploy/loadbalancing-example/example-zitadel-config.yaml
@@ -16,14 +16,9 @@ Database:
    User.SSL.Mode: 'disable'
    Admin.SSL.Mode: 'disable'

-# By default, ZITADEL should redirect to /ui/v2/login
-OIDC:
-  DefaultLoginURLV2: "/ui/v2/login/login?authRequest=" # ZITADEL_OIDC_DEFAULTLOGINURLV2
-  DefaultLogoutURLV2: "/ui/v2/login/logout?post_logout_redirect=" # ZITADEL_OIDC_DEFAULTLOGOUTURLV2
-SAML.DefaultLoginURLV2: "/ui/v2/login/login?authRequest=" # ZITADEL_SAML_DEFAULTLOGINURLV2
-
 # Access logs allow us to debug Network issues
 LogStore.Access.Stdout.Enabled: true

 # Skipping the MFA init step allows us to immediately authenticate at the console
 DefaultInstance.LoginPolicy.MfaInitSkipLifetime: "0s"
+DefaultInstance.PrivacyPolicy.TOSLink: example.com
--- a/docs/docs/self-hosting/deploy/loadbalancing-example/example-zitadel-init-steps.yaml
+++ b/docs/docs/self-hosting/deploy/loadbalancing-example/example-zitadel-init-steps.yaml
@@ -1,12 +1,13 @@
 # All possible options and their defaults: https://github.com/zitadel/zitadel/blob/main/cmd/setup/steps.yaml
 FirstInstance:
-  PatPath: '/pat'
+  PatPath: '/pat-dir/pat'
+  LoginClientPatPath: '/pat-dir/login-client-pat'
  Org:
    # We want to authenticate immediately at the console without changing the password
    Human:
      PasswordChangeRequired: false
-    Machine:
+    LoginClient:
      Machine:
-        Username: 'login-container'
-        Name: 'Login Container'
+        Username: 'login-client'
+        Name: 'Login Client'
      Pat.ExpirationDate: '2029-01-01T00:00:00Z'
--- a/docs/docs/self-hosting/deploy/loadbalancing-example/loadbalancing-example.mdx
+++ b/docs/docs/self-hosting/deploy/loadbalancing-example/loadbalancing-example.mdx
@@ -60,9 +60,13 @@ wget https://raw.githubusercontent.com/zitadel/zitadel/main/docs/docs/self-hosti

 # A single ZITADEL instance always needs the same 32 bytes long masterkey
 # Generate one to a file if you haven't done so already and pass it as environment variable
-LC_ALL=C tr -dc '[:graph:]' </dev/urandom | head -c 32 > ./zitadel-masterkey
+LC_ALL=C tr -dc '[:alpha:]' </dev/urandom | head -c 32 > ./zitadel-masterkey
 export ZITADEL_MASTERKEY="$(cat ./zitadel-masterkey)"

+# make sure the file ./pat exists so docker compose doesn't complain
+# it will be overwritten by the setup job
+echo "overwritten" > ./pat
+
 # Run the database and application containers
 docker compose up --detach --wait
 ```
--- a/docs/docs/self-hosting/deploy/macos.mdx
+++ b/docs/docs/self-hosting/deploy/macos.mdx
@@ -26,13 +26,14 @@ sudo pg_ctl start -D /tmp/postgresql

 ```bash
 brew install zitadel/tap/zitadel
+brew install node
 ```

 ### Download from GitHub

 Download the ZITADEL release according to your architecture from [Github](https://github.com/zitadel/zitadel/releases/latest)

-## Unpack the archive
+#### Unpack the archive
 move to your download location and unpack the archive

 ```bash
@@ -40,10 +41,26 @@ move to your download location and unpack the archive
 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
+#### Run ZITADEL

 ```bash
-ZITADEL_DATABASE_POSTGRES_HOST=localhost ZITADEL_DATABASE_POSTGRES_PORT=5432 ZITADEL_DATABASE_POSTGRES_DATABASE=zitadel ZITADEL_DATABASE_POSTGRES_USER_USERNAME=zitadel ZITADEL_DATABASE_POSTGRES_USER_PASSWORD=zitadel ZITADEL_DATABASE_POSTGRES_USER_SSL_MODE=disable ZITADEL_DATABASE_POSTGRES_ADMIN_USERNAME=$(whoami) ZITADEL_DATABASE_POSTGRES_ADMIN_PASSWORD=postgres ZITADEL_DATABASE_POSTGRES_ADMIN_SSL_MODE=disable ZITADEL_EXTERNALSECURE=false zitadel start-from-init --masterkey "MasterkeyNeedsToHave32Characters" --tlsMode disabled
+export ZITADEL_LOGIN_CLIENT_PAT_PATH=$(pwd)/login-client-pat
+ZITADEL_DATABASE_POSTGRES_HOST=localhost ZITADEL_DATABASE_POSTGRES_PORT=5432 ZITADEL_DATABASE_POSTGRES_DATABASE=zitadel ZITADEL_DATABASE_POSTGRES_USER_USERNAME=zitadel ZITADEL_DATABASE_POSTGRES_USER_PASSWORD=zitadel ZITADEL_DATABASE_POSTGRES_USER_SSL_MODE=disable ZITADEL_DATABASE_POSTGRES_ADMIN_USERNAME=$(whoami) ZITADEL_DATABASE_POSTGRES_ADMIN_PASSWORD=postgres ZITADEL_DATABASE_POSTGRES_ADMIN_SSL_MODE=disable ZITADEL_EXTERNALSECURE=false ZITADEL_FIRSTINSTANCE_LOGINCLIENTPATPATH=$(echo $ZITADEL_LOGIN_CLIENT_PAT_PATH) ZITADEL_FIRSTINSTANCE_ORG_LOGINCLIENT_MACHINE_USERNAME=zitadel-login-client ZITADEL_FIRSTINSTANCE_ORG_LOGINCLIENT_MACHINE_NAME=zitadel-login-client ZITADEL_FIRSTINSTANCE_ORG_LOGINCLIENT_PAT_EXPIRATIONDATE=2099-01-01T00:00:00Z zitadel start-from-init --masterkey "MasterkeyNeedsToHave32Characters" --tlsMode disabled
+```
+
+#### Unpack the login archive
+
+```bash
+mkdir zitadel-login
+#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/login.tar.gz  |  tar -xzv -C zitadel-login
+
+```
+
+#### Run ZITADEL Login
+
+```bash
+ZITADEL_API_URL=http://localhost:8080 ZITADEL_SERVICE_USER_TOKEN=$(cat $ZITADEL_LOGIN_CLIENT_PAT_PATH) node apps/login/server.js
 ```

 <DefaultUser components={props.components} />