From 437a0802bd5b62d91aacf114be199275f313ecc9 Mon Sep 17 00:00:00 2001 From: Florian Forster Date: Fri, 17 Jul 2026 13:36:51 +0200 Subject: [PATCH] docs: document initial admin password requirements in compose guide (#12452) # Which Problems Are Solved - The **Harden secrets** section of the Docker Compose guide lists commands for the masterkey and the two database passwords, but never mentions the **initial admin user password**. - Setting `ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD` to a value that does not meet the default password complexity policy fails the initial setup with a `_password_complexity_model` error, and the requirements were not documented anywhere near the other secrets. # How the Problems Are Solved - Adds a short note directly below the secret-generation commands documenting the initial admin password: the default (`Password1!` / `zitadel-admin@zitadel.localhost`), how to override it via `ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD`, and the default complexity requirements (min 8 chars, upper + lower + number + symbol). - Links to the [Password Complexity](/guides/manage/console/default-settings#password-complexity) policy docs and notes that the variable only applies during initial setup. # Additional Changes None. # Additional Context - Reported by a self-hosting user (TrueNAS + Ansible) who hit repeated setup errors because the initial admin password complexity requirement was not documented alongside the masterkey/DB password commands. --- apps/docs/content/self-hosting/deploy/compose.mdx | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/apps/docs/content/self-hosting/deploy/compose.mdx b/apps/docs/content/self-hosting/deploy/compose.mdx index 4f091286e..565869746 100644 --- a/apps/docs/content/self-hosting/deploy/compose.mdx +++ b/apps/docs/content/self-hosting/deploy/compose.mdx @@ -93,6 +93,16 @@ echo "POSTGRES_ADMIN_PASSWORD=$(tr -dc A-Za-z0-9 > echo "POSTGRES_ZITADEL_PASSWORD=$(tr -dc A-Za-z0-9 > .env ``` +The commands above cover the masterkey and the database passwords. The **initial admin user** (`zitadel-admin`) has a password too, defaulting to `Password1!`. To set your own before the first start, add it to `.env`: + +```dotenv +ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD=MyInitialPassw0rd! +``` + + +The initial admin password must satisfy the default [password complexity policy](/guides/manage/console/default-settings#password-complexity): at least 8 characters, including an uppercase letter, a lowercase letter, a number, and a symbol. A password that doesn't meet these requirements causes the initial setup to fail with a password complexity error. Like all `ZITADEL_FIRSTINSTANCE_*` variables, it is only applied during the first start; change it later from the Console. + + ### External URL settings These three settings **must match your public endpoint exactly**: