Files
zitadel/apps/api/project.json
T
d8ea041c56 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]>
2026-01-29 08:38:36 -08:00

506 lines
23 KiB
JSON

{
"$schema": "../../node_modules/nx/schemas/project-schema.json",
"name": "@zitadel/api",
"projectType": "application",
"namedInputs": {
"sources": [
"{workspaceRoot}/cmd/**/*.go",
"{workspaceRoot}/internal/**/*.go",
"{workspaceRoot}/backend/**/*.go",
"{workspaceRoot}/proto/**/*.go",
"{workspaceRoot}/pkg/**/*.go",
"{workspaceRoot}/main.go",
"{workspaceRoot}/internal/**/*.yaml"
],
"runtime": [
"sources",
"{workspaceRoot}/go*",
"!{workspaceRoot}/internal/integration/**/*",
"!{workspaceRoot}/**/*_test.go",
"!{workspaceRoot}/**/integration_test/**/*"
],
"pack": [
{
"env": "VERSION"
},
"runtime"
]
},
"targets": {
"prod": {
"description": "Runs the Go-based API backend in production mode",
"continuous": true,
"dependsOn": [
"build"
],
"executor": "nx:run-commands",
"options": {
"parallel": false,
"commands": [
"./.artifacts/bin/$(go env GOOS)/$(go env GOARCH)/${ZITADEL_BINARY:-zitadel.local} start-from-init --config ${API_CONFIG_FILE} --steps ${API_CONFIG_FILE} --masterkey MasterkeyNeedsToHave32Characters"
]
},
"defaultConfiguration": "default",
"configurations": {
"default": {
"env": {
"API_CONFIG_FILE": "{projectRoot}/prod-default.yaml"
}
},
"test-integration-api": {
"env": {
"API_CONFIG_FILE": "{projectRoot}/test-integration-api.yaml"
}
},
"test-functional-ui": {
"env": {
"API_CONFIG_FILE": "{projectRoot}/test-functional-ui.yaml"
}
}
}
},
"build": {
"description": "Compiles the Go-based API backend into an executable binary.",
"dependsOn": [
"generate",
"build-console"
],
"command": "bash -c 'CGO_ENABLED=0 go build -o .artifacts/bin/$(go env GOOS)/$(go env GOARCH)/zitadel.local -ldflags=\"-s -w\"'",
"inputs": [
{
"runtime": "go env GOOS"
},
{
"runtime": "go env GOARCH"
},
"runtime",
{
"dependentTasksOutputFiles": "internal/api/ui/console/static/**/*"
}
],
"outputs": [
"{workspaceRoot}/.artifacts/bin/*/*/zitadel.local"
]
},
"generate": {
"description": "Generates the code needed to start a full-featured API: gRPC and OpenAPI stubs, static files for the embedded login v1, asset routes and documentation.",
"dependsOn": [
"generate-stubs",
"generate-assets",
"generate-statik"
]
},
"lint-install": {
"description": "Installs golangci-lint binary for linting. Using go install is not recommended in the official docs, because this can produce non-deterministic results.",
"cache": true,
"command": "curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/HEAD/install.sh | sh -s -- -b .artifacts/bin/$(go env GOOS)/$(go env GOARCH) v2.5.0",
"inputs": [
{
"runtime": "go env GOOS"
},
{
"runtime": "go env GOARCH"
}
],
"outputs": [
"{workspaceRoot}/.artifacts/bin/*/*/golangci-lint"
]
},
"lint": {
"description": "Lints the Go code with golangci-lint using the configuration in .golangci.yaml",
"dependsOn": [
"lint-install",
"generate-stubs",
"generate-assets"
],
"command": "PATH=\"${PWD}/.artifacts/bin/$(go env GOOS)/$(go env GOARCH):$PATH\" golangci-lint run --timeout 15m --config ./.golangci.yaml --verbose",
"cache": true,
"inputs": [
"sources",
"{workspaceRoot}/.golangci.yaml"
]
},
"test": {
"description": "Runs all tests (unit and integration)",
"dependsOn": [
"test-unit",
"test-integration"
]
},
"test-unit": {
"description": "Runs the unit tests with coverage",
"dependsOn": [
"generate"
],
"command": "go test -race -coverprofile=profile.api.test-unit.cov -coverpkg=./internal/...,./backend/... ./...",
"inputs": [
"sources",
"{workspaceRoot}/go*"
],
"outputs": [
"{workspaceRoot}/profile.api.test-unit.cov"
]
},
"test-integration-build": {
"description": "Builds the test binary for integration tests.",
"dependsOn": [
"generate"
],
"command": "go build -cover -race -tags integration -o .artifacts/bin/$(go env GOOS)/$(go env GOARCH)/zitadel.test main.go",
"cache": true,
"inputs": [
{
"runtime": "go env GOOS"
},
{
"runtime": "go env GOARCH"
},
"sources",
"{workspaceRoot}/internal/integration/**",
"{workspaceRoot}/go*"
],
"outputs": [
"{workspaceRoot}/.artifacts/bin/*/*/zitadel.test"
]
},
"test-integration-run-db": {
"description": "Runs the database and cache for integration tests.",
"continuous": true,
"command": "nx run @zitadel/devcontainer:compose up --force-recreate --renew-anon-volumes db-api-integration cache-api-integration"
},
"test-integration-run-api": {
"description": "Runs the API server for the integration tests.",
"continuous": true,
"dependsOn": [
"test-integration-build"
],
"executor": "nx:run-commands",
"options": {
"env": {
"ZITADEL_BINARY": "zitadel.test",
"GOCOVERDIR": "{workspaceRoot}/.artifacts/api-test-integration/coverage",
"GORACE": "log_path=.artifacts/api-test-integration/race.log"
},
"parallel": false,
"commands": [
"rm -rf .artifacts/api-test-integration",
"mkdir -p ${GOCOVERDIR}",
"nx run @zitadel/api:prod:test-integration-api --excludeTaskDependencies"
]
}
},
"test-integration": {
"description": "Runs the integration tests sequentially with coverage and race condition detection. Go test caching is disabled, because the tests run against an out-of-process API.",
"dependsOn": [
"test-integration-run-db",
"test-integration-run-api"
],
"executor": "nx:run-commands",
"options": {
"parallel": false,
"env": {
"GOCOVERDIR": "{workspaceRoot}/.artifacts/api-test-integration/coverage"
},
"commands": [
"wait-on --verbose --interval 2000 --simultaneous 1 --timeout 30m \"${ZITADEL_API_URL}/debug/ready\"",
"bash -c 'go test -race -count 1 -tags integration -timeout 60m -parallel 1 $(go list -tags integration ./... | grep -e \"integration_test\" -e \"events_testing\")'",
"go tool covdata textfmt -i=$GOCOVERDIR -pkg=github.com/zitadel/zitadel/internal/...,github.com/zitadel/zitadel/cmd/...,github.com/zitadel/zitadel/backend/... -o profile.api.test-integration.cov",
"nx run @zitadel/api:test-integration-stop"
]
},
"inputs": [
{
"runtime": "go env GOOS"
},
{
"runtime": "go env GOARCH"
},
"sources",
"{workspaceRoot}/internal/integration/**",
"{workspaceRoot}/go*"
],
"outputs": [
"{workspaceRoot}/profile.api.test-integration.cov"
]
},
"test-integration-stop": {
"description": "Stops the database and cache containers used for integration tests.",
"command": "nx run @zitadel/devcontainer:compose down --volumes db-api-integration cache-api-integration"
},
"build-console": {
"description": "Builds the Management Console and copies its static files to the API.",
"dependsOn": [
"@zitadel/console:build"
],
"command": "find internal/api/ui/console/static -mindepth 1 ! -name 'gitkeep' -delete -print && cp -r -v console/dist/console/* internal/api/ui/console/static",
"cache": true,
"inputs": [
{
"dependentTasksOutputFiles": "console/dist/console/**/*"
}
],
"outputs": [
"{workspaceRoot}/internal/api/ui/console/static"
]
},
"generate-install": {
"description": "Installs the binaries needed for generating code. We avoid using go tools so the dev tool dependencies don't interfere with the prod dependencies.",
"executor": "nx:run-commands",
"options": {
"commands": [
"GOBIN=${PWD}/.artifacts/bin/$(go env GOOS)/$(go env GOARCH) go install github.com/daixiang0/[email protected]",
"GOBIN=${PWD}/.artifacts/bin/$(go env GOOS)/$(go env GOARCH) go install github.com/dmarkham/[email protected]",
"GOBIN=${PWD}/.artifacts/bin/$(go env GOOS)/$(go env GOARCH) go install go.uber.org/mock/[email protected]",
"GOBIN=${PWD}/.artifacts/bin/$(go env GOOS)/$(go env GOARCH) go install golang.org/x/tools/cmd/[email protected]",
"GOBIN=${PWD}/.artifacts/bin/$(go env GOOS)/$(go env GOARCH) go install github.com/rakyll/[email protected]",
"GOBIN=${PWD}/.artifacts/bin/$(go env GOOS)/$(go env GOARCH) go install github.com/bufbuild/buf/cmd/[email protected]",
"GOBIN=${PWD}/.artifacts/bin/$(go env GOOS)/$(go env GOARCH) go install google.golang.org/protobuf/cmd/[email protected]",
"GOBIN=${PWD}/.artifacts/bin/$(go env GOOS)/$(go env GOARCH) go install google.golang.org/grpc/cmd/[email protected]",
"GOBIN=${PWD}/.artifacts/bin/$(go env GOOS)/$(go env GOARCH) go install github.com/grpc-ecosystem/grpc-gateway/v2/[email protected]",
"GOBIN=${PWD}/.artifacts/bin/$(go env GOOS)/$(go env GOARCH) go install github.com/grpc-ecosystem/grpc-gateway/v2/[email protected]",
"GOBIN=${PWD}/.artifacts/bin/$(go env GOOS)/$(go env GOARCH) go install github.com/envoyproxy/[email protected]",
"GOBIN=${PWD}/.artifacts/bin/$(go env GOOS)/$(go env GOARCH) go install connectrpc.com/connect/cmd/[email protected]",
"GOBIN=${PWD}/.artifacts/bin/$(go env GOOS)/$(go env GOARCH) go install google.golang.org/protobuf/cmd/[email protected]",
"GOBIN=${PWD}/.artifacts/bin/$(go env GOOS)/$(go env GOARCH) go install ./internal/protoc/protoc-gen-authoption",
"GOBIN=${PWD}/.artifacts/bin/$(go env GOOS)/$(go env GOARCH) go install ./internal/protoc/protoc-gen-zitadel"
]
},
"cache": true,
"inputs": [
{
"runtime": "go env GOOS"
},
{
"runtime": "go env GOARCH"
},
"{workspaceRoot}/internal/protoc/protoc-gen-authoption/**/*",
"{workspaceRoot}/internal/protoc/protoc-gen-zitadel/**/*"
],
"outputs": [
"{workspaceRoot}/.artifacts/bin/*/*/enumer",
"{workspaceRoot}/.artifacts/bin/*/*/mockgen",
"{workspaceRoot}/.artifacts/bin/*/*/stringer",
"{workspaceRoot}/.artifacts/bin/*/*/statik",
"{workspaceRoot}/.artifacts/bin/*/*/buf",
"{workspaceRoot}/.artifacts/bin/*/*/protoc-gen-go",
"{workspaceRoot}/.artifacts/bin/*/*/protoc-gen-go-grpc",
"{workspaceRoot}/.artifacts/bin/*/*/protoc-gen-grpc-gateway",
"{workspaceRoot}/.artifacts/bin/*/*/protoc-gen-openapiv2",
"{workspaceRoot}/.artifacts/bin/*/*/protoc-gen-validate",
"{workspaceRoot}/.artifacts/bin/*/*/protoc-gen-connect-go",
"{workspaceRoot}/.artifacts/bin/*/*/protoc-gen-authoption",
"{workspaceRoot}/.artifacts/bin/*/*/protoc-gen-zitadel"
]
},
"generate-stubs": {
"description": "Generates the gRPC and OpenAPI stubs from the proto files.",
"dependsOn": [
"generate-install"
],
"executor": "nx:run-commands",
"options": {
"parallel": false,
"commands": [
"bash -c 'PATH=\"${PWD}/.artifacts/bin/$(go env GOOS)/$(go env GOARCH):$PATH\" buf generate'",
"mkdir -p pkg/grpc openapi/v2/zitadel",
"cp -r .artifacts/grpc/github.com/zitadel/zitadel/pkg/grpc/** pkg/grpc/",
"cp -r .artifacts/grpc/zitadel/ openapi/v2/zitadel"
]
},
"cache": true,
"inputs": [
"{workspaceRoot}/proto/**/*",
"{workspaceRoot}/buf.gen.yaml",
"{workspaceRoot}/buf.yaml"
],
"outputs": [
"{workspaceRoot}/pkg/grpc/**/*",
"{workspaceRoot}/openapi/v2/zitadel/**/*"
]
},
"generate-statik": {
"description": "Generates statik files for embedding static resources",
"dependsOn": [
"generate-install"
],
"executor": "nx:run-commands",
"options": {
"commands": [
"PATH=\"${PWD}/.artifacts/bin/$(go env GOOS)/$(go env GOARCH):$PATH\" go generate internal/api/ui/login/static/resources/generate.go",
"PATH=\"${PWD}/.artifacts/bin/$(go env GOOS)/$(go env GOARCH):$PATH\" go generate internal/api/ui/login/statik/generate.go",
"PATH=\"${PWD}/.artifacts/bin/$(go env GOOS)/$(go env GOARCH):$PATH\" go generate internal/notification/statik/generate.go",
"PATH=\"${PWD}/.artifacts/bin/$(go env GOOS)/$(go env GOARCH):$PATH\" go generate internal/statik/generate.go"
],
"parallel": false
},
"cache": true,
"inputs": [
{
"runtime": "go env GOOS"
},
{
"runtime": "go env GOARCH"
},
"{workspaceRoot}/internal/statik/generate.go",
"{workspaceRoot}/internal/notification/statik/generate.go",
"{workspaceRoot}/internal/api/ui/login/static/resources/generate.go",
"{workspaceRoot}/internal/api/ui/login/statik/generate.go"
],
"outputs": [
"{workspaceRoot}/internal/statik/statik.go",
"{workspaceRoot}/internal/notification/statik/statik.go",
"{workspaceRoot}/internal/api/ui/login/static/resources/themes/zitadel/css/zitadel.css*",
"{workspaceRoot}/internal/api/ui/login/statik/statik.go"
]
},
"generate-assets": {
"description": "Generates asset routes and documentation",
"dependsOn": [
"generate-install"
],
"command": "mkdir -p apps/docs/content/apis/assets && go run internal/api/assets/generator/asset_generator.go -directory=internal/api/assets/generator/ -assets=apps/docs/content/apis/assets/assets.mdx",
"cache": true,
"inputs": [
"{workspaceRoot}/internal/api/assets/generator/asset_generator.go"
],
"outputs": [
"{workspaceRoot}/internal/api/assets/authz.go",
"{workspaceRoot}/internal/api/assets/router.go",
"{workspaceRoot}/apps/docs/content/apis/assets/assets.mdx"
]
},
"generate-go": {
"description": "Generates Go using Go native generation tools. This only needs to be run if sources for //go:generate files change, like for Stringer, Enumer, Mockgen etc.",
"dependsOn": [
"generate-install"
],
"command": "PATH=\"${PWD}/.artifacts/bin/$(go env GOOS)/$(go env GOARCH):$PATH\" go generate ./..."
},
"pack-platform": {
"description": "Cross-compiles the binary and packages it for the platform defined by GOOS and GOARCH environment variables. The version is taken from the ZITADEL_VERSION environment variable.",
"executor": "nx:run-commands",
"options": {
"parallel": false,
"commands": [
"mkdir -p .artifacts/pack .artifacts/bin/$GOOS/$GOARCH",
"bash -c 'EXT=\"\"; if [ \"$GOOS\" = \"windows\" ]; then EXT=\".exe\"; fi; echo \"Building for $GOOS-$GOARCH...\"; CGO_ENABLED=0 go build -o .artifacts/bin/$GOOS/$GOARCH/zitadel$EXT -ldflags=\"-s -w -X github.com/zitadel/zitadel/cmd/build.commit=$(git rev-parse --short HEAD) -X github.com/zitadel/zitadel/cmd/build.date=$(date \"+%Y-%m-%dT%T%z\" | sed -E \"s/.([0-9]{2})([0-9]{2})$/-\\1:\\2/\") -X github.com/zitadel/zitadel/cmd/build.version=${ZITADEL_VERSION}\"'",
"bash -c 'EXT=\"\"; if [ \"$GOOS\" = \"windows\" ]; then EXT=\".exe\"; fi; FOLDER=\"zitadel-$GOOS-$GOARCH\"; mkdir -p \".artifacts/pack/$FOLDER\"; cp README.md LICENSE \".artifacts/bin/$GOOS/$GOARCH/zitadel$EXT\" \".artifacts/pack/$FOLDER/\"; tar -czvf \".artifacts/pack/$FOLDER.tar.gz\" -C .artifacts/pack \"$FOLDER\"; rm -rf \".artifacts/pack/$FOLDER\"'"
]
}
},
"pack-darwin-amd64": {
"description": "Packages the API for Darwin AMD64 (Intel) architecture",
"dependsOn": [
"generate",
"build-console"
],
"command": "GOOS=darwin GOARCH=amd64 nx run @zitadel/api:pack-platform",
"cache": true,
"inputs": [
"pack",
{
"env": "ZITADEL_VERSION"
}
],
"outputs": [
"{workspaceRoot}/.artifacts/pack/zitadel-darwin-amd64.tar.gz",
"{workspaceRoot}/.artifacts/bin/darwin/amd64/zitadel"
]
},
"pack-darwin-arm64": {
"description": "Packages the API for Darwin ARM64 (Apple Silicon) architecture",
"dependsOn": [
"generate",
"build-console"
],
"command": "GOOS=darwin GOARCH=arm64 nx run @zitadel/api:pack-platform",
"cache": true,
"inputs": [
"pack",
{
"env": "ZITADEL_VERSION"
}
],
"outputs": [
"{workspaceRoot}/.artifacts/pack/zitadel-darwin-arm64.tar.gz",
"{workspaceRoot}/.artifacts/bin/darwin/arm64/zitadel"
]
},
"pack-linux-amd64": {
"description": "Packages the API for Linux AMD64 architecture",
"dependsOn": [
"generate",
"build-console"
],
"command": "GOOS=linux GOARCH=amd64 nx run @zitadel/api:pack-platform",
"cache": true,
"inputs": [
"pack",
{
"env": "ZITADEL_VERSION"
}
],
"outputs": [
"{workspaceRoot}/.artifacts/pack/zitadel-linux-amd64.tar.gz",
"{workspaceRoot}/.artifacts/bin/linux/amd64/zitadel"
]
},
"pack-linux-arm64": {
"description": "Packages the API for Linux ARM64 architecture",
"dependsOn": [
"generate",
"build-console"
],
"command": "GOOS=linux GOARCH=arm64 nx run @zitadel/api:pack-platform",
"cache": true,
"inputs": [
"pack",
{
"env": "ZITADEL_VERSION"
}
],
"outputs": [
"{workspaceRoot}/.artifacts/pack/zitadel-linux-arm64.tar.gz",
"{workspaceRoot}/.artifacts/bin/linux/arm64/zitadel"
]
},
"pack-windows-amd64": {
"description": "Packages the API for Windows AMD64 architecture",
"dependsOn": [
"generate",
"build-console"
],
"command": "GOOS=windows GOARCH=amd64 nx run @zitadel/api:pack-platform",
"cache": true,
"inputs": [
"pack",
{
"env": "ZITADEL_VERSION"
}
],
"outputs": [
"{workspaceRoot}/.artifacts/pack/zitadel-windows-amd64.tar.gz",
"{workspaceRoot}/.artifacts/bin/windows/amd64/zitadel.exe"
]
},
"pack-windows-arm64": {
"description": "Packages the API for Windows ARM64 architecture",
"dependsOn": [
"generate",
"build-console"
],
"command": "GOOS=windows GOARCH=arm64 nx run @zitadel/api:pack-platform",
"cache": true,
"inputs": [
"pack",
{
"env": "ZITADEL_VERSION"
}
],
"outputs": [
"{workspaceRoot}/.artifacts/pack/zitadel-windows-arm64.tar.gz",
"{workspaceRoot}/.artifacts/bin/windows/arm64/zitadel.exe"
]
}
}
}