From 25f5b754611731cbc123dffbc050384d741f4766 Mon Sep 17 00:00:00 2001 From: Melvin Carvalho Date: Mon, 18 May 2026 07:00:09 +0200 Subject: [PATCH] docs: add features/app-install page for jss install MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Covers Phases 1+2+4+6 of JSS#464 — bare name / org/repo / URL / refs / renames, bearer + NIP-98 auth, --pod targeting, --bundle (with the JSON-LD shape + the solid-apps/bundles repo), how it works under the hood, and a troubleshooting table. Sidebar entry added under Features, next to git-integration. Fixes #19 --- docs/features/app-install.md | 199 +++++++++++++++++++++++++++++++++++ sidebars.ts | 1 + 2 files changed, 200 insertions(+) create mode 100644 docs/features/app-install.md diff --git a/docs/features/app-install.md b/docs/features/app-install.md new file mode 100644 index 0000000..0b8fd47 --- /dev/null +++ b/docs/features/app-install.md @@ -0,0 +1,199 @@ +--- +sidebar_position: 14 +title: Installing Apps +description: Install Solid apps into your pod with one command — jss install +--- + +# Installing Apps + +JSS ships a built-in `install` subcommand that pulls a Solid app from a git repo and pushes it into your running pod at `/public/apps//`. One command, no clone-and-push dance, no token plumbing — the hard parts (git auto-init, ACL-gated push, working-tree extraction via `updateInstead`) are handled by the same git HTTP backend JSS already uses. + +## Quick start + +```bash +jss start --provision-keys & # pod running on http://localhost:4443 +jss install chrome # installs solid-apps/chrome → /public/apps/chrome/ +``` + +Open `http://localhost:4443/public/apps/chrome/` in a browser. That's it. + +## App specs + +The argument to `install` accepts five forms: + +| Input | Resolves to | Pod path | +|---|---|---| +| `chrome` | `github.com/solid-apps/chrome` (default registry) | `/public/apps/chrome/` | +| `JavaScriptSolidServer/git` | `github.com/JavaScriptSolidServer/git` | `/public/apps/git/` | +| `https://github.com/foo/bar` | as-is | `/public/apps/bar/` | +| `chrome#v1` | `github.com/solid-apps/chrome` at ref `v1` | `/public/apps/chrome/` | +| `litecut/litecut.github.io=litecut` | `github.com/litecut/litecut.github.io`, renamed | `/public/apps/litecut/` | + +Two optional suffixes apply to any form: + +- **`#`** — pin a ref. Uses `git clone --branch ` under the hood. +- **`=`** — override the pod-path name. Useful when the repo's last segment isn't what you want under `/public/apps/`. + +Multiple specs in one command: + +```bash +jss install chrome vellum pdf hub +``` + +Each is installed independently; per-app `✓` / `⊘` / `✗` status, exit non-zero if any failed. + +## Authentication + +The install needs write access on the target pod. Two paths: + +### Bearer token (default) + +```bash +jss install chrome --user me --password me +# or via env (keeps the secret out of shell history): +JSS_SINGLE_USER_PASSWORD=secret jss install chrome +``` + +`POST /idp/credentials` returns a token, which is sent as `Authorization: Bearer ...` on each push. + +If the pod runs in `--public` mode (no IDP), no token is fetched; writes are unauthenticated. + +### Nostr (NIP-98) + +```bash +jss install chrome --nostr-privkey <64-hex> +# or via env: +NOSTR_PRIVKEY=<64-hex> jss install chrome +``` + +Each push is signed with a NIP-98 event (Schnorr signature on a `kind: 27235` Nostr event). JSS verifies the signature, derives a `did:nostr:` identity, and runs WAC against that. + +Pairs naturally with `--provision-keys`: the privkey JSS auto-generates at `/private/privkey.jsonld` is the natural source. + +```bash +jss start --provision-keys & +PRIVKEY=$(jq -r .secretKeyMultibase pod-data/private/privkey.jsonld | sed 's/^f8126//') +NOSTR_PRIVKEY=$PRIVKEY jss install chrome +``` + +ACL on the target path must grant the corresponding pubkey: + +```turtle +<#owner> a acl:Authorization; + acl:agent ; + acl:accessTo <./>; + acl:default <./>; + acl:mode acl:Read, acl:Write, acl:Control. +``` + +This is typically already true on a `--provision-keys` pod — JSS seeds the owner ACL to grant the provisioned key. + +## Targeting a different pod + +```bash +jss install chrome --pod http://192.168.1.10:5544 +``` + +Default is `http://localhost:4443`. Auth flags apply against the chosen pod. + +## Bundles + +`--bundle ` installs a set of apps from a JSON-LD manifest. Same auth, same target, same per-app status. + +```bash +jss install --bundle starter # solid-apps/bundles/HEAD/starter.jsonld +jss install --bundle media chrome # bundle + ad-hoc additions +jss install --bundle ./my-stack.jsonld # local file +jss install --bundle https://my.pod/bundles/dev.jsonld +``` + +### Source resolution + +| Input | Resolves to | +|---|---| +| `--bundle starter` | `https://raw.githubusercontent.com/solid-apps/bundles/HEAD/starter.jsonld` | +| `--bundle /` | `https://raw.githubusercontent.com///HEAD/bundle.jsonld` | +| `--bundle https://...` | fetch as-is | +| `--bundle ./path.jsonld` | local filesystem (absolute paths supported) | + +`/HEAD/` resolves to the repo's default branch — works for both `gh-pages`-default repos (solid-apps convention) and `main`-default repos. + +### Bundle format + +JSON-LD `schema:ItemList`: + +```json +{ + "@context": { "schema": "https://schema.org/", "app": "urn:jss:app:" }, + "@id": "#bundle", + "@type": "schema:ItemList", + "schema:name": "Starter", + "schema:description": "Minimal pleasant first-run set", + "schema:itemListElement": [ + "chrome", + "vellum", + { "app:spec": "litecut/litecut.github.io=litecut", "app:label": "Litecut" } + ] +} +``` + +Each item is either: + +- A **bare string** — any spec `jss install` accepts +- An **object** — required `app:spec`, optional `app:label` / `app:description` for UI tooling + +### Curated bundles + +The [`solid-apps/bundles`](https://github.com/solid-apps/bundles) repo hosts ready-made bundles: + +| Bundle | Apps | +|---|---| +| `starter` | chrome, vellum, pdf, alarm | +| `all` | chrome, vellum, win98, pdf, hub, alarm, playlist | +| `media` | playlist, pdf | +| `productivity` | vellum, hub, win98 | + +```bash +jss install --bundle starter +``` + +### Sharing custom bundles + +Bundles are JSON-LD documents — they live anywhere a JSON-LD doc can. Host yours on your pod, in a GitHub repo, or any static server: + +```bash +jss install --bundle https://my.pod/bundles/dev-stack.jsonld +``` + +ACL-gated, version-controlled (if in git), pointable from a single URL. The Linux-distribution analogy is apt: `apt install task-server` becomes `jss install --bundle task-server`, but the manifests are sharable Solid resources instead of fixed-path config files. + +## How it works + +Under the hood, `jss install ` is: + +1. **Resolve** the spec to a source URL (`github.com/solid-apps/chrome` for bare names). +2. **Authenticate.** Fetch a bearer token from `/idp/credentials`, OR build a NIP-98 signed event if `--nostr-privkey` is set. Skipped entirely if the pod is in `--public` mode. +3. **Clone** the repo to a temp directory. Full clone — no `--depth`, because shallow pushes are rejected by `git-receive-pack`. +4. **Dual push** to `/public/apps/` on both `HEAD:main` and `HEAD:gh-pages`. JSS auto-inits the destination repo, and whichever ref matches the server-side HEAD triggers `receive.denyCurrentBranch updateInstead` to extract the working tree onto disk where JSS serves it as static resources. The other ref is a harmless stranded reference. +5. **Clean up** the temp directory. + +Idempotent on re-run. Skip-on-existing-non-repo paths (e.g. jspod's bundled `pilot`) report a friendly `⊘ skipped` instead of an error. + +## Troubleshooting + +| Symptom | Cause | Fix | +|---|---|---| +| `✗ : invalid app name "..."` | Spec doesn't match `/^[a-z0-9][a-z0-9_.-]*$/i` (bare-name form) or `/` | Check the spec; review the [App specs](#app-specs) table | +| `✗ : clone failed: Repository not found` | The repo doesn't exist at the resolved URL | Verify the source — `github.com/solid-apps/` for bare names | +| `✗ : push failed: shallow update not allowed` | Shouldn't happen with this tool — but the symptom on a manual clone-and-push is using `--depth=1` | Remove `--depth` from the clone | +| `✗ : push failed: HTTP 401` | Auth failed | Check `--user` / `--password`; for Nostr, check that the ACL grants the pubkey | +| `✗ : push failed: HTTP 413` | Body exceeds JSS's `bodyLimit` (10 MB) | Tracked as [JSS#474](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/issues/474). Workaround: install a smaller repo or push a no-history snapshot | +| Working tree empty after push (`/public/apps//index.html` returns 404) | Server-side HEAD doesn't match the pushed branch | JSS 0.0.197+ pins `-b main` on auto-init; upgrade if you see this | +| `⊘ : skipped (path already in use)` | The target path has content but no `.git/` (e.g. jspod's bundled `pilot`) | Expected — JSS refuses to clobber non-repo content | + +## See also + +- [Git Integration](./git-integration.md) — the substrate that powers `install` +- [`jss install --help`](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/blob/gh-pages/src/cli/install.js) — the source +- [solid-apps/bundles](https://github.com/solid-apps/bundles) — curated bundle repo +- [Phased plan (JSS#464)](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/issues/464) — the design roadmap; Phases 3 (`--did`) and 5 (curated no-arg default) still ahead diff --git a/sidebars.ts b/sidebars.ts index 7f24be2..a1d6395 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -41,6 +41,7 @@ const sidebars: SidebarsConfig = { 'features/live-reload', 'features/mashlib-ui', 'features/git-integration', + 'features/app-install', 'features/activitypub', 'features/nostr', 'features/e2ee',