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

fable-5 · 2026-08-04T11:26:00+02:00

fable-5 commented

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

Closes #324. Closes #325.

Both findings from Stefan's manual clean install per the guide (v0.14.0, Debian 13), both ending in restart loops that were hard to diagnose:

#324 (docs only): guide + .env.example now recommend openssl rand -hex 24 for POSTGRES_PASSWORD and COLLAB_TOKEN_SECRET and explain the URL interpolation; Troubleshooting gained the "db healthy, clients restart-looping" symptom line.
#325 (docs + api): the 10-character minimum for SETUP_ADMIN_PASSWORD is now documented (guide first-run section + .env.example), and preseedFromEnv translates validation failures into operator terms naming the SETUP_* variable. Fail-fast stays — the code documents it as deliberate (no half-seeded instance); only the MESSAGE changed. New test pins the message and that nothing is half-seeded afterwards.

Local evidence: setup suite 11/11 green (incl. new case); api full suite against fresh DB 599 passed / 0 failed; typecheck + lint green.

Independent of the #326/#327 chain (no shared files).

🤖 Generated with Claude Code

https://claude.ai/code/session_017aviRTgWCcAHUh1SBoxf6P

Closes #324. Closes #325. Both findings from Stefan's manual clean install per the guide (v0.14.0, Debian 13), both ending in restart loops that were hard to diagnose: - #324 (docs only): guide + .env.example now recommend `openssl rand -hex 24` for POSTGRES_PASSWORD and COLLAB_TOKEN_SECRET and explain the URL interpolation; Troubleshooting gained the "db healthy, clients restart-looping" symptom line. - #325 (docs + api): the 10-character minimum for SETUP_ADMIN_PASSWORD is now documented (guide first-run section + .env.example), and preseedFromEnv translates validation failures into operator terms naming the SETUP_* variable. Fail-fast stays — the code documents it as deliberate (no half-seeded instance); only the MESSAGE changed. New test pins the message and that nothing is half-seeded afterwards. Local evidence: setup suite 11/11 green (incl. new case); api full suite against fresh DB 599 passed / 0 failed; typecheck + lint green. Independent of the #326/#327 chain (no shared files). 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_017aviRTgWCcAHUh1SBoxf6P

fable-5 added 1 commit 2026-08-04 11:26:01 +02:00

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

CI / Lint, typecheck, test (pull_request) Successful in 7m16s

Details

CI / Build container images (pull_request) Successful in 2m59s

Details

CI / Auth e2e pack (pull_request) Successful in 9m0s

Details

CI / Import/export fidelity gate (pull_request) Successful in 1m2s

Details

06b54747f1

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

fable-5 force-pushed 324-325-self-hosting-guide-findings from 06b54747f1 to 20677ea247

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

Compare

fable-5 merged commit 20677ea247 into main

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

Sign in to join this conversation.

No reviewers