71 lines
2.8 KiB
Markdown
71 lines
2.8 KiB
Markdown
# lnbits-extensions — aiolabs catalog manifest
|
|
|
|
A standalone catalog of LNbits extensions we make available across our
|
|
deployments. Just `extensions.json` + this README — no server code.
|
|
|
|
## Why this is its own repo
|
|
|
|
`extensions.json` is a **catalog** (what's available), not a
|
|
**dependency** (what's installed). Keeping it out of the lnbits server
|
|
fork (`aiolabs/lnbits`) means:
|
|
|
|
- The server fork's `main` can be locked-down and slow-moving — only
|
|
real server code goes through PR review.
|
|
- Catalog updates (new versions, new extensions, deprecating an entry)
|
|
happen here on a different cadence and review bar.
|
|
- Hosts pull the catalog at runtime via `LNBITS_EXTENSIONS_MANIFESTS`,
|
|
so promoting a new extension version is a single commit here, not a
|
|
rebuild of every lnbits host.
|
|
|
|
## How hosts consume it
|
|
|
|
Server-deploy sets `services.lnbits.env.LNBITS_EXTENSIONS_MANIFESTS` to
|
|
the raw URL of `extensions.json` on this repo's `main`:
|
|
|
|
```
|
|
https://git.atitlan.io/aiolabs/lnbits-extensions/raw/branch/main/extensions.json
|
|
```
|
|
|
|
LNbits fetches that URL on boot, builds the in-app catalog from it, and
|
|
verifies each downloaded archive against the per-entry `hash` field
|
|
(sha256). That `hash` is the integrity guarantee — without a matching
|
|
sha256, lnbits refuses to install. So even though the manifest itself
|
|
is fetched at runtime, the *artifacts* installed are content-addressed.
|
|
|
|
## How to add or update an entry
|
|
|
|
Each entry has a stable schema (see `extensions.json`); the required
|
|
fields are `id`, `repo`, `name`, `version`, `short_description`,
|
|
`archive`, and `hash`.
|
|
|
|
To add a new extension or version:
|
|
|
|
1. Tag a release in the source extension repo (e.g.
|
|
`git.atitlan.io/aiolabs/<extension>` `v0.0.5`).
|
|
2. Compute the sha256 of the archive:
|
|
```sh
|
|
curl -sL https://git.atitlan.io/aiolabs/<ext>/archive/v0.0.5.zip \
|
|
| sha256sum
|
|
```
|
|
3. Append a new object to `extensions.extensions[]`. Multiple versions
|
|
of the same `id` are allowed — lnbits picks the highest the host's
|
|
`min_lnbits_version` permits.
|
|
4. Commit + push to `main`. Hosts pick up the change on next lnbits
|
|
restart.
|
|
|
|
## Featured extensions
|
|
|
|
`extensions.featured[]` is the array of `id`s shown prominently in the
|
|
lnbits "Manage Extensions" UI. Add an `id` here when an extension is
|
|
considered the canonical choice for a category (e.g. `libra` for
|
|
accounting); remove when superseded.
|
|
|
|
## Why we don't include the lnbits upstream manifest
|
|
|
|
We could chain ours with
|
|
`https://raw.githubusercontent.com/lnbits/lnbits-extensions/main/extensions.json`
|
|
in `LNBITS_EXTENSIONS_MANIFESTS`, but a tight curated catalog is a
|
|
feature, not a limitation, for our deployments — every available
|
|
extension on a host is one we've explicitly vetted. The upstream
|
|
catalog is mirrored at `~/dev/refs/repos/lnbits/lnbits-extensions/` for
|
|
awareness if we want to lift a specific extension.
|