# 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]>
# Which Problems Are Solved
The login v2 container has no way to verify upstream Zitadel API
connectivity before accepting traffic. The existing `/healthy` endpoint
always returns 200 regardless of whether the backend is reachable. This
means Kubernetes routes user traffic to pods that cannot actually serve
login requests, causing silent failures where the root layout swallows
gRPC errors and renders pages with default settings.
# How the Problems Are Solved
A new `/ui/v2/login/ready` endpoint creates a gRPC client using the same
auth and transport path as real requests, calls
`SettingsService.getGeneralSettings()`, and returns `200 OK` on success
or `503 Service unavailable` on failure. This verifies both network
connectivity and authentication credentials to the upstream Zitadel API.
Kubernetes supports readiness probes natively, so this endpoint can be
configured as a readiness probe to gate traffic until the login
container can connect to Zitadel. Docker Compose does not have a
readiness probe concept, so the compose healthcheck and
`healthcheck.mjs` default remain unchanged and continue using
`/healthy`.
The Docker HEALTHCHECK in the Dockerfile has been updated to use
`/ready` so that the image-level health status reflects actual upstream
connectivity. This will also allow us to simplify the Helm chart by
dropping the `wait4x` init containers that currently poll the Zitadel
API before starting the login pod, since the readiness probe makes them
redundant.
# Additional Changes
The `/ready` endpoint has been added to the OTEL HTTP instrumentation
ignore list to avoid noisy probe traces. Unit tests, a wiring spec
integration test, and an OTEL span filtering test have been added for
the new endpoint. The `# TODO: Check healthy, not ready` comment has
been removed from the Dockerfile. The `/healthy` endpoint is kept as-is
for liveness probes.
# Additional Context
The Helm chart changes to use `/ready` for readiness and startup probes
and to remove the `wait-for-zitadel` init container will be done in a
follow-up PR in the `zitadel-charts` repository.
## 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]>
# Which Problems Are Solved
Invalid formatting in the login codebase due to invalid prettier
configuration
# How the Problems Are Solved
Fxed .prettierignore wildcards for login source files
# Additional Changes
Removed .prettierrc file because there is already a prettier.config.mjs
file
# Additional Context
Closes#11096
# Which Problems Are Solved
This pull request resolves a 404 error that occurred at the end of the
LDAP login flow.
Previously, when a user submitted their LDAP credentials in the
apps/login application, the form initiated the session creation process
but incorrectly redirected the user to /idp/ldap/success, a route that
does not exist. In addition, the redirect failed to preserve necessary
IDP context parameters (such as requestId, organization, and linking
fingerprint info) that are required to fully complete the authentication
intent.
# How the Problems Are Solved
- Fixed redirect path: Updated `createNewSessionForLDAP` to redirect to
`/idp/ldap/process` instead of success, aligning it with the standard
IDP intent processing pipeline which dynamically resolves
`[provider]/process`.
- Preserved context parameters: Extracted `requestId`, `organization`,
`postErrorRedirectUrl`, `linkToSessionId`, and `linkFingerprint` from
the URL parameters on the LDAP page and passed them through
LDAPUsernamePasswordForm down to the server action so the ongoing auth
request is successfully tied to the user's intent.
Closes#11138
# Which Problems Are Solved
Previously, the application strictly checked the allowRegister
setting—which typically applies to local account creation—before
considering if a user without an account should be redirected to an IDP,
or whether they could access the register page. This blocked users from
registering via identity providers when local registration was disabled
but IDPs were configured.
# How the Problems Are Solved
- Removed the allowRegister dependency when deciding to redirect an
unknown user to an IDP. The logic now only checks
!allowLocalAuthentication, correctly opening up the IDP registration
flow even when local auth/registration is not allowed.
- Modified the block condition so the register page is only restricted
if allowRegister is false and there are no configured identityProviders
available.
<!--
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]>
# Which Problems Are Solved
* v2 login ui was ignoring oicd `ui_locales` making it impossible to
sync the login ui locale with the apps ui
# How the Problems Are Solved
- Read `uiLocales` from `authRequest`
- check all listed if valid in ui
- take the first valid one
- set language cookie (if a valid locale is pressent in uiLocales)
# Additional Changes
- tests
# Additional Context
---------
Co-authored-by: Florian Forster <[email protected]>
Co-authored-by: Max Peintner <[email protected]>
# Which Problems Are Solved
The login unit tests broke due to a recent merge.
# How the Problems Are Solved
This PR fixes the broken tests.
# Additional Changes
None
# Additional Context
- requires backport to v4.x
## 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
This PR introduces several HTML attributes to the username/ID input
field to **prevent unwanted automatic capitalization and correction** on
mobile devices (iOS and Android).
Specifically, this addresses the common issue where a mobile keyboard
defaults to an uppercase letter for the first character, even when the
input (like a username or email) should be lowercase.
# How the Problems Are Solved
The following attributes have been added to the `<input>` field:
| Attribute | Value | Purpose |
| :--- | :--- | :--- |
| `autoCapitalize` | `none` | **Crucial fix:** Prevents the virtual
keyboard from capitalizing the first letter. |
| `autoCorrect` | `off` | Prevents the operating system from
auto-correcting input (e.g., changing "teh" to "the"). |
| `spellCheck` | `false` | Disables the red squiggly lines for
spell-checking. |
# Additional Changes
None.
Previously:
~Introduces a default `Content-Type` request header in the `.env` file
to increase compatibility for developing `zitadel-login` and call a
non-local Zitadel API. The `Host` header is also added as a
commented-out reference so developers will be reminded to set this one
too. This is needed for supporting calls to a Zitadel deployed behind an
AWS ALB, for example.~
https://github.com/zitadel/zitadel-charts/pull/460
# Additional Context
This attribute was already present:
| Attribute | Value | Purpose |
| :--- | :--- | :--- |
| `autoComplete` | `username` | Provides a semantic hint to password
managers to correctly suggest and fill stored usernames. |
## Rationale and References (MDN Web Docs)
| Attribute | Why we use it | Reference Link |
| :--- | :--- | :--- |
| **`autoCapitalize="none"`** | Overrides default OS sentence
capitalization behavior. | [MDN:
autocapitalize](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/autocapitalize)
|
| **`autoCorrect="off"`** | Essential for case-sensitive or specific
identifiers where correction must be disabled (primarily iOS). | [MDN:
autocorrect](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/autocorrect)
|
| **`spellCheck="false"`** | Usernames are not dictionary words, so
spell-checking is distracting/irrelevant. | [MDN:
spellcheck](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/spellcheck)
|
| **`autoComplete="username"`** | Modern standard for indicating a login
field, supporting password managers. | [MDN:
autocomplete](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/autocomplete)
|
## Browser Safety Concern
This change is **safe**. These attributes act as "hints" to the browser
and OS. If a particular older browser does not support one of the
attributes, it will simply ignore it and revert to its default behavior,
introducing **no errors** or breaking changes. The combination used is
considered best practice for secure and predictable input fields.
- Discussion #11124
---------
Co-authored-by: Copilot <[email protected]>
Co-authored-by: Ramon <[email protected]>
# 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
# Which Problems Are Solved
1. `nx run @zitadel/api:test-unit` panics in
`TestCommandSide_ChangeUserHuman` due to two test cases (added in
0261536) missing the required `loginPaths` field. Since the field type
is `func(*testing.T) LoginPaths`, its zero value is `nil`, and calling
it causes a SIGSEGV.
2. Three targets in `apps/api/project.json` (`test-unit`, `build`,
`build-linux`) were silently non-cacheable because NX does not merge
`cache: true` from `targetDefaults` when a project-level target
overrides other properties like `dependsOn` or `inputs`.
3. `TestServer_AuthorizeOrDenyDeviceAuthorization` integration test is
flaky — it uses hardcoded `5*time.Second` timeouts for `EventuallyWithT`
polling, while the rest of the file uses
`WaitForAndTickWithMaxDuration(ctx, time.Minute)`. Under CI load, 5
seconds is insufficient and the empty ID cascades into a validation
error.
# How the Problems Are Solved
**Test panic fix:**
- Added missing `loginPaths: expectLoginPathsNoCall` to both broken test
cases ("change human email verified (self-management), not allowed" and
"change human phone verified (self-management), not allowed").
**NX cache fix:**
- Added explicit `"cache": true` to `test-unit`, `build`, and
`build-linux` targets in `apps/api/project.json`.
- Verified with `pnpm nx show project @zitadel/api --json` that all
three targets now resolve with `cache: true`.
**Integration test flakiness fix:**
- Replaced all 6 hardcoded `assert.EventuallyWithT(t, ...,
5*time.Second, 100*time.Millisecond)` calls in
`TestServer_AuthorizeOrDenyDeviceAuthorization` with
`require.EventuallyWithT(t, ..., retryDuration, tick)` using
`integration.WaitForAndTickWithMaxDuration(CTXLoginClient,
time.Minute)`.
- Changed from `assert` (non-fatal) to `require` (fatal) so timeout
failures stop the test immediately instead of cascading with empty IDs.
# Additional Context
- The broken unit test landed on main because CI skips `lint_test_build`
on pushes to main (`if: github.ref != 'refs/heads/main'`). A follow-up
issue was created: #11696.
- The integration test flakiness was missed by the previous fix in
#10752.
---------
Co-authored-by: Copilot <[email protected]>
Co-authored-by: Livio Spring <[email protected]>
# Which Problems Are Solved
- Currently, if a user has only secondary authentication methods (like
TOTP) configured but no primary authentication method (Password,
Passkey, or IDP), the login flow fails to handle them correctly,
resulting in an unhelpful "user not found" error when they attempt to
log in.
- These users are not correctly prompted to set up a primary
authentication factor, leaving them in a state where they cannot
successfully authenticate.
# How the Problems Are Solved
- Updated `sendLoginname` to evaluate if a user has an active primary
authentication method (`AuthenticationMethodType.PASSWORD`, `PASSKEY`,
or `IDP`. If they lack a primary method, the flow now correctly
redirects them into the verification/invite process rather than falling
through the method checks and returning a generic error.
- Updated `sendVerification` to replace the empty `authMethodTypes`
array check with a specific check for primary authentication methods.
Now, after completing email/invite verification, users who do not have a
primary authentication method are explicitly redirected to
`/authenticator/set` to set one up.
# Which Problems Are Solved
The login container can only serve HTTP. In deployments where a reverse
proxy is not used, operators need the login container to terminate TLS
itself.
Closes#11473
# How the Problems Are Solved
The container now supports optional HTTPS via three environment
variables that match the pattern already used by the backend server:
`ZITADEL_TLS_ENABLED`, `ZITADEL_TLS_CERTPATH`, and
`ZITADEL_TLS_KEYPATH`. When `ZITADEL_TLS_ENABLED` is not set or set to
`false`, behavior is identical to before. When set to `true`, the server
reads the provided certificate and key files and serves HTTPS using the
lower-level `getRequestHandlers` API from Next.js.
The Docker healthcheck was updated to probe the correct scheme
automatically based on the same environment variable.
# Additional Changes
Added a dockerized integration test that verifies both HTTP and HTTPS
modes using testcontainers.
# Additional Context
The TLS path uses `getRequestHandlers` from
`next/dist/server/lib/start-server` instead of `startServer` because the
latter rejects self-signed certificates in production mode. This is the
same internal API that `startServer` itself calls.
---------
Co-authored-by: Copilot <[email protected]>
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]>
Closes#11199
# Which Problems Are Solved
This PR refactors the login app to load allowed languages and the
default language directly from the Zitadel API equivalents
(`getGeneralSettings`), rather than relying on a hardcoded list. This
ensures that the available languages in the UI and the locale selection
logic match the instance's configuration.
# How the Problems Are Solved
- Fetches allowed languages server-side and passes them to the
LanguageSwitcher
- The NEXT_LOCALE cookie and Accept-Language headers are now strictly
validated against the API-provided allowed languages.
- Fallback: If a cookie requests an unsupported language, the system now
falls back to the API's defaultLanguage (instead of valid but
unconfigured defaults).
# Additional Changes
Helper: Added `getLanguage(code)` to map API language codes to display
names (utilizing Intl.DisplayNames if the code isn't in our static
mapping).
---------
Co-authored-by: Livio Spring <[email protected]>
# Which Problems Are Solved
This PR introduces robust redirect configuration options and enhances
security for Server Actions in multi-domain setups.
# How the Problems Are Solved
- Redirect Fallback Logic: Implemented a unified `resolveRedirectUri`
utility that prioritizes redirect targets as follows:
- Environment override (`DEFAULT_REDIRECT_URI`)
- Organization settings (`defaultRedirectUri`).
- Relative fallback (`/signedin?...`).
- Host Reflection: `DEFAULT_REDIRECT_URI` supports absolute URLs or
relative paths via host reflection.
- Server Action Security: Configured `serverActions.allowedOrigins` to
be dynamically manageable via the `SERVER_ACTION_ALLOWED_ORIGINS`
environment variable (comma-separated list). It defaults to an empty
list for maximum security.
- UI Integration: Updated the /signedin page to use the unified redirect
logic, ensuring consistent behavior for the "Continue" button.
- Documentation: Added type definitions and detailed descriptions for
new environment variables in
`next-env-vars.d.ts`
---------
Co-authored-by: Copilot <[email protected]>
# Which Problems Are Solved
We do have a production checklist for self-hosters which lacks some
important things for our cloud customers.
# How the Problems Are Solved
Adding a production checklist specifically for cloud users
---------
Co-authored-by: Copilot <[email protected]>
Co-authored-by: Florian Forster <[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. 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
- On self-hosted ZITADEL, the CSP `img-src` directive was baked in at
build time from `ZITADEL_API_URL`, blocking branding logos when the
runtime domain differs from the build environment
- CSP construction was duplicated across three files with no single
source of truth
# How the Problems Are Solved
- Introduced a centralized `buildCSP()` function in `src/lib/csp.ts`
that constructs the full CSP string from runtime inputs (`serviceUrl`
for img-src, `iframeOrigins` for frame-ancestors)
- Middleware and flow-initiation now call `buildCSP()` instead of
concatenating strings against a static `DEFAULT_CSP`
- `constants/csp.js` is simplified to a static fallback used only by
`next.config.mjs`
# Additional Changes
- Removed no-op `securitySettings.embeddedIframe.allowedOrigins;`
statements in flow-initiation
- Removed duplicate `X-Frame-Options: SAMEORIGIN` header from
`next.config.mjs` (conflicted with `X-Frame-Options: deny`)
- Added `X-Frame-Options: deny` explicitly on proxy route responses in
middleware (previously relied on next.config.mjs static header surviving
the rewrite)
# Additional Context
- Closes#11088
- Closes#11602
# Which Problems Are Solved
Some graphics used in the docs are using the wrong naming for specific
terms
# How the Problems Are Solved
Replaced graphics with updated terms:
- Role Assignment instead of User Grant, Authorization
- Project Grant instead of Organization Grant
Co-authored-by: Livio Spring <[email protected]>
# Which Problems Are Solved
Update outdated screenshots in the docs.
# How the Problems Are Solved
By replacing the outdated ones with current screenshots
# Additional Changes
Replace the usage of "authorization" with "role assignments" in docs
where it was previously missed.
# Additional Context
- Follow-up for PR https://github.com/zitadel/zitadel/pull/11588
- there are some more docs to be updated, which will be done in a
following PR
---------
Co-authored-by: Copilot <[email protected]>
# Which Problems Are Solved
- Docs code blocks that display imported files (YAML configs, Go
examples) render as unstyled plain text with no syntax highlighting,
unlike fenced code blocks which go through `rehypeCode`/Shiki
# How the Problems Are Solved
- Deleted `components/docusaurus/code-block.tsx` entirely — no custom
wrapper is needed anymore
- Replaced all usages with `DynamicCodeBlock` from
`fumadocs-ui/components/dynamic-codeblock` directly in MDX files; it
handles SSR pre-rendering through the same Shiki pipeline as all other
code blocks
- Raw file content (YAML, Go) is imported as strings via webpack's
existing `asset/source` rule already configured in `next.config.mjs` —
no new infrastructure required
- In `_proxy_guide_tls_mode.mdx`, the `Commands` JSX component was
refactored from concatenated JSX array children to a single template
literal string, which is what `DynamicCodeBlock` (and any string-based
highlighter) requires
- All changes applied to both non-versioned docs and versioned snapshots
(v4.10, v4.11)
# Additional Changes
None.
# Additional Context
- Affected MDX files: YAML config files under
`self-hosting/manage/configure/`, reverse-proxy guides,
`self-hosting/deploy/compose.mdx`, and the actions
`testing-request-signature.mdx` guide
<!-- START COPILOT ORIGINAL PROMPT -->
<details>
<summary>Original prompt</summary>
>
> ----
>
> *This section details on the original issue you should resolve*
>
> <issue_title>code block style is weird</issue_title>
> <issue_description>### Preflight Checklist
>
> - [x] I could not find a solution in the existing issues, docs, nor
discussions
> - [x] I have joined the [ZITADEL chat](https://zitadel.com/chat)
>
> ### Describe the docs your are missing or that are wrong
>
> This hurts my eyes:
>
> <img width="867" height="525" alt="Image"
src="https://github.com/user-attachments/assets/b7b66d92-56e1-4e0a-8dba-3cab448930fe"
/>
>
> ### Additional Context
>
> _No response_</issue_description>
>
> <agent_instructions>the user reported a weirdly styled code block in
the docs page where we used to display yaml files. Investigate the docs
and fix the styling</agent_instructions>
>
> ## Comments on the Issue (you are @copilot in this section)
>
> <comments>
> <comment_new><author>@fforootd</author><body>
> haha, ok that is certainly weird, let me look at
that.</body></comment_new>
> </comments>
>
</details>
<!-- START COPILOT CODING AGENT SUFFIX -->
- Fixeszitadel/zitadel#11645
<!-- START COPILOT CODING AGENT TIPS -->
---------
Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: fforootd <[email protected]>
Co-authored-by: Florian Forster <[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. 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 first input field on login screens is not automatically focused,
requiring users to manually click before typing. This creates
unnecessary friction during the login flow, particularly for
keyboard-oriented users and accessibility scenarios.
# How the Problems Are Solved
- Added the `autoFocus` prop to the first `TextInput` in all 12 login
form components.
- For forms with conditionally rendered first inputs
(`set-password-form` and `register-form-idp-incomplete`), `autoFocus` is
set dynamically so the correct field receives focus depending on which
input is visible.
# Additional Changes
None
# Additional Context
- Closes#11565
Co-authored-by: Max Peintner <[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. 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
As part of the consistent naming effort, this PR focuses on Resource
ID's.
# How the Problems Are Solved
Renamed generic Resource ID to matching Object + ID such as
- Organization ID
- User ID
- Application ID
- Identity Provider ID
- Instance ID
- Project ID
# Additional Changes
None
# Additional Context
- Closes#11306
---------
Co-authored-by: Livio Spring <[email protected]>
# Which Problems Are Solved
As part of the consistent naming effort, this PR focuses on
"Organization domain".
# How the Problems Are Solved
- All terms referring referring to Organization Domains where changed to
be Organization Domain
# Additional Changes
None
# Additional Context
- closes [#11283](https://github.com/zitadel/zitadel/issues/11283)
---------
Co-authored-by: Copilot <[email protected]>
Fabienne BühlerandGitHub
Florian ForsterandGitHub
Vitor Bari BucciantiandGitHub
Mridang AgarwallaandGitHub
Max PeintnerandGitHub
Livio SpringandGitHub
Max PeintnerandGitHub
Marco A.andGitHub
Federico CoppedeandGitHub
dependabot[bot]andGitHub
Liam NevilleandGitHub
