SETUP_ADMIN_PASSWORD minimum length (10) is undocumented; violation crash-loops the api with a raw ZodError #325

New Issue

fable-5 · 2026-08-04T10:49:24+02:00

fable-5 commented

2026-08-04 10:49:24 +02:00

Reported by Stefan from a manual clean install per docs/self-hosting/README.md (v0.14.0, Docker CE / Compose v2, Debian 13).

Pre-seeding (SetupService.preseedFromEnv, apps/api/src/setup/setup.service.ts) validates the admin password via setupAdminInputSchema -- min 10 characters (packages/shared/src/auth.ts:37). Neither docs/self-hosting/README.md nor deploy/compose/.env.example mentions the minimum.

Symptom: with a shorter SETUP_ADMIN_PASSWORD the api crash-loops on start; the log shows only an unhandled stacktrace ending in the i18n key validation.password.tooShort -- which SETUP_* value is meant has to be guessed from the stacktrace.

Repro: complete pre-seeding block in .env but SETUP_ADMIN_PASSWORD < 10 characters, docker compose up -d -> api restart loop with the ZodError.

Fix outline:

Docs: state the minimum in the README's first-run/pre-seeding section and as a comment in .env.example (# min. 10 characters).
Code: catch the validation error in preseedFromEnv and log a clear operator-facing message (e.g. "Pre-seeding failed: SETUP_ADMIN_PASSWORD must be at least 10 characters. Fix .env and recreate the api container."). Failing the boot stays right -- the code comment documents fail-loud as intentional (a half-seeded instance would be harder to diagnose), so keep fail-fast and fix the MESSAGE, rather than falling back to the wizard.
Troubleshooting section: add the symptom line "api restart-looping with ZodError validation.password.tooShort -> SETUP_ADMIN_PASSWORD shorter than 10 characters".

Reported by Stefan from a manual clean install per docs/self-hosting/README.md (v0.14.0, Docker CE / Compose v2, Debian 13). Pre-seeding (SetupService.preseedFromEnv, apps/api/src/setup/setup.service.ts) validates the admin password via setupAdminInputSchema -- min 10 characters (packages/shared/src/auth.ts:37). Neither docs/self-hosting/README.md nor deploy/compose/.env.example mentions the minimum. Symptom: with a shorter SETUP_ADMIN_PASSWORD the api crash-loops on start; the log shows only an unhandled stacktrace ending in the i18n key `validation.password.tooShort` -- which SETUP_* value is meant has to be guessed from the stacktrace. Repro: complete pre-seeding block in .env but SETUP_ADMIN_PASSWORD < 10 characters, `docker compose up -d` -> api restart loop with the ZodError. Fix outline: - Docs: state the minimum in the README's first-run/pre-seeding section and as a comment in .env.example (`# min. 10 characters`). - Code: catch the validation error in preseedFromEnv and log a clear operator-facing message (e.g. "Pre-seeding failed: SETUP_ADMIN_PASSWORD must be at least 10 characters. Fix .env and recreate the api container."). Failing the boot stays right -- the code comment documents fail-loud as intentional (a half-seeded instance would be harder to diagnose), so keep fail-fast and fix the MESSAGE, rather than falling back to the wizard. - Troubleshooting section: add the symptom line "api restart-looping with ZodError validation.password.tooShort -> SETUP_ADMIN_PASSWORD shorter than 10 characters".

fable-5 referenced this issue from a commit

2026-08-04 11:25:48 +02:00

Self-hosting findings: URL-safe password advice, operator-readable pre-seed errors (#324, #325)

fable-5 referenced a pull request that will close this issue

2026-08-04 11:26:00 +02:00

Self-hosting findings: URL-safe password advice, operator-readable pre-seed errors (#324, #325) #328

fable-5 referenced this issue from a commit

2026-08-04 12:44:18 +02:00

Self-hosting findings: URL-safe password advice, operator-readable pre-seed errors (#324, #325)

fable-5 closed this issue

2026-08-04 13:06:15 +02:00

Sign in to join this conversation.