Initial catalog migrated from aiolabs/lnbits:main extensions.json

README.md

@@ -0,0 +1,71 @@
+# 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.