Guide's password advice (openssl rand -base64) produces credentials that break DATABASE_URL #324

New Issue

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

fable-5 commented

2026-08-04 10:49:23 +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).

The guide (docs/self-hosting/README.md, Install step 2) recommends openssl rand -base64 32 for POSTGRES_PASSWORD and COLLAB_TOKEN_SECRET. base64 output regularly contains /, + and =, but the compose file interpolates the password UNESCAPED into a connection URL:

DATABASE_URL: postgresql://dorfteich:${POSTGRES_PASSWORD:?set in .env}@db:5432/dorfteich

A / (and depending on the parser +/=) makes the URL invalid.

Symptom -- and why it misleads: db becomes healthy (Postgres receives the password only as an env variable, no URL involved), while api, collab and backup exit 1 into a restart loop. A healthy database with all database clients dying points the diagnosis in the wrong direction first.

Repro: fill .env per the guide until POSTGRES_PASSWORD contains a / (with -base64 32 almost immediately), docker compose up -d, docker compose ps -> api/collab/backup restarting, db healthy.

Fix outline (from the report):

Docs minimal: recommend URL-safe generation (openssl rand -hex 24) for POSTGRES_PASSWORD in README and .env.example. COLLAB_TOKEN_SECRET never enters a URL, but unify both recommendations for simplicity.
Code, more robust (optional): percent-encode the password where DATABASE_URL is assembled, or use discrete PG* variables instead of a URL -- then arbitrary passwords are valid.
Troubleshooting section: add the symptom line "api/collab/backup restart-looping while db is healthy -> special characters in POSTGRES_PASSWORD break DATABASE_URL".

Reported by Stefan from a manual clean install per docs/self-hosting/README.md (v0.14.0, Docker CE / Compose v2, Debian 13). The guide (docs/self-hosting/README.md, Install step 2) recommends `openssl rand -base64 32` for POSTGRES_PASSWORD and COLLAB_TOKEN_SECRET. base64 output regularly contains `/`, `+` and `=`, but the compose file interpolates the password UNESCAPED into a connection URL: DATABASE_URL: postgresql://dorfteich:${POSTGRES_PASSWORD:?set in .env}@db:5432/dorfteich A `/` (and depending on the parser `+`/`=`) makes the URL invalid. Symptom -- and why it misleads: `db` becomes healthy (Postgres receives the password only as an env variable, no URL involved), while api, collab and backup exit 1 into a restart loop. A healthy database with all database clients dying points the diagnosis in the wrong direction first. Repro: fill .env per the guide until POSTGRES_PASSWORD contains a `/` (with -base64 32 almost immediately), `docker compose up -d`, `docker compose ps` -> api/collab/backup restarting, db healthy. Fix outline (from the report): - Docs minimal: recommend URL-safe generation (`openssl rand -hex 24`) for POSTGRES_PASSWORD in README and .env.example. COLLAB_TOKEN_SECRET never enters a URL, but unify both recommendations for simplicity. - Code, more robust (optional): percent-encode the password where DATABASE_URL is assembled, or use discrete PG* variables instead of a URL -- then arbitrary passwords are valid. - Troubleshooting section: add the symptom line "api/collab/backup restart-looping while db is healthy -> special characters in POSTGRES_PASSWORD break DATABASE_URL".

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.