docs: surface lnbits workspace gotchas as a committed reference
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>
This commit is contained in:
parent
30fbd0cef9
commit
6c9f76bd70
2 changed files with 167 additions and 0 deletions
|
|
@ -202,6 +202,11 @@ lb fix-issue-123 # cd ~/dev/lnbits/fix-issue-123
|
|||
- [`docs/lnbits-upstream-flow.md`](docs/lnbits-upstream-flow.md) —
|
||||
reference for how `lnbits/lnbits` itself moves: `dev` / `main`
|
||||
branch model, squash-merge convention, release tagging.
|
||||
- [`docs/lnbits-workspace-notes.md`](docs/lnbits-workspace-notes.md) —
|
||||
practical gotchas and design constraints for day-to-day lnbits work:
|
||||
port choice, `LNBITS_SRC` build-context traps, the
|
||||
extension-folder-upgrade-wipes-fork issue, Nostr key handling,
|
||||
CLINK protocol scope, fork versioning.
|
||||
|
||||
## Contributing to this scaffold
|
||||
|
||||
|
|
|
|||
Reference in a new issue