LNbits has two sources of truth for settings depending on lifecycle.
The trap: on first boot, .env seeds the DB; on every subsequent boot,
the DB row overwrites the in-memory Settings. Editing .env after the
first boot is a no-op for editable fields — they can only change via
the Admin UI or by clearing rows in system_settings.
Documented:
- the boot-time read-DB → seed-from-env → overwrite-cached-Settings
sequence with file:line references for verification
- exceptions where env still wins (super_user, lnbits_admin_ui=False,
the full ReadOnlySettings field list)
- LNBITS_FIRST_INSTALL_TOKEN rotation does NOT reset settings to env
(it's an admin-recovery escape hatch, not a config-refresh)
- the deploy-side implication: declarative env vars are a *seed*
for EditableSettings, authoritative for ReadOnlySettings — plan
your deploy story accordingly
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
New docs/lnbits-workspace-notes.md collects the day-to-day gotchas
that have repeatedly surprised people doing lnbits dev work — content
that lives in personal CLAUDE.md / memory notes elsewhere but is
genuinely useful as a public reference once stripped of identity.
Sections:
- pick a non-default port (5000 collides with macOS AirPlay etc.)
- LNBITS_SRC + docker-compose build context (commits don't reach
the dev image if the build context points at a stale worktree;
`docker compose config | grep -A2 lnbits` to verify)
- extension folder mounted as install target: clicking "Upgrade"
in the LNbits UI extracts the catalog tarball over the mounted
fork checkout, wiping .git
- Nostr key handling: upstream stores user nsecs plaintext in
accounts.prvkey; signer-abstraction shape (LocalSigner with
envelope-encrypted blob / RemoteBunkerSigner via NIP-46 /
ClientSideOnlySigner) with the "prefer don't-store-the-key"
principle
- CLINK protocol scope: Shocknet's 21001-21003 event kinds are
Lightning.Pub-specific; LNbits has zero CLINK knowledge; how
to think about cross-system designs without conflating them
- fork versioning: v<upstream>-<tag>.<N> + the PEP 440
`+<tag>.<N>` package-version form for pyproject.toml
- codebase reading tips (key paths, --first-parent log reading)
Linked from README "Further reading". No personal identity in the
new doc — scrubbed of aiolabs/atitlan/bohm/etc references.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
