docs: introduce versioned docs and migrate to fuma (#11166)

## 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 <[email protected]>
This commit is contained in:
Florian Forster
2026-01-29 08:38:36 -08:00
committed by GitHub
co-authored by Federico Coppede
parent 7b6395c348
commit d8ea041c56
2826 changed files with 78739 additions and 23571 deletions
@@ -0,0 +1,2 @@
defaults.yaml
steps.yaml
@@ -0,0 +1,56 @@
---
title: Download the docker compose example configuration.
---
import CodeBlock from '@/components/docusaurus/code-block';
import DockerComposeSource from "./docker-compose.yaml"
import ExampleZITADELConfigSource from "./example-zitadel-config.yaml"
import ExampleZITADELSecretsSource from "./example-zitadel-secrets.yaml"
import ExampleZITADELInitStepsSource from "./example-zitadel-init-steps.yaml"
The docker compose example mounts the example zitadel configuration files to the ZITADEL container.
By executing the commands below, you will download the following files:
<details>
<summary>docker-compose.yaml</summary>
<CodeBlock language="yaml">{DockerComposeSource}</CodeBlock>
</details>
<details>
<summary>example-zitadel-config.yaml</summary>
<CodeBlock language="yaml">{ExampleZITADELConfigSource}</CodeBlock>
</details>
<details>
<summary>example-zitadel-secrets.yaml</summary>
<CodeBlock language="yaml">{ExampleZITADELSecretsSource}</CodeBlock>
</details>
<details>
<summary>example-zitadel-init-steps.yaml</summary>
<CodeBlock language="yaml">{ExampleZITADELInitStepsSource}</CodeBlock>
</details>
```bash
# Download the docker compose example configuration.
wget https://raw.githubusercontent.com/zitadel/zitadel/main/docs/self-hosting/manage/configure/docker-compose.yaml
# Download and adjust the example configuration file containing standard configuration.
wget https://raw.githubusercontent.com/zitadel/zitadel/main/docs/self-hosting/manage/configure/example-zitadel-config.yaml
# Download and adjust the example configuration file containing secret configuration.
wget https://raw.githubusercontent.com/zitadel/zitadel/main/docs/self-hosting/manage/configure/example-zitadel-secrets.yaml
# Download and adjust the example configuration file containing database initialization configuration.
wget https://raw.githubusercontent.com/zitadel/zitadel/main/docs/self-hosting/manage/configure/example-zitadel-init-steps.yaml
# 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
export ZITADEL_MASTERKEY="$(cat ./zitadel-masterkey)"
# Run the database and application containers
docker compose up --detach
```
@@ -0,0 +1,6 @@
To run Zitadel on Kubernetes, use [the official Zitadel Helm chart](https://github.com/zitadel/zitadel-charts).
Configure Zitadel using native Helm values.
You can manage secrets through Helm values, letting Helm create Kubernetes secrets.
Alternatively, reference existing Kubernetes secrets managed outside of Helm.
See the [referenced secrets example](https://github.com/zitadel/zitadel-charts/tree/main/examples/3-referenced-secrets) in the charts */examples* folder.
For a quick setup, check out the [insecure Postgres example](https://github.com/zitadel/zitadel-charts/tree/main/examples/1-postgres-insecure).
@@ -0,0 +1,74 @@
---
title: Download and adjust the example configuration file containing standard configuration
---
import CodeBlock from '@/components/docusaurus/code-block';
import ExampleZITADELConfigSource from "./example-zitadel-config.yaml"
import ExampleZITADELSecretsSource from "./example-zitadel-secrets.yaml"
import ExampleZITADELInitStepsSource from "./example-zitadel-init-steps.yaml"
### Configure by Files
By executing the commands below, you will download the following files:
<details>
<summary>example-zitadel-config.yaml</summary>
<CodeBlock language="yaml">{ExampleZITADELConfigSource}</CodeBlock>
</details>
<details>
<summary>example-zitadel-secrets.yaml</summary>
<CodeBlock language="yaml">{ExampleZITADELSecretsSource}</CodeBlock>
</details>
<details>
<summary>example-zitadel-init-steps.yaml</summary>
<CodeBlock language="yaml">{ExampleZITADELInitStepsSource}</CodeBlock>
</details>
```bash
# Download and adjust the example configuration file containing standard configuration
wget https://raw.githubusercontent.com/zitadel/zitadel/main/docs/self-hosting/manage/configure/example-zitadel-config.yaml
# Download and adjust the example configuration file containing secret configuration
wget https://raw.githubusercontent.com/zitadel/zitadel/main/docs/self-hosting/manage/configure/example-zitadel-secrets.yaml
# Download and adjust the example configuration file containing database initialization configuration
wget https://raw.githubusercontent.com/zitadel/zitadel/main/docs/self-hosting/manage/configure/example-zitadel-init-steps.yaml
# A single ZITADEL instance always needs the same 32 characters long masterkey
# If you haven't done so already, you can generate a new one
# The key must be passed as argument
ZITADEL_MASTERKEY="$(LC_ALL=C tr -dc '[:graph:]' </dev/urandom | head -c 32)"
# Pass zitadel configuration by configuration files
zitadel start-from-init \
--config ./example-zitadel-config.yaml \
--config ./example-zitadel-secrets.yaml \
--steps ./example-zitadel-init-steps.yaml \
--masterkey "${ZITADEL_MASTERKEY}"
```
### Configure by Environment Variables
```bash
# Set runtime environment variables
export ZITADEL_DATABASE_POSTGRES_HOST=my.database
export ZITADEL_DATABASE_POSTGRES_PORT=5432
export ZITADEL_DATABASE_POSTGRES_DATABASE=zitadel
export ZITADEL_DATABASE_POSTGRES_USER_USERNAME=my_zitadel_db_user
export ZITADEL_DATABASE_POSTGRES_USER_PASSWORD=Secret_DB_User_Password
export ZITADEL_DATABASE_POSTGRES_USER_SSL_MODE=disable
export ZITADEL_DATABASE_POSTGRES_ADMIN_USERNAME=root
export ZITADEL_DATABASE_POSTGRES_ADMIN_SSL_MODE=disable
export ZITADEL_FIRSTINSTANCE_ORG_HUMAN_USERNAME="root"
export ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD="RootPassword1!"
# 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
# Let the zitadel binary read configuration from environment variables
zitadel start-from-init --masterkey "${ZITADEL_MASTERKEY}" --tlsMode disabled --masterkeyFile ./zitadel-masterkey
```
@@ -0,0 +1 @@
Open your favorite internet browser at http://localhost:8080/ui/[email protected] and use the password _RootPassword1!_
@@ -0,0 +1,125 @@
---
title: Configuration Options in ZITADEL
sidebar_label: Configuration
---
import LinuxUnix from "./_linuxunix.mdx";
import Compose from "./_compose.mdx";
import Helm from "./_helm.mdx";
import Login from "./_login.mdx";
import CodeBlock from "@/components/docusaurus/code-block";
import DefaultsYamlSource from "../../../../../../cmd/defaults.yaml";
import StepsYamlSource from "../../../../../../cmd/setup/steps.yaml";
import SkipSuperUserDatabaseQueries from "./example-skip-superuser-queries.yaml";
This guide assumes you are familiar with [running ZITADEL using the least amount of configuration possible](/self-hosting/deploy/overview).
## Configuration files
### Runtime configuration file
You can configure the runtime using the `--config` flag of the `zitadel` binary.
Also, you can use the environment variables listed in the defaults.yaml.
<Callout>
For overwriting the default configuration for the first instance created by zitadel setup, use the FirstInstance section in the [database initialization file](#database-initialization-file).
</Callout>
<details>
<summary>defaults.yaml</summary>
<CodeBlock language="yaml">{DefaultsYamlSource}</CodeBlock>
</details>
### Database initialization file
ZITADEL uses a [different configuration file](https://github.com/zitadel/zitadel/blob/main/cmd/setup/steps.yaml) for _database initialization steps_.
Use the `--steps` flag of the `zitadel` binary to provide this configuration file.
Also, you can use the environment variables listed in the steps.yaml.
<Callout>
By using the FirstInstance section, you can overwrite the [DefaultInstance configuration](#runtime-configuration-file) for the first instance created by zitadel setup.
</Callout>
<details>
<summary>steps.yaml</summary>
<CodeBlock language="yaml">{StepsYamlSource}</CodeBlock>
</details>
### Pre-existing Database and User
By default, when you run `zitadel init` or `zitadel start-from-init`, ZITADEL checks if the specified database and user exist. If they don't, ZITADEL creates them and grants the necessary permissions.
If you manage the database and user manually, you can instruct ZITADEL to skip these checks. This is useful if the ZITADEL user has limited database permissions, for example, if it is not a `SUPERUSER`. This scenario is most common on cloud providers.
To skip the checks, you must ensure the database objects (database, user, grant) exist before running the commands and then set the `Database.postgres.Admin.ExistingDatabase` field in your configuration as shown below. This tells ZITADEL to connect to the existing database as an admin user, bypassing the creation and permission steps.
<details>
<summary>skip-superuser-queries-config.yaml</summary>
<CodeBlock language="yaml">{SkipSuperUserDatabaseQueries}</CodeBlock>
</details>
### Multiple configuration files
ZITADEL merges configuration files when multiple `--config` and `--steps` flags are provided.
You can use these flags to handle standard configuration files differently from secret configuration files.
For example, standard configuration files stored in git may contain public information such as a database hostname.
To use private information — such as a database admin credential — without storing it in git, use an extra `--config` or `--steps` flag that requests the private information from a secret manager.
## Environment variables
All configuration properties are configurable using environment variables.
ZITADEL environment variable keys are prefixed with `ZITADEL_`.
For example, to configure the default ZITADEL IAM admin username and password set the `zitadel` binary runtime environment variables `ZITADEL_FIRSTINSTANCE_ORG_HUMAN_USERNAME` and `ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD`.
All supported environment variables are listed in the [runtime configuration file](#runtime-configuration-file) and the [database initialization file](#database-initialization-file).
### Proxy configuration
A proxy for outgoing connections can be configured using the environment variables: Use `HTTP_PROXY` for outgoing HTTP requests, and `HTTPS_PROXY` for outgoing HTTPS requests.
These environment variables are used as a proxy URL.
To exclude specific hosts from proxying, set the `NO_PROXY` environment variable: The value is interpreted as a comma-separated string.
For more information on the `NO_PROXY` environment variable, read the [`httpproxy` Go doc](https://pkg.go.dev/golang.org/x/net/http/httpproxy#Config).
## Masterkey
The masterkey is used to AES256-encrypt other generated encryption keys.
It must be 32 bytes.
There are three ways to pass the masterkey to the `zitadel` binary:
- By value: Use the flag `--masterkey My_Master_Key_Which_Has_32_Bytes`
- By environment variable `ZITADEL_MASTERKEY`: Use the flag `--masterkeyFromEnv`
- By file: Use the flag `--masterkeyFile /path/to/file`
## Passing the configuration
<Tabs
groupId="installation-target"
default="linuxunix"
values={[
{ label: "Linux and Unix", value: "linuxunix" },
{ label: "Docker Compose", value: "compose" },
{ label: "Kubernetes (Helm)", value: "k8s" },
]}
>
<Tab value="linuxunix">
<LinuxUnix components={props.components} />
<Login components={props.components} />
</Tab>
<Tab value="compose">
<Compose components={props.components} />
<Login components={props.components} />
</Tab>
<Tab value="k8s">
<Helm components={props.components} />
</Tab>
</Tabs>
## What's next
- Read more about [the login process](/guides/integrate/login/login-users).
- If you are running ZITADEL in production, you need to [customize your own domain](../custom-domain).
- Check out all possible [runtime configuration properties and their defaults in the source code](https://github.com/zitadel/zitadel/blob/main/cmd/defaults.yaml)
- Check out all possible [setup step configuration properties and their defaults in the source code](https://github.com/zitadel/zitadel/blob/main/cmd/setup/steps.yaml)
<Callout type="warn">
The ZITADEL management console [requires end-to-end HTTP/2 support](/self-hosting/manage/http2)
</Callout>
@@ -0,0 +1,40 @@
services:
zitadel:
restart: "always"
networks:
- "zitadel"
image: "ghcr.io/zitadel/zitadel:latest"
command: 'start-from-init --config /example-zitadel-config.yaml --config /example-zitadel-secrets.yaml --steps /example-zitadel-init-steps.yaml --masterkey "${ZITADEL_MASTERKEY}" --tlsMode disabled'
ports:
- "8080:8080"
volumes:
- "./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"
depends_on:
db:
condition: "service_healthy"
db:
image: postgres:17-alpine
restart: always
environment:
- POSTGRES_USER=root
- POSTGRES_PASSWORD=postgres
networks:
- 'zitadel'
healthcheck:
test: ["CMD-SHELL", "pg_isready", "-d", "db_prod"]
interval: 10s
timeout: 60s
retries: 5
start_period: 10s
volumes:
- 'data:/var/lib/postgresql/data:rw'
networks:
zitadel:
volumes:
data:
@@ -0,0 +1,10 @@
Database:
postgres:
Database: existing_database
# Admin credentials should be the same as the application user credentials
Admin:
Username: zitadel-user
ExistingDatabase: existing_database # this is used to connect the admin to the previously created database
# Application user credentials
User:
Username: zitadel-user
@@ -0,0 +1,19 @@
# All possible options and their defaults: https://github.com/zitadel/zitadel/blob/main/cmd/defaults.yaml
Log:
Level: 'info'
# Make ZITADEL accessible over HTTP, not HTTPS
ExternalSecure: false
# If not using the docker compose example, adjust these values for connecting ZITADEL to your PostgreSQL
Database:
postgres:
Host: 'db'
Port: 5432
Database: zitadel
User:
SSL:
Mode: 'disable'
Admin:
SSL:
Mode: 'disable'
@@ -0,0 +1,7 @@
# All possible options and their defaults: https://github.com/zitadel/zitadel/blob/main/cmd/setup/steps.yaml
FirstInstance:
Org:
Human:
# use the loginname [email protected]
Username: 'root'
Password: 'RootPassword1!'
@@ -0,0 +1,12 @@
# All possible options and their defaults: https://github.com/zitadel/zitadel/blob/main/cmd/defaults.yaml
# If not using the docker compose example, adjust these values for connecting ZITADEL to your PostgreSQL
Database:
postgres:
User:
# If the user doesn't exist already, it is created
Username: 'zitadel_user'
Password: 'zitadel_pw'
Admin:
Username: 'root'
Password: 'postgres'
@@ -0,0 +1,7 @@
---
title: Configure ZITADEL
---
Detailed configuration options for ZITADEL.
- [Configuration Guide](/self-hosting/manage/configure/configure)