Automatically generated PR targeting 1 files.
**Thread ID:** 1517531035175354430
**Action:** UPDATE
**AI Summary:**
> Documentation does not explain what happens when users bookmark the
login page or access ZITADEL without an OIDC flow, particularly
regarding redirect behavior and the purpose of organization Default
Redirect URI settings.
Co-authored-by: zitadel-knowledge-bot[bot] <296006658+zitadel-knowledge-bot[bot]@users.noreply.github.com>
Automatically generated PR targeting 1 files.
**Thread ID:** 1512031509387673610
**Action:** UPDATE
**AI Summary:**
> The documentation lacks clear explanation of how the 'Use new login
UI' checkbox and 'Custom base URL for the new Login UI' field work
together, including step-by-step configuration and troubleshooting
guidance.
---------
Co-authored-by: zitadel-knowledge-bot[bot] <296006658+zitadel-knowledge-bot[bot]@users.noreply.github.com>
Co-authored-by: fcoppede <[email protected]>
Automatically generated PR targeting 1 files.
**Thread ID:** manual-1782237446658
**Action:** UPDATE
**AI Summary:**
> Need to add a note on this page to encourage users with active
subscriptions to link their github and Discord account because that will
help github issues get higher priority and discord threads as well
Co-authored-by: zitadel-knowledge-bot[bot] <296006658+zitadel-knowledge-bot[bot]@users.noreply.github.com>
<!--
Please inform yourself about the contribution guidelines on submitting a
PR here:
https://github.com/zitadel/zitadel/blob/main/CONTRIBUTING.md#submit-a-pull-request-pr.
Take note of how PR/commit titles should be written and replace the
template texts in the sections below. Don't remove any of the sections.
It is important that the commit history clearly shows what is changed
and why.
Important: By submitting a contribution you agree to the terms from our
Licensing Policy as described here:
https://github.com/zitadel/zitadel/blob/main/LICENSING.md#community-contributions.
-->
# Which Problems Are Solved
The projects setting texts and sceenshot where outdated.
# How the Problems Are Solved
Update the text and screenshot.
# Additional Changes
* Rewording
* Lockout warning component
---------
Co-authored-by: Copilot Autofix powered by AI <[email protected]>
# Which Problems Are Solved
Pages in `apps/docs` that embed source from GitHub via the Docusaurus
convention
````
```js reference
https://github.com/zitadel/actions/blob/main/examples/org_metadata_claim.js
```
````
stopped working after the migration from Docusaurus to fumadocs. The old
`docusaurus-theme-github-codeblock` plugin used to fetch the file and
render it; fumadocs has no support for that meta, so the page rendered
the raw URL as plain code-block text. Visible at
`/docs/apis/actions/code-examples` and 16 other pages.
# How the Problems Are Solved
- Converted every ```` ```<lang> reference\n<URL>\n``` ```` block (46
total across 17 `.mdx` files) to the native fumadocs JSX form:
`<GithubCodeBlock url="<URL>" />`. The existing `<details>`/`<summary>`
collapsibles around blocks are kept — they're an authoring choice, not
part of the rendering bug.
- Updated `apps/docs/components/github-code-block.tsx` to render via
`DynamicCodeBlock` from `fumadocs-ui/components/dynamic-codeblock`
(proper shiki highlighting) instead of raw `CodeBlock` + `Pre` (which
produced unhighlighted output). Also fixed language detection so a URL
hash like `#L10-L20` no longer pollutes the language token.
- Registered `GithubCodeBlock` globally in
`apps/docs/mdx-components.tsx`, matching how every other shared
component (`APIPage`, `Callout`, `Tab/Tabs`, `Step/Steps`, `Admonition`,
`TerminologyUpdate`) is exposed. MDX files no longer need a local
`import`.
# Additional Changes
- Normalized the two MDX files that were already using the JSX form
(`examples/secure-api/python-django.mdx`,
`examples/secure-api/java-spring.mdx`): removed their now-redundant
local `import { GithubCodeBlock }` and rewrote 9 long-form
`<GithubCodeBlock url="..."></GithubCodeBlock>` tags to self-closing for
consistency.
# Additional Context
Verified locally with `pnpm --filter @zitadel/docs dev`:
- `/docs/apis/actions/code-examples` — 20 shiki-highlighted code blocks
rendered inside the `<details>` collapsibles (was 0).
- `/docs/apis/openidoauth/claims` — line-range hashes (`#L9-L11`)
honored.
- `/docs/examples/login/flutter` — mixed languages (xml/dart/html)
detected and highlighted.
- `/docs/guides/integrate/external-audit-log` — edge case of fenced
reference indented inside a numbered list also converted and rendered.
Greps:
- `^[ \t]*\`\`\`[a-zA-Z0-9]+ reference` in `apps/docs/content/**/*.mdx`
→ 0 matches.
- `<GithubCodeBlock url="` in `apps/docs/content/**/*.mdx` → 55 matches.
- `from '@/components/github-code-block'` in
`apps/docs/content/**/*.mdx` → 0 matches.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>
## Description
This PR updates the Kubernetes deployment documentation to address user
feedback regarding our routing instructions. A user noted that standard
`Ingress` is becoming outdated and requested configuration examples for
the modern Gateway API.
To support both existing and modern clusters, I have updated the guide
to provide two clear pathways for exposing ZITADEL.
## Changes Included
* **Prerequisites updated:** Mentioned Gateway API controllers alongside
standard Ingress controllers.
* **Refactored Stage 2 (Production):** Split the routing configuration
into "Option A: Standard Ingress" and "Option B: Gateway API".
* **Added YAML example:** Provided a sample `HTTPRoute` resource to
route traffic to the `zitadel` and `zitadel-login` backend services.
* **Terminology updates:** Broadened terms like "Ingress" to "Routing"
or "Routing controller" where applicable.
<!--
Please inform yourself about the contribution guidelines on submitting a
PR here:
https://github.com/zitadel/zitadel/blob/main/CONTRIBUTING.md#submit-a-pull-request-pr.
Take note of how PR/commit titles should be written and replace the
template texts in the sections below. Don't remove any of the sections.
It is important that the commit history clearly shows what is changed
and why.
Important: By submitting a contribution you agree to the terms from our
Licensing Policy as described here:
https://github.com/zitadel/zitadel/blob/main/LICENSING.md#community-contributions.
-->
# Which Problems Are Solved
Outdated depdencies
# How the Problems Are Solved
This PR mostly just updates our NPM depdencies to the newest feature
releases.
The UUID package was update to version 14, the changelog only includes
changes to the supported node version.
# Additional Changes
Replace tsx for some scripts in the docs.
---------
Co-authored-by: Livio Spring <[email protected]>
Co-authored-by: Max Peintner <[email protected]>
## Summary
- Switch the docs catch-all route to full static generation and prebuild
both latest and versioned docs paths.
- Prebuild OG images for all docs pages, make sitemap and LLM export
static, and remove nondeterministic sitemap timestamps.
- Reduce build-time overhead by memoizing docs sidebar trees and
skipping processed markdown generation for versioned docs.
## Testing
- `pnpm nx run @zitadel/docs:build`
- `pnpm nx run @zitadel/docs:lint`
- `pnpm nx run @zitadel/docs:check-types`
- Verified the prerender manifest contains 8,816 prerendered routes,
3,293 versioned docs routes, 4,406 OG routes, and zero revalidating docs
routes.
This PR updates the "Private Key JWT Auth for Service Accounts"
documentation to explicitly clarify the relationship between the exp
(expiration) and iat (issued at) claims.
Previously, the documentation didn't make it clear what happens if a
developer sets an exp claim far into the future. This update clarifies
that while the exp value is strictly enforced, the iat claim takes
precedence if the exp is set to more than 1 hour in the future (i.e.,
ZITADEL will reject the JWT once the iat is older than 1 hour,
regardless of the exp time).
**Changes included:**
Updated the description of the exp claim in the JWT payload section to
highlight the 1-hour iat limit enforcement.
# Which Problems Are Solved
The Vercel `docs` project generated ~64M ISR writes over 30 days (99.5%
of ISR writes across all projects, ~\$258/month).
Root causes in the Next.js 16 docs app:
- `apps/docs/app/[[...slug]]/page.tsx` had `dynamicParams = true` +
`revalidate = 3600`. Bot traffic hitting unknown URLs (`/docs/wp-admin`,
`/docs/.env`, fuzzed paths) got rendered via \`notFound()\`, and the 404
response was cached as an ISR entry — 1 write per unique bad URL. Known
pages were also rewritten hourly for no reason since content only
changes on deploy.
- `apps/docs/app/og/docs/[...slug]/route.tsx` had `revalidate = false` +
empty `generateStaticParams()` + implicit `dynamicParams = true`. Every
unique OG URL (including bot probes) was cached forever — writes
accumulated permanently.
# How the Problems Are Solved
Switch the docs routes to pure SSG (content is static and only changes
on deploy, so ISR provides no value):
- `app/[[...slug]]/page.tsx`: `dynamicParams = false`, `revalidate =
false`, `dynamic = 'force-static'`. Unknown URLs now return a static 404
at the CDN — no function invocation, no ISR write. All 390 pages from
`source.generateParams()` are still pre-rendered.
- `app/og/docs/[...slug]/route.tsx`: `generateStaticParams()` now
returns all 390 pages via the existing `getPageImage(page).segments`
helper, so every OG image is pre-built as a static asset. `dynamicParams
= false` + `dynamic = 'force-static'` locks it down.
- `app/llms-full.txt/route.ts`: added `dynamic = 'force-static'` as a
safety net (already `revalidate = false`, single URL).
The tradeoff is longer CI builds (~40s–2min for 390 OG image
generations, paid on every preview deploy) in exchange for eliminating
~\$258/month in ISR writes plus associated function invocations and CPU
time.
# Additional Changes
None.
# Additional Context
- No changes to `next.config.mjs`, `vercel.json`, or redirects.
- Existing `apps/docs/redirects.json` (3,261 entries) covers legacy URLs
so `dynamicParams = false` won't 404 moved pages linked from elsewhere.
- Versioned routes: `content/versions.json` and `v*/` folders don't
exist yet. When versioning is activated, `generateStaticParams()` in
both files must also include `versionSource.generateParams()` —
otherwise versioned URLs will 404 under `dynamicParams = false`.
## Test plan
- [ ] CI build succeeds (expect modest build-time increase for OG
pre-generation)
- [ ] Inspect `apps/docs/.next/prerender-manifest.json` — all 390 doc
routes + 390 OG routes listed with `initialRevalidateSeconds: false`
- [ ] Local smoke: `/docs` → 200, `/docs/wp-admin` → 404 (static, no
function), `/docs/og/docs/guides/start/image.png` → PNG,
`/docs/og/docs/bogus/image.png` → 404
- [ ] Post-deploy: Vercel **ISR Writes** metric drops to near-zero
within 24h
- [ ] Post-deploy: Vercel **Function Invocations** for `/og/docs/*` drop
to zero
- [ ] Verify no legitimate docs pages 404 (cross-check logs against
`apps/docs/app/sitemap.ts`)
---------
Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>
# Which Problems Are Solved
As part of https://github.com/zitadel/zitadel/issues/11917 we want to
introduce error slugs so (API) clients can rely on stable,
machine-readable errors and act accordingly.
# How the Problems Are Solved
- Added a `NewSlug` helper function in the domain package.
- Added `ErrorDetails` to the `ZitadelError`
- Added an `zitadel.error.v2.ErrorDetail` proto message
- Updated the connectRPC error interceptor to map new slug based errors
to the new `ErrorDetail`
- Defined some common slugs and error functions like internal errors
- Defined (session) specific slugs used in the `DeleteSession` and
`CheckUser` functions and replaced old implementations
- Updated integration tests to check specific errors if the relation
database feature is enabled
- Updated doc and guideline to reflect the latest changes and decisions
- Updated DeleteSession endpoint API to list possible slugs
# Additional Changes
None
# Additional Context
- closes#11957
---------
Co-authored-by: Wim Van Laer <[email protected]>
# Which Problems Are Solved
After merging #11968 and rechecking the dependabot alerts there are
still some issues leftover.
# How the Problems Are Solved
This pr makes overrides for vulnerable transitive depdencies to force
update to safe versions.
It also upgrades the next.js version in the docs and I also ran `pnpm
update` once more.
# Additional Changes
Removed the mochaawesome dependency is this is not really needed and
seems unmaintained.
# Additional Context
- Precursor: #11968
# Which Problems Are Solved
This pr updates major and minor dependencies and is the first step on
getting our dependabot alerts cut down.
# How the Problems Are Solved
Depedency updates across the board eg:
- Upgrade Angular to v21
- Upgrade next.js to v16.2
- Upgrade tailwind to v4 in the login
- Upgrade vitest to v4 in the login
This is an uncompleted list refer to the changed files for a full
overview of all the updates.
# Additional Changes
Migrated all control flow in the console to the modern control flow
syntax.
Fixed the dependsOn setting for the @zitadel/login:test-unit nx target.
# Additional Context
- Closes https://github.com/zitadel/zitadel/issues/11274
---------
Co-authored-by: Max Peintner <[email protected]>
# Which Problems Are Solved
The documentation did not reflect the difference between login v1 and v2
for configuring a JWT-idp
# How the Problems Are Solved
Added a warning in the docs which highlight that difference.
# Additional Changes
- Restructured the docs to reflect a more generic approach.
- Fixed indentation inside the `<Callout type="warning">` block so the
content renders as formatted text instead of a code block.
- Fixed inconsistent acronym casing in the use-case section: "jwt" →
"JWT" and "idp" → "IdP" to match the rest of the page and UI terms.
# Additional Context
- Closes: #11589
<!-- START COPILOT CODING AGENT TIPS -->
---
💡 You can make Copilot smarter by setting up custom instructions,
customizing its development environment and configuring Model Context
Protocol (MCP) servers. Learn more [Copilot coding agent
tips](https://gh.io/copilot-coding-agent-tips) in the docs.
---------
Co-authored-by: Copilot <[email protected]>
Co-authored-by: copilot-swe-agent[bot] <[email protected]>
## Problem statement
- `<Tabs>` were not rendered in docs
- Missing steps in README for local dev
## How it was solved
- Enhance the README to better describe local development setup and
clean up formatting.
- Standardize the use of tabs across various components for consistency.
## Additional info
To not cause merge conflicts with
https://github.com/zitadel/zitadel/pull/11729 changes in
`/self-hosting/manage/configure/configure.mdx` were skipped
# Which Problems Are Solved
System API users currently authenticate using raw RSA public keys
configured via Path or KeyData. This approach doesn't integrate well
with Kubernetes tooling.
# How the Problems Are Solved
Allow for the `path`/`keyData` to be an X.509 certificate.
The `NotBefore` and `NotAfter` fields of the certificate are beeing
respected when validating the JWT.
# Additional Changes
# Additional Context
- Closes#11442
---------
Co-authored-by: Livio Spring <[email protected]>
# Which Problems Are Solved
For switching v4.x releases to a corresponding maintenance branch, we
had to trick semantic release and create a `5.0.0-base` tag on main.
This now breaks the docs build, which tries to fetch all tags and build
a corresponding version.
# How the Problems Are Solved
- Ignore pre-released tags/releases for the moment.
# Additional Changes
None
# Additional Context
- requires backport to v4.x
# Which Problems Are Solved
API Requests in the docs, still had old naming
# How the Problems Are Solved
Updated Authorization Reuqest naming in docs with role assignments
Added a callout to the Kubernetes deployment guide (`Deploy ZITADEL on
Kubernetes`) explicitly stating that PostgreSQL 18 is not currently
supported, ensuring users deploy with a compatible version (14-17).
This PR updates the "Hosted Login UI" documentation to clarify how text
customization works for the new Hosted Login V2.
**Changes:**
1. Adds a warning callout to the "Customization options" section.
2. Clarifies that Login V2 interface texts currently cannot be modified
via the ZITADEL Console UI.
3. Provides the required workaround, directing users to use the Settings
V2 API to patch translation keys using the en.json locale file as a
reference.
---------
Co-authored-by: Copilot Autofix powered by AI <[email protected]>
# Which Problems Are Solved
For existing customers it could be hard to understand the new aligned
terms we have defined, if they are already used to the "old term"
# How the Problems Are Solved
Adding notes at the top of docs pages to state clearliy new and old
terms.
# Which Problems Are Solved
- `@zitadel/docs:generate-proto-docs` could block while `npx` waited for
confirmation to install `@bufbuild/buf`.
- When the docs generation ran through `nx run-many --target generate`,
that interactive prompt was hidden, so the task appeared stuck without
visible output.
# How the Problems Are Solved
- Resolve Buf from the workspace root with `pnpm exec buf generate` so
the repo-pinned CLI is used non-interactively.
- Run the Buf command from the workspace context instead of the
temporary execution directory.
- Keep the existing generation arguments, template handling, and
excluded path handling intact.
# Additional Changes
- Remove the temporary directory setup that was only needed for the
previous `npx`-based invocation.
- Keep the existing `protoc-gen-connect-openapi` installation and PATH
wiring unchanged.
# Additional Context
- Follow-up for the docs generation issue discussed in Discord where
`@zitadel/docs:generate-proto-docs` prompted for `@bufbuild/buf`
installation and appeared blocked under `nx run-many --target generate`.
- Validated with `pnpm nx run @zitadel/docs:generate-proto-docs
--outputStyle=stream`.
- Validated with `pnpm nx run @zitadel/docs:generate
--outputStyle=stream`.
# Which Problems Are Solved
- Apple Sign-In uses a Form Post method to return the authorization
response, which ZITADEL handles at a specific endpoint ending in /form
for the login v1.
- The Console previously displayed the standard callback URL (without
`/form`), causing confusion and configuration errors..
# How the Problems Are Solved
- **Console**: Updated ProviderNextService to accept a suffix string .
- **Console**: Updated ProviderAppleComponent to append the suffix to
the urls.
# Additional Changes
- Updated `docs/docs/guides/integrate/identity-providers/apple.mdx` to
explicitly state that the callback URL end with `/form`
- Updated `docs/docs/guides/integrate/login-ui/external-login.mdx` to
clarify the `/form` suffix requirement for Apple Sign-In in the hosted
login documentation.
# Additional Context
- fixes#11438
---------
Co-authored-by: Ramon <[email protected]>
Co-authored-by: Florian Forster <[email protected]>
## Problem
ZITADEL has inconsistent naming across docs, UI, and API
([#5888](https://github.com/zitadel/zitadel/issues/5888)). We want
contributors and Copilot code-review agents to flag discouraged terms
and suggest canonical replacements automatically.
## Solution
Add a **Markdown terminology catalog** that Copilot agents read
natively.
### What's added
- **`TERMINOLOGY.md`** (repo root) — full ~35-term canonical table from
issue #5888 with:
- Action legend: `keep` / `replace` / `remove` / `internal` / `proposed`
- Scope legend: `UI` / `Docs` / `API` / `Everywhere`
- "Search for (discouraged)" and "Replace with / enforce" columns
- Governance section (how to add new terms, ownership)
- **`.github/instructions/terminology.instructions.md`** — Copilot
`applyTo`-scoped instruction that activates on every PR touching
docs/i18n/proto files and tells the agent:
- Which files map to which scope
- Not to flag identifiers/field names in proto files (only
comments/descriptions)
- To request catalog updates when new terms are introduced
### What's updated
- `.github/copilot-instructions.md` — points to `TERMINOLOGY.md`
- `apps/docs/AGENTS.md` — updated reference, removed dead
`check-terminology` Nx target entry
- `.github/pull_request_template.md` — checklist item updated
- `.github/workflows/ready_for_review.yml` — checklist item updated
### Why Markdown over JSON
| | Markdown | JSON |
|---|---|---|
| Copilot reads natively | yes | no (needs parsing context) |
| Mirrors AGENTS.md table style | yes | no |
| Human-readable without tooling | yes | no |
| Mirrors the #5888 issue format | yes | no |
| Requires schema / parser | no | yes |
### Why root over `.github/`
`.github/` is for GitHub-specific automation files. `TERMINOLOGY.md` is
a project-wide convention document — it belongs alongside
`CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, and `AGENTS.md` at the repo
root.
## How it works in practice
When a PR touches `apps/docs/content/**`, `console/src/assets/i18n/**`,
`apps/login/locales/**`, or `proto/**/*.proto`, Copilot code review
automatically loads `.github/instructions/terminology.instructions.md`
and cross-references `TERMINOLOGY.md` to flag discouraged terms.
Human reviewers see the terminology checklist in the auto-comment on PR
open.
## Checklist
- [x] `TERMINOLOGY.md` at repo root with all ~35 terms from #5888
- [x] Plain text action/scope values (no emojis)
- [x] Copilot instruction file scoped to correct file patterns
- [x] All stale `terminology-rules.json` references removed
- [x] No linter/CI step added (guidelines-only approach)
Relates to: #5888
---------
Co-authored-by: Copilot <[email protected]>
Co-authored-by: Fabienne Bühler <[email protected]>
# Which Problems Are Solved
The distinction between Example Applications and SDKs has not been
clear. In the SDKs section a lot of Example applications where listed.
Also In the SDKs it was not really clear what the SDKs actually are.
Also some examples and skds are outdated and not well maintained
anymore.
# How the Problems Are Solved
- Moved all example app guides to the Example Applications Section
- Restructured SDKs Nav --> SDKs & Integrations: Frontend & Mobile,
Backend & API, Management API Clients
- Removed unnecessary / outdated guides
- Remove ids in framework.json for frameworks which shouldn't be
rendered in console
## Todos:
- Update SDKs Introduction page
- Add links to common oidc libs for most used frameworks
---------
Co-authored-by: Mridang Agarwalla <[email protected]>
<!--
Please inform yourself about the contribution guidelines on submitting a
PR here:
https://github.com/zitadel/zitadel/blob/main/CONTRIBUTING.md#submit-a-pull-request-pr.
Take note of how PR/commit titles should be written and replace the
template texts in the sections below. Do not remove any of the sections.
-->
# Which Problems Are Solved
The `/apis/introduction` page did not give developers clear guidance on
which API version to use. v1 and v2 were presented as equal choices, the
v2 resource list was incomplete, the API path prefix block was
misleading, and several links used inconsistent relative paths.
- No clear recommendation to use v2 for new integrations
- v1 APIs not labelled as legacy
- "APIs v2" section only listed 3 of 15 available v2 services
- Path prefix block only listed 5 of 15 v2 gRPC service paths, with no
distinction between REST and gRPC/Connect access patterns
- `/ui/` path listed as a single entry — the Management Console
(`/ui/console/`) and hosted Login UI (`/ui/login/`) were not
distinguished
- Relative links (`../guides/...`, `./assets/assets`) inconsistent with
the rest of the page
- Auth disclaimer paragraph was confusing; "Custom" section heading was
unclear
# How the Problems Are Solved
- **v2-first framing**: Added a clear directive — "Use the v2 APIs for
all new integrations" — and renamed the old section to "Legacy v1 APIs"
- **Complete v2 resource list**: All 15 v2 services now listed with
one-line descriptions (User, Session, Org, Instance, Project,
Application, IDP, Group, Settings, Feature, Authorization, Action,
WebKey, OIDC, SAML)
- **Full path prefix list**: All 15 v2 gRPC service paths listed; split
into `# REST (HTTP/JSON transcoding): /v2/` and `# gRPC + Connect
protocol (binary or JSON via connectRPC):`
- **`/ui/` paths clarified**: Split into `/ui/console/` (Management
Console) and `/ui/login/` (Hosted Login UI) with inline comments
- **Fixed relative links**: `../guides/...` → `/guides/...`;
`./assets/assets` → `/apis/assets/assets`
- **Section copy improvements**: Auth disclaimer removed; "Custom"
renamed to "Session-based and custom login" with clear bullet list; v1
API card descriptions updated with v2 pointers; Assets card, System card
title fix
- **Client libraries section**: Replaced noisy "API definitions" section
with cleaner "Client libraries & schemas"
# Additional Context
All changes are in `apps/docs/content/apis/introduction.mdx`,
`apps/docs/content/apis/v2.mdx`, and
`apps/docs/content/apis/migration_v1_to_v2.mdx`.
Co-authored-by: Copilot <[email protected]>
## What
Shorten the `title` frontmatter on 20 docs pages so that the rendered
`<title>` tag stays within the 70-character SEO limit.
The root layout appends ` | ZITADEL Docs` (15 chars) to every page
title, meaning the raw frontmatter `title` must be ≤ 55 characters. A
site scan flagged all 20 pages for the "Title too long" warning (titles
ranged from 71 to 92 characters in the final rendered tag).
## Why
Search engines may truncate or ignore `<title>` tags longer than 70
characters, hurting click-through rates and keyword relevance in search
results.
## How
Each title was rewritten to:
- Fit within 55 characters (leaving room for ` | ZITADEL Docs`)
- Front-load the primary search keyword (product name, protocol, or
feature)
- Include "ZITADEL" where users realistically search for `{feature}
ZITADEL`
- Avoid generic filler words ("Configure", "Set up", "Support for")
All 20 files already have a `sidebar_label` field that preserves the
original descriptive title for sidebar navigation — no navigation
changes result from this PR.
## Pages updated
| Page | Before (chars) | After (chars) |
|---|---|---|
| concepts/features/passkeys | 82 | 64 |
| guides/integrate/identity-providers/openldap | 72 | 58 |
| guides/solution-scenarios/b2b | 78 | 59 |
| guides/integrate/services/cloudflare-oidc | 86 | 54 |
| guides/integrate/login/hosted-login | 71 | 55 |
| guides/integrate/service-accounts/private-key-jwt | 76 | 56 |
| guides/integrate/service-accounts/client-credentials | 78 | 60 |
| guides/integrate/services/google-cloud | 92 | 57 |
| guides/solution-scenarios/saas | 88 | 65 |
| guides/migrate/sources/auth0 | 73 | 65 |
| guides/integrate/login-ui/oidc-standard | 81 | 55 |
| guides/integrate/login-ui/username-password | 73 | 59 |
| guides/integrate/login-ui/device-auth | 78 | 60 |
| guides/integrate/identity-providers/linkedin_oauth | 72 | 58 |
| guides/integrate/identity-providers/pingfederate-saml | 74 | 61 |
| guides/integrate/service-accounts/personal-access-token | 82 | 62 |
| legal/service-description/cloud-service-description | 76 | 61 |
| guides/integrate/login/login-users | 83 | 55 |
| guides/integrate/identity-providers/migrate | 74 | 65 |
| guides/manage/console/projects-overview | 71 | 62 |
All final `<title>` values are between 54 and 66 characters (well under
the 70-char limit).
# Which Problems Are Solved
Renaming of:
- Resource Owner
- OrgID
- OrganizationID
- Organization Id
# How the Problems Are Solved
Find & Replace, evalue entries, is resource owner referring to an
organization ? If so, do change
# Additional Context
- Closes#11305
Users deploying ZITADEL against a managed PostgreSQL service (RDS, Cloud
SQL, Azure Database, etc.) often do not have superuser access and cannot
provide `Admin.*` credentials. The documented workaround — provisioning
the user and database manually and then running `start-from-setup` —
silently skips schema bootstrapping, causing `relation
"eventstore.events" does not exist` errors with no clear recovery path.
The root cause is that `zitadel init` conflates two steps that require
different privileges without exposing them separately:
- **Provisioning step** (`CREATE ROLE`, `CREATE DATABASE`, `GRANT`) —
requires superuser.
- **Schema bootstrapping step** (create
`eventstore`/`projections`/`system` schemas and base tables) — requires
only DB owner.
Users who handle the provisioning step externally have no supported way
to run schema bootstrapping alone.
## Changes
- **`cmd/initialise/verify_schema.go`** (renamed from
`verify_zitadel.go`): Rename `newZitadel()` → `newSchema()` (internal);
rename the `init zitadel` sub-command to `zitadel init schema`
(backwards-compatible alias kept) with a clear description that it
bootstraps the ZITADEL database schema without admin/superuser
privileges. Fix stale error log message to reference `init schema`.
- **`cmd/initialise/verify_schema_test.go`** (renamed from
`verify_zitadel_test.go`): Test file renamed to match source file.
- **`cmd/initialise/init.go`**: Update call site to `newSchema()`. Add
guidance in the `init` command's Long description about using `zitadel
init schema` for users without admin credentials.
- **`cmd/initialise/verify_database.go`**: Add a `pg_database` catalog
pre-check before attempting `CREATE DATABASE`, so `zitadel init` with
`ADMIN=service_user` no longer fails with `permission denied to create
database` when the database was already provisioned externally.
- **`cmd/initialise/verify_database_test.go`**: Add test cases covering
the new catalog-check skip path, the existing error-skip path, and the
error-propagation path when the `pg_database` query itself fails.
- **`apps/docs/content/self-hosting/manage/database/index.mdx`**: Inline
the `_postgres.mdx` partial (now only PostgreSQL is supported), add a
top-level callout, and add a **Managed PostgreSQL / No Admin Access**
section with explicit 3-step instructions and security guidance (strong
passwords, SSL, TLS). Additional improvements: add inline `# Use
'require' or 'verify-full' for production` comments on `Mode: disable`
lines in the YAML example; add clarifying comment to the redundant
`GRANT` in the SQL snippet; replace admonition syntax with proper
Fumadocs `<Callout>` components; add full database connection env vars
to the `start-from-setup` example.
- **`apps/docs/content/self-hosting/manage/updating_scaling.mdx`**:
Rewrite the init phase description to clearly distinguish the
provisioning and schema bootstrapping steps, and document `zitadel init
schema` as the path for manual provisioning. Replace admonition syntax
with proper Fumadocs `<Callout>` components.
- **`apps/docs/content/self-hosting/manage/database/_postgres.mdx`**:
Deleted (content merged into `index.mdx`).
## Problem
This relates to https://github.com/zitadel/zitadel/discussions/9363
I think we can improve our UX in cases where a user wants to use an
external DB and/or does not want to share too broad permissions with
zitadel
## Related problems
* https://github.com/zitadel/zitadel/issues/10432
* https://github.com/zitadel/zitadel/discussions/8583
* https://github.com/zitadel/zitadel/issues/7903
* https://github.com/zitadel/zitadel/issues/9718
* https://github.com/zitadel/zitadel/issues/8012
* https://github.com/zitadel/zitadel/issues/8558
## Related PRs
https://github.com/zitadel/zitadel/pull/11021
# Which Problems Are Solved
Not all frameworks were listed in the Management Console when creating
an application.
# How the Problems Are Solved
Aligned the list from the docs and console.
# Additional Changes
None
# Additional Context
requires backport to v4.x
This PR forces the user to enter a reason/explanation before submitting
a negative feedback. Negative feedback without an explanation is not
actionable.
# Which Problems Are Solved
This PR fixes a couple of minor issues in the docs:
- Duplicated sentences
- Obsolete names
- Wrong header hierarchy
# How the Problems Are Solved
Solved by rewriting/fixing the mdx files.
# Additional Changes
none
# Additional Context
none
Replaces the single-file `docker-compose.yaml` quickstart with a
production-aware, Traefik-based compose pack in `deploy/compose/`. The
pack covers the full arc from a 2-minute localhost quickstart to a
hardened homelab or semi-production deployment.
### What's in the pack
**Stack**: Traefik (proxy) → ZITADEL API (Go `:8080`) + ZITADEL Login
(Next.js `:3000`) → PostgreSQL
All HTTP/gRPC routing is handled by Traefik via Docker labels — no
manual proxy config needed. The Login V2 UI is enabled by default. Login
URLs are derived automatically from `ZITADEL_DOMAIN`,
`ZITADEL_EXTERNALPORT`, and `ZITADEL_PUBLIC_SCHEME` — no separate URL
variables needed.
**Compose files**
| File | Purpose |
|------|---------|
| `docker-compose.yml` | Base stack — works standalone. Uses explicit
`name: zitadel` network for reliable Traefik service discovery. |
| `docker-compose.mode-letsencrypt.yml` | TLS overlay: ACME HTTP
challenge |
| `docker-compose.mode-external-tls.yml` | TLS overlay: upstream LB/CDN
terminates TLS. Uses `forwardedHeaders.trustedIPs` (configurable via
`TRAEFIK_TRUSTED_IPS`) instead of `insecure=true`. |
| `docker-compose.mode-local-tls.yml` | TLS overlay: self-signed certs
for LAN |
| `docker-compose.prodlike.yml` | Splits init / setup / start for
controlled upgrades |
| `docker-compose.test.yml` | CI overlay: swaps images to locally-built
`:local` tags |
**Optional profiles**: `cache` (Redis), `observability` (OpenTelemetry
Collector)
### Build infra
- New `@zitadel/api:pack` and `@zitadel/login:pack` Nx targets build
local Docker images (`zitadel/zitadel:local`,
`zitadel/zitadel-login:local`) for use in CI and local testing
- `apps/api/Dockerfile` now accepts a `BINARY` build arg so local and
release builds share the same image
### Testing
- New `@zitadel/compose` Nx project with targets: `test-config`
(validates all overlay combinations using `--quiet`), `test-run` (starts
full stack with local images), `test-e2e` (Playwright wiring + protocol
matrix tests through Traefik), `test-full` (end-to-end: build → start →
test → teardown), `stop`
- **`@zitadel/compose` is explicitly excluded from `nx affected` in CI
for now** — the full stack smoke test requires a Docker daemon and
significant resources. The intent is to add a dedicated
`compose_smoke_test` CI job in a follow-up. The targets can be run
locally with `pnpm nx run @zitadel/compose:test-full`.
### Documentation
- **`compose.mdx`**: Complete rewrite with a staged structure (Stage 1
Quickstart → Stage 2 Homelab → Stage 3 Beyond Compose). Documents TLS
modes, profiles, secrets hardening, ExternalDomain/Port/Secure
invariant, upgrades, and the path to Kubernetes
- **New `requirements.mdx`**: Lists supported PostgreSQL versions
(14–18), Redis (standalone), Docker Compose v2.x, and reverse proxy h2c
requirements
- **`reverse_proxy.mdx`**: Added intro covering h2c requirements, TLS
modes table, and Login UI routing split
- **`troubleshooting.mdx`**: New sections for container restarts on
upgrade, FIRSTINSTANCE env vars not taking effect, and diagnosing
unhealthy containers
- **`caddy/index.mdx`**: Known issue and workaround for the `TE:
trailers` header hang
- Removed the old
`apps/docs/content/self-hosting/deploy/docker-compose.yaml` embedded in
the docs
### Breaking change
The old `apps/docs/content/self-hosting/deploy/docker-compose.yaml` file
is deleted. The getting-started docs page
(`/self-hosting/deploy/compose`) now points to the new pack via a `curl
| tar` download command.
---
### Checklist
- [x] `deploy/compose/` smoke test passes end-to-end locally (`pnpm nx
run @zitadel/compose:test-full`)
- [x] Docs build passes (`pnpm nx run @zitadel/docs:build`)
- [ ] Follow-up issue created to add `compose_smoke_test` CI job
---------
Co-authored-by: Mridang Agarwalla <[email protected]>
Federico CoppedeandGitHub
Livio SpringandGitHub
SilvanandGitHub
Mridang AgarwallaandGitHub
Fabienne BühlerandGitHub
Vitor Bari BucciantiandGitHub
Marco A.andGitHub
Livio SpringandGitHub