# 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
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`.
This pull request makes a small change to the environment variables used
when spawning a child process in the `generate-proto-docs.mjs` script.
The hardcoded `BUF_TOKEN` environment variable has been removed, and now
only the existing environment variables from `process.env` are passed to
the child process.
- Removed the hardcoded `BUF_TOKEN` from the environment variables when
spawning the child process in `generate-proto-docs.mjs`.
This pull request introduces several improvements and security
enhancements to the documentation build scripts in
`apps/docs/scripts/fetch-remote-content.mjs`, as well as updates to the
test configuration in `apps/docs/package.json` and
`apps/docs/project.json`. The main focus is on enabling local
development workflows, improving safety when handling refs and file
paths, and making the codebase more robust against injection and
traversal attacks.
**Security and validation improvements:**
* Added `safeLog` and `isValidRef` helper functions to sanitize logs and
validate refs, preventing log and command injection vulnerabilities.
* Updated logic for reading local files and external content to ensure
paths are securely resolved and checked, preventing directory traversal
and unauthorized file access.
**Local development and workflow enhancements:**
* Refactored content fetching logic to support copying local content and
public assets when the source ref matches the local branch, enabling
easier local testing and development.
[[1]](diffhunk://#diff-0d1ade7f3d86ad72c66b573c31b0bc34d318dbf964198164719822d300d397d1L70-R202)
[[2]](diffhunk://#diff-0d1ade7f3d86ad72c66b573c31b0bc34d318dbf964198164719822d300d397d1R230-L145)
[[3]](diffhunk://#diff-0d1ade7f3d86ad72c66b573c31b0bc34d318dbf964198164719822d300d397d1L155-R250)
* Improved handling of external files (like `defaults.yaml` and
`setup/steps.yaml`) in local and remote workflows, including secure
copying and conditional downloading.
[[1]](diffhunk://#diff-0d1ade7f3d86ad72c66b573c31b0bc34d318dbf964198164719822d300d397d1L70-R202)
[[2]](diffhunk://#diff-0d1ade7f3d86ad72c66b573c31b0bc34d318dbf964198164719822d300d397d1R266-R364)
* Enhanced relative import fixing logic to robustly rewrite paths and
ensure external files are downloaded or copied as needed, with clearer
separation of cases for content, public, and external assets.
(F768070bL263R373,
[[1]](diffhunk://#diff-0d1ade7f3d86ad72c66b573c31b0bc34d318dbf964198164719822d300d397d1L310-R398)
[[2]](diffhunk://#diff-0d1ade7f3d86ad72c66b573c31b0bc34d318dbf964198164719822d300d397d1L345-L349)
[[3]](diffhunk://#diff-0d1ade7f3d86ad72c66b573c31b0bc34d318dbf964198164719822d300d397d1L360-R425)
**Testing and configuration updates:**
* Added a new `test:scripts` npm script for running script-level tests,
and updated the Nx test command to use this script for the docs app.
[[1]](diffhunk://#diff-d03d2ce97fad5059ad6248fca5f5919994b09bca360f883318c03f1f817ae677R19)
[[2]](diffhunk://#diff-92d9997980c0871325f1a46a6d363cc28da597bd19ed327e979774d9e7838cabL216-R216)
These changes improve the reliability, security, and developer
experience of the documentation build process.
This pull request significantly expands and restructures the Kubernetes
deployment documentation for Zitadel. It introduces detailed,
task-focused guides for installation, configuration, ingress, and
database setup, replacing the previous minimal documentation. The new
docs provide comprehensive instructions and best practices for deploying
Zitadel on Kubernetes using Helm, including security, scaling, and high
availability considerations.
The most important changes are:
**Documentation Restructuring and Overview**
- Added a new `index.mdx` providing an overview of the Zitadel Helm
chart, architecture, prerequisites, and quick links to relevant
resources and next steps.
- Removed the old minimal Kubernetes deployment page and replaced it
with a structured, multi-page documentation set.
**Installation and Setup**
- Added an `installation.mdx` guide with step-by-step instructions for
preparing prerequisites, creating Kubernetes secrets, configuring
`values.yaml`, installing the Helm chart, and verifying the deployment.
**Configuration and Best Practices**
- Added a `configuration.mdx` guide covering Helm chart configuration
options, including replica count, container images, security contexts,
external domain setup, secrets management, scaling, autoscaling, pod
disruption budgets, and anti-affinity rules.
**Ingress and Database Configuration**
- Added an `ingress.mdx` guide detailing how to configure Kubernetes
ingress resources for Zitadel and Login containers, including TLS
termination and certificate management.
- Added a `database.mdx` guide explaining how to connect Zitadel to
PostgreSQL with various TLS/security options and how to manage database
credentials and certificates using Kubernetes secrets.
This pull request updates the fallback branch logic and improves
handling of branch names in the `fetch-remote-content.mjs` script. The
changes ensure better compatibility with both `main` and `master`
branches, and clarify how documentation versions are labeled.
Branch handling improvements:
* Changed the fallback branch from `fuma-docs` to `main` for fetching
content when a newer version does not exist.
* Updated branch detection logic to recognize both `main` and `master`
as valid primary branches, instead of just `main` and `fuma-docs`.
* Improved local version labeling: if the current branch is `main` or
`master`, it now returns a standardized label (`ZITADEL Docs`) and marks
it as not unreleased; other branches are handled accordingly.
## Todos for release
- [x] Configure Env in docs project on vercel
- [x] Configure Root Path in the docs project on vercel
- [ ] Remove old CSP https://github.com/zitadel/website/pull/1592
## What we did
This pull request migrates the project documentation from the old
`docs/` directory to the new `apps/docs/` directory, introduces a new
documentation system built with Next.js and Fumadocs, and updates all
relevant references, configuration files, and documentation to reflect
this change. It also adds new configuration and ignore files for the new
documentation app, updates CI and linting to exclude the new docs from
certain checks, and revises the contributing guidelines accordingly.
**Documentation System Migration and New Docs App**
* Migrated all documentation from `docs/` to `apps/docs/`, and updated
all references in `README.md`, `CONTRIBUTING.md`, and other files to
point to the new location.
[[1]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L585-L640)
[[2]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L660-R607)
[[3]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L740-R687)
[[4]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L2-R3)
[[5]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L30-R30)
* Added a new Next.js/Fumadocs-based documentation app under
`apps/docs/`, including core app files, layouts, routing, search API,
and a comprehensive `README.md` with development and contribution
instructions.
[[1]](diffhunk://#diff-5a1b07344a2c1b4d3f37b23ff1388b62cd9f57dea3c1cd23d8a0412b7602b132R1-R74)
[[2]](diffhunk://#diff-462b9ad1eabbb7d1c29bb9c36e4931eb180fd7190900e6d2babf8f4d66ad1c28R1-R39)
[[3]](diffhunk://#diff-e16ae25660ded787b10ac35dea96d5ecaacf895dae0afc8a9bd4382dc79a8c87R1-R7)
[apps/docs/app/[[...slug]]/layout.tsxR1-R81](diffhunk://#diff-59e08acde4e805b7aeccef1dcf98f1d71dfc550777e6b9402085cee0e9fa4e0aR1-R81),
[apps/docs/app/[[...slug]]/page.tsxR1-R79](diffhunk://#diff-e5df3f80d0fa01e12d63d81f29c57a9d14e846c78fd3beabb2ef768e38fd9580R1-R79),
[[4]](diffhunk://#diff-389b34918e040cacaa87cd7201ffa462cc2b0b716736f537e3d3c660ac69353bR1-R7)
[[5]](diffhunk://#diff-d3b03416d1c457b19f1c27b26f2db741412df841b875c26ccadc36e4522247f4R1-R29)
[[6]](diffhunk://#diff-c8fb8339570a5305809be7c618e14705fd86390dc278e6ce8ba224a7bc8b0c3cR1-R25)
**Configuration and Tooling Updates**
* Updated `.github/workflows/codeql.yml`, `.golangci.yaml`, and
`.github/dependabot.yml` to properly handle the new docs app: excluded
`apps/docs` from certain checks, added npm dependency updates for the
docs app, and excluded generated content.
[[1]](diffhunk://#diff-12783128521e452af0cfac94b99b8d250413c516ec71fe6d97dbea666ff7ba27L8-R14)
[[2]](diffhunk://#diff-9917ddc9f1c3304218f7269265b746d997c5c0615478177b5fceecd33ef47cb5R5-R6)
[[3]](diffhunk://#diff-9917ddc9f1c3304218f7269265b746d997c5c0615478177b5fceecd33ef47cb5R126-R129)
[[4]](diffhunk://#diff-dd4fbda47e51f1e35defb9275a9cd9c212ecde0b870cba89ddaaae65c5f3cd28R89-R106)
* Updated `.devcontainer/devcontainer.json` to use the latest Go 1.25.3
version for consistency.
**Licensing and Miscellaneous**
* Added `apps/docs/` to the list of licensed directories in
`LICENSING.md`.
These changes ensure the documentation is now maintained in a modern,
scalable system and all project tooling is updated to support the new
structure.
---------
Co-authored-by: Federico Coppede <fcoppede@gmail.com>
fcoppede
Livio SpringandGitHub
Fabienne BühlerandGitHub
Florian ForsterandGitHub
Mridang AgarwallaandGitHub
Vitor Bari BucciantiandGitHub