mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-22 23:42:16 +00:00
d8ea041c56
## 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]>
65 lines
2.8 KiB
Plaintext
65 lines
2.8 KiB
Plaintext
---
|
|
title: External ZITADEL Access
|
|
sidebar_label: Instance Not Found
|
|
---
|
|
|
|
## Why do I get an "Instance not found" error?
|
|
|
|
Also, ZITADEL has the [concept of virtual instances](/concepts/structure/instance#multiple-virtual-instances).
|
|
It uses a requests Host header to determine which virtual instance to use.
|
|
This is useful for multi-tenancy and resource sharing, for example in SaaS scenarios.
|
|
For most cases however, ZITADEL should run on exactly one domain.
|
|
|
|
This guide assumes you are already familiar with [configuring ZITADEL](./configure).
|
|
|
|
## Standard Config
|
|
|
|
ZITADEL only serves requests sent to the expected protocol, host and port.
|
|
For local testing purposes, you can use following configuration:
|
|
|
|
```yaml
|
|
ExternalDomain: localhost
|
|
ExternalPort: 8080
|
|
ExternalSecure: false
|
|
```
|
|
|
|
For productive setups however, we recommend using HTTPS and a Custom Domain:
|
|
|
|
```yaml
|
|
ExternalDomain: 'zitadel.my.domain'
|
|
ExternalPort: 443
|
|
ExternalSecure: true
|
|
```
|
|
|
|
## Changing ExternalDomain, ExternalPort or ExternalSecure
|
|
|
|
You can change the ExternalDomain, ExternalPort and ExternalSecure configuration options at any time.
|
|
However, for ZITADEL to be able to pick up the changes, [you need to rerun ZITADELs setup phase](/self-hosting/manage/updating_scaling#the-setup-phase).
|
|
|
|
## Running ZITADEL behind a Reverse Proxy
|
|
|
|
If you run ZITADEL behind a reverse proxy, you need to ensure that it sends the correct request headers to ZITADEL.
|
|
The proxy must either ensure that
|
|
- the original *Host* header value is assigned to the *Forwarded* headers host directive.
|
|
- the original requests *Host* header value is unchanged by the proxy.
|
|
|
|
Check out the [reverse proxy configuration examples](/self-hosting/manage/reverseproxy/reverse_proxy) for more information.
|
|
|
|
## Organization Domains
|
|
|
|
Note that by default, you cannot access ZITADEL at an organizations domain.
|
|
Organization level domains [are intended for routing users by their login methods to their correct organization](/guides/solution-scenarios/domain-discovery).
|
|
|
|
However, if you want to access ZITADEL at an organization domain, [you can add additional domains using the System API](/reference/api/system/zitadel.system.v1.SystemService.AddDomain).
|
|
Be aware that you won't automatically have the organizations context when you access ZITADEL like this.
|
|
|
|
## Generated Subdomains
|
|
|
|
ZITADEL creates random subdomains for [each new virtual instance](/concepts/structure/instance#multiple-virtual-instances).
|
|
You can immediately access the ZITADEL Management Console and APIs using these subdomains without further actions.
|
|
|
|
## More Information
|
|
|
|
- [Check out the production-near loadbalancing example with Traefik](/self-hosting/manage/reverseproxy/traefik)
|
|
- [Explore some concrete proxy configuration examples for ZITADEL using the domain 127.0.0.1.sslip.io](/self-hosting/manage/reverseproxy/reverse_proxy)
|