Skip to content

Auto-generate session secret; make SESSION_SECRET optional - #11

Merged
Lucifix merged 1 commit into
mainfrom
feature/auto-session-secret
Sep 15, 2026
Merged

Lucifix merged 1 commit into
mainfrom
feature/auto-session-secret

Conversation

@Lucifix

@Lucifix Lucifix commented Sep 15, 2026

Copy link
Copy Markdown
Owner

What does this change?

SESSION_SECRET is no longer required. When it's unset, a random 32-byte key is generated on first boot into $DATA_DIR/session-secret (/data/session-secret in Docker, mode 0600) and reused on every later boot. This removes the one mandatory setup step, so a bare docker run / compose paste works out of the box — the same approach most self-hosted apps take.

  • New app/lib/sessionSecret.server.ts resolves the key: SESSION_SECRET env → existing file → generate + persist.
  • server/app.ts no longer exits when SESSION_SECRET is missing.
  • docker-compose.yml uses ${SESSION_SECRET:-} instead of :? (required).
  • README, .env.example, AGENTS.md updated to describe the variable as optional.

Reviewer notes

  • Backward compatible: if SESSION_SECRET is set, it wins, so existing deployments keep their current sessions after upgrading.
  • The file lives in the data dir but outside database/ and uploads/, which are the only paths a backup restore swaps — restoring doesn't sign the user out.
  • Losing the file only costs one re-login; deleting it + restarting is documented as the "sign out everywhere" option.
  • An empty env value (from compose's :- default) or an empty file is treated as unset, never used as the key.
  • The generated key only persists if /data is a volume — already the documented setup.

Related issue

None.

Checklist

  • Ran npm run lint:fix and npm run fmt at the repo root
  • Added/updated backend tests for behavior changes (app/lib/sessionSecret.test.ts)
  • npm run typecheck and npm run build pass
  • Followed existing conventions (Zod validation, CatalogProvider pattern
    for new data sources, comments explain why not what)

Also verified manually: a production build booted with no SESSION_SECRET generated the key file (-rw-------) and served /api/auth/me{"authenticated":false,"needsSetup":true}.

Screenshots

N/A — no UI change.

Requiring users to generate and pass a SESSION_SECRET made the Docker setup
harder than it needs to be. The key is now generated on first boot into
$DATA_DIR/session-secret (0600) and reused afterwards; SESSION_SECRET still
takes precedence so existing deployments keep their sessions.
@Lucifix
Lucifix merged commit 0c9c2f0 into main Sep 15, 2026
6 checks passed
@Lucifix
Lucifix deleted the feature/auto-session-secret branch September 15, 2026 18:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant