template-monorepo/deploy/zitadel/README.md

ZITADEL（dev / k6）

本機跑 k6 測試用的 ZITADEL stack（docker-compose profile: k6）。

啟動

make k6-up

會啟動 mongo / redis / mailhog / postgres / zitadel。

ZITADEL 首次啟動會 init Postgres schema 並執行 steps.yaml 預載：

• Instance 名稱：ZITADEL
• Org：GatewayDev
• Admin 使用者：zitadel-admin@zitadel.localhost / Password1!
• Service Account：zitadel-admin-sa（產生 PAT 寫到 machinekey/zitadel-admin-sa.token）

完成需 30~90 秒，可用 make k6-wait 等到 /debug/healthz 200。

PAT 取用

cat deploy/zitadel/machinekey/zitadel-admin-sa.token

把這個值塞進 etc/gateway.k6.yaml 的 Zitadel.ServiceUserToken，或用環境變數：

export ZITADEL_SERVICE_TOKEN=$(cat deploy/zitadel/machinekey/zitadel-admin-sa.token)

make k6-gateway 會自動做這件事。

密碼登入（/auth/login）

ZITADEL v2 預設停用 OAuth Resource Owner Password Grant（unsupported_grant_type）。 本 repo 的 Gateway 在未設定 OAuthClientID / OAuthClientSecret 時，會改用 v2 Sessions API（PAT）驗證密碼，無需額外建立 OIDC App。

若要在正式環境使用 ROPG，請自行建立 OIDC Application 並設定：

export ZITADEL_OAUTH_CLIENT_ID=...
export ZITADEL_OAUTH_CLIENT_SECRET=...

重設

make k6-down                                    # 停容器（保留 volume）
docker volume rm template-monorepo_postgres_data   # 清 ZITADEL 資料
rm deploy/zitadel/machinekey/zitadel-admin-sa.*    # 清 PAT

端點

• Console UI：http://localhost:8080/ui/console
• OIDC issuer：http://localhost:8080
• Management API：http://localhost:8080/management/v1
• Health：http://localhost:8080/debug/healthz

不可帶上 prod

MasterkeyNeedsToHave32Characters 與 steps.yaml 內的密碼都是固定 dev 值，只能本機用。