Two findings from Stefan's manual clean install per the guide, both
ending in an api restart loop that was hard to diagnose:
- #324: the guide recommended `openssl rand -base64 32` for
POSTGRES_PASSWORD, but the compose interpolates the password unescaped
into DATABASE_URL — base64's `/`, `+`, `=` break the URL. Misleadingly,
db stays healthy (it gets the password as a plain env var) while
api/collab/backup crash. Guide and .env.example now recommend
`openssl rand -hex 24` for both secrets and say why; Troubleshooting
gained the symptom line.
- #325: SETUP_ADMIN_PASSWORD's minimum (10 chars,
packages/shared/src/auth.ts) was undocumented, and a violation crashed
the boot with a raw ZodError naming schema fields and i18n keys.
Failing the boot stays — deliberately, no half-seeded instance — but
preseedFromEnv now translates validation errors into operator terms
("Pre-seeding failed: SETUP_ADMIN_PASSWORD must be at least 10
characters. Fix .env and recreate the api container."). Documented in
the guide's first-run section, .env.example, and Troubleshooting; new
test pins the message and that nothing is half-seeded afterwards.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017aviRTgWCcAHUh1SBoxf6P
