mirror of
https://github.com/zitadel/zitadel.git
synced 2025-01-06 13:07:52 +00:00
docs: copy config options to docs (#6143)
* poc * wip * works * upgrade yaml package * need to add global comments for shifting * wip: need index before working on comments * green * clean up * test null value * comment * package * delete * convert to module * render md table * tests with ESM * comments * top level gitignore * wip: new cases * arrays: green * array_test * treat comments on map without first element * fix some new case * skip leaf comments * output folder * comment * finish up for poc * arrays * create output dir * merge main, create tables * copy config options to docs * cleanup * recommend file configuration * language * add some explanations * some small typo fixes --------- Co-authored-by: mffap <mpa@zitadel.com> Co-authored-by: Florian Forster <florian@zitadel.com>
This commit is contained in:
Elio Bischof
GitHub
parent
57857b8d30
commit
7bc4aa9c76
File diff suppressed because one or more lines are too long
@ -1,41 +1,53 @@
|
||||
FirstInstance:
|
||||
MachineKeyPath:
|
||||
PatPath:
|
||||
InstanceName: ZITADEL
|
||||
DefaultLanguage: en
|
||||
# The machine key from the section FirstInstance.Org.Machine.MachineKey is written to the MachineKeyPath.
|
||||
MachineKeyPath: # ZITADEL_FIRSTINSTANCE_MACHINEKEYPATH
|
||||
# The personal access token from the section FirstInstance.Org.Machine.Pat is written to the PatPath.
|
||||
PatPath: # ZITADEL_FIRSTINSTANCE_PATPATH
|
||||
InstanceName: ZITADEL # ZITADEL_FIRSTINSTANCE_INSTANCENAME
|
||||
DefaultLanguage: en # ZITADEL_FIRSTINSTANCE_DEFAULTLANGUAGE
|
||||
Org:
|
||||
Name: ZITADEL
|
||||
Name: ZITADEL # ZITADEL_FIRSTINSTANCE_ORG_NAME
|
||||
# In the FirstInstance.Org.Human section, the initial organization's admin user with the role IAM_OWNER is defined.
|
||||
# ZITADEL either creates a human user or a machine user.
|
||||
# If FirstInstance.Org.Machine.Machine is defined, a service user is created with the IAM_OWNER role, not a human user.
|
||||
Human:
|
||||
# in case that UserLoginMustBeDomain is false (default) and you don't overwrite the username with an email,
|
||||
# In case UserLoginMustBeDomain is false (default) and you don't overwrite the username with an email,
|
||||
# it will be suffixed by the org domain (org-name + domain from config).
|
||||
# for example: zitadel-admin in org ZITADEL on domain.tld -> zitadel-admin@zitadel.domain.tld
|
||||
UserName: zitadel-admin
|
||||
FirstName: ZITADEL
|
||||
LastName: Admin
|
||||
NickName:
|
||||
DisplayName:
|
||||
# for example zitadel-admin in org ZITADEL on domain.tld -> zitadel-admin@zitadel.domain.tld
|
||||
UserName: zitadel-admin # ZITADEL_FIRSTINSTANCE_ORG_HUMAN_USERNAME
|
||||
FirstName: ZITADEL # ZITADEL_FIRSTINSTANCE_ORG_HUMAN_FIRSTNAME
|
||||
LastName: Admin # ZITADEL_FIRSTINSTANCE_ORG_HUMAN_LASTNAME
|
||||
NickName: # ZITADEL_FIRSTINSTANCE_ORG_HUMAN_NICKNAME
|
||||
DisplayName: # ZITADEL_FIRSTINSTANCE_ORG_HUMAN_DISPLAYNAME
|
||||
Email:
|
||||
Address: #uses the username if empty
|
||||
Verified: true
|
||||
PreferredLanguage: en
|
||||
Gender:
|
||||
# uses the username if empty
|
||||
Address: # ZITADEL_FIRSTINSTANCE_ORG_HUMAN_EMAIL_ADDRESS
|
||||
Verified: true # ZITADEL_FIRSTINSTANCE_ORG_HUMAN_EMAIL_VERIFIED
|
||||
PreferredLanguage: en # ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PREFERREDLANGUAGE
|
||||
Gender: # ZITADEL_FIRSTINSTANCE_ORG_HUMAN_GENDER
|
||||
Phone:
|
||||
Number:
|
||||
Verified:
|
||||
Password: Password1!
|
||||
PasswordChangeRequired: true
|
||||
Number: # ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PHONE_NUMBER
|
||||
Verified: # ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PHONE_VERIFIED
|
||||
Password: Password1! # ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD
|
||||
PasswordChangeRequired: true # ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED
|
||||
# In the FirstInstance.Org.Machine section, the initial organization's admin user with the role IAM_OWNER is defined.
|
||||
# ZITADEL either creates a human user or a machine user.
|
||||
# If FirstInstance.Org.Machine.Machine is defined, a service user is created with the IAM_OWNER role, not a human user.
|
||||
Machine:
|
||||
Machine:
|
||||
Username:
|
||||
Name:
|
||||
Username: # ZITADEL_FIRSTINSTANCE_ORG_MACHINE_USERNAME
|
||||
Name: # ZITADEL_FIRSTINSTANCE_ORG_MACHINE_NAME
|
||||
MachineKey:
|
||||
ExpirationDate:
|
||||
Type:
|
||||
# date format: 2023-01-01T00:00:00Z
|
||||
ExpirationDate: # ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINEKEY_EXPIRATIONDATE
|
||||
# Currently, the only supported value is 1 for JSON
|
||||
Type: # ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINEKEY_TYPE
|
||||
Pat:
|
||||
ExpirationDate:
|
||||
# date format: 2023-01-01T00:00:00Z
|
||||
ExpirationDate: # ZITADEL_FIRSTINSTANCE_ORG_MACHINE_PAT_EXPIRATIONDATE
|
||||
|
||||
CorrectCreationDate:
|
||||
FailAfter: 5m
|
||||
FailAfter: 5m # ZITADEL_CORRECTCREATIONDATE_FAILAFTER
|
||||
|
||||
AddEventCreatedAt:
|
||||
BulkAmount: 100
|
||||
BulkAmount: 100 # ZITADEL_ADDEVENTCREATEDAT_BULKAMOUNT
|
||||
|
||||
3
docs/.gitignore
vendored
3
docs/.gitignore
vendored
@ -12,6 +12,9 @@
|
||||
# Generated by docusaurus-plugin-openapi-docs
|
||||
docs/apis/resources
|
||||
|
||||
# Generated markedown from config
|
||||
/uitls/generate_config/node_modules
|
||||
|
||||
# Misc
|
||||
.DS_Store
|
||||
.env.local
|
||||
|
||||
2
docs/docs/apis/proto/.gitignore
vendored
Normal file
2
docs/docs/apis/proto/.gitignore
vendored
Normal file
@ -0,0 +1,2 @@
|
||||
*
|
||||
!.gitignore
|
||||
2
docs/docs/self-hosting/manage/configure/.gitignore
vendored
Normal file
2
docs/docs/self-hosting/manage/configure/.gitignore
vendored
Normal file
@ -0,0 +1,2 @@
|
||||
defaults.yaml
|
||||
steps.yaml
|
||||
@ -4,44 +4,57 @@ title: Configuration Options
|
||||
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem";
|
||||
import LinuxUnix from './_linuxunix.mdx'
|
||||
import Compose from './_compose.mdx'
|
||||
import Helm from './_helm.mdx'
|
||||
|
||||
# Configure ZITADEL
|
||||
import LinuxUnix from "./_linuxunix.mdx";
|
||||
import Compose from "./_compose.mdx";
|
||||
import Helm from "./_helm.mdx";
|
||||
import CodeBlock from "@theme/CodeBlock";
|
||||
import DefaultsYamlSource from "!!raw-loader!./defaults.yaml";
|
||||
import StepsYamlSource from "!!raw-loader!./steps.yaml";
|
||||
|
||||
This guide assumes you are familiar with [running ZITADEL using the least amount of configuration possible](/docs/self-hosting/deploy/overview).
|
||||
|
||||
## Configuration Files
|
||||
## Configuration files
|
||||
|
||||
### Runtime Configuration File
|
||||
### Runtime configuration file
|
||||
|
||||
You can configure the runtime using the `--config` flag of the `zitadel` binary.
|
||||
For a description of all _runtime configuration options_ and their defaults, read the [ZITADEL source code](https://github.com/zitadel/zitadel/blob/main/cmd/defaults.yaml).
|
||||
Also, you can use the environment variables listed in the defaults.yaml.
|
||||
|
||||
### Database Initialization File
|
||||
<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.
|
||||
|
||||
### Multiple Configuration Files
|
||||
<details>
|
||||
<summary>steps.yaml</summary>
|
||||
<CodeBlock language="yaml">{StepsYamlSource}</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
|
||||
## 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`.
|
||||
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
|
||||
### 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.
|
||||
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
|
||||
@ -49,6 +62,7 @@ For more information on the `NO_PROXY` environment variable, read the [`httpprox
|
||||
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`
|
||||
@ -56,29 +70,30 @@ There are three ways to pass the masterkey to the `zitadel` binary:
|
||||
## 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'}
|
||||
]}
|
||||
groupId="installation-target"
|
||||
default="linuxunix"
|
||||
values={[
|
||||
{ label: "Linux and Unix", value: "linuxunix" },
|
||||
{ label: "Docker Compose", value: "compose" },
|
||||
{ label: "Kubernetes (Helm)", value: "k8s" },
|
||||
]}
|
||||
>
|
||||
<TabItem value="linuxunix">
|
||||
<LinuxUnix/>
|
||||
</TabItem>
|
||||
<TabItem value="compose">
|
||||
<Compose/>
|
||||
</TabItem>
|
||||
<TabItem value="k8s">
|
||||
<Helm/>
|
||||
</TabItem>
|
||||
<TabItem value="linuxunix">
|
||||
<LinuxUnix />
|
||||
</TabItem>
|
||||
<TabItem value="compose">
|
||||
<Compose />
|
||||
</TabItem>
|
||||
<TabItem value="k8s">
|
||||
<Helm />
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
Open your favorite internet browser at [http://localhost:8080/ui/console](http://localhost:8080/ui/console).
|
||||
This is the IAM admin users login according to your configuration in the [example-zitadel-init-steps.yaml](./example-zitadel-init-steps.yaml):
|
||||
- **username**: *root@<span></span>zitadel.localhost*
|
||||
- **password**: *RootPassword1!*
|
||||
|
||||
- **username**: _root@<span></span>zitadel.localhost_
|
||||
- **password**: _RootPassword1!_
|
||||
|
||||
## What's next
|
||||
|
||||
@ -90,4 +105,5 @@ This is the IAM admin users login according to your configuration in the [exampl
|
||||
:::caution
|
||||
|
||||
<!-- TODO: Better mark the link in the UI -->
|
||||
|
||||
The ZITADEL management console [requires end-to-end HTTP/2 support](/docs/self-hosting/manage/http2)
|
||||
|
||||
@ -21,6 +21,9 @@ Read more about separating the init and setup phases on the [Updating and Scalin
|
||||
## Configuration
|
||||
|
||||
Read [on the configure page](/docs/self-hosting/manage/configure) about the available options you have to configure ZITADEL.
|
||||
Prefer passing .yaml files to the ZITADEL binary instead of environment variables.
|
||||
Restricting access to these files to avoid leaking sensitive information is easier than restricting access to environment variables.
|
||||
Also, not all configuration options are available as environment variables.
|
||||
|
||||
## Networking
|
||||
|
||||
|
||||
@ -13,9 +13,10 @@
|
||||
"serve": "docusaurus serve",
|
||||
"write-translations": "docusaurus write-translations",
|
||||
"write-heading-ids": "docusaurus write-heading-ids",
|
||||
"generate": "yarn generate:grpc && yarn generate:apidocs",
|
||||
"generate": "yarn generate:grpc && yarn generate:apidocs && yarn generate:configdocs",
|
||||
"generate:grpc": "buf generate ../proto",
|
||||
"generate:apidocs": "docusaurus clean-api-docs all && docusaurus gen-api-docs all"
|
||||
"generate:apidocs": "docusaurus clean-api-docs all && docusaurus gen-api-docs all",
|
||||
"generate:configdocs": "cp -r ../cmd/defaults.yaml ./docs/self-hosting/manage/configure/ && cp -r ../cmd/setup/steps.yaml ./docs/self-hosting/manage/configure/"
|
||||
},
|
||||
"dependencies": {
|
||||
"@algolia/autocomplete-core": "1.5.2",
|
||||
|
||||
@ -11090,6 +11090,11 @@ yaml@1.10.2, yaml@^1.10.0, yaml@^1.10.2, yaml@^1.7.2:
|
||||
resolved "https://registry.yarnpkg.com/yaml/-/yaml-1.10.2.tgz#2301c5ffbf12b467de8da2333a459e29e7920e4b"
|
||||
integrity sha512-r3vXyErRCYJ7wg28yvBY5VSoAF8ZvlcW9/BwUzEtUsjvX/DKs24dIkuwjtuprwJJHsbyUbLApepYTR1BN4uHrg==
|
||||
|
||||
yaml@2.3.1:
|
||||
version "2.3.1"
|
||||
resolved "https://registry.yarnpkg.com/yaml/-/yaml-2.3.1.tgz#02fe0975d23cd441242aa7204e09fc28ac2ac33b"
|
||||
integrity sha512-2eHWfjaoXgTBC2jNM1LRef62VQa0umtvRiDSk6HSzW7RvS5YtkabJrwYLLEKWBc8a5U2PTSCs+dJjUTJdlHsWQ==
|
||||
|
||||
yargs-parser@^18.1.2:
|
||||
version "18.1.3"
|
||||
resolved "https://registry.yarnpkg.com/yargs-parser/-/yargs-parser-18.1.3.tgz#be68c4975c6b2abf469236b0c870362fab09a7b0"
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user