Skip to content

Zero-config first run: auto-generate JWT_SECRET and bootstrap admin credentials #109

Description

@cevheri

Part of the distribution-channels epic #108.

Problem

Every native distribution channel (npx, brew, deb/rpm, snap, winget, desktop) fails at install time today because the app refuses to start without preconfigured env vars (JWT_SECRET, ADMIN_PASSWORD). Docker users are used to setting env vars; brew install users are not. This issue is the prerequisite for all other distribution work.

Proposal

When the required auth env vars are absent, fall back to a zero-config first run instead of failing:

  • JWT_SECRET: if unset, generate a cryptographically random secret on first start, persist it in the data directory, and reuse it on subsequent starts.
  • ADMIN_PASSWORD: if unset, either
    • generate a random password on first start and print it once to stdout (Grafana/Jenkins model), or
    • offer a localhost-only mode where auth is relaxed only when the server binds to 127.0.0.1.
  • Explicit env vars always win; existing Docker/Helm behavior must not change when the vars are set.

Design decisions to settle

  • Where the data directory lives per platform (XDG on Linux, ~/Library/Application Support on macOS, %APPDATA% on Windows) and how it interacts with STORAGE_SQLITE_PATH.
  • Whether the localhost no-auth mode is acceptable security-wise, or whether print-once password is the only bootstrap path.

Acceptance criteria

  • Starting the standalone server with zero env vars succeeds and prints clear first-run instructions.
  • Restart reuses the persisted secret (sessions survive restarts).
  • Setting the env vars explicitly bypasses all bootstrap logic (current behavior unchanged).
  • Documented in README and .env.example.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions