@@ -21,7 +21,15 @@ page's links point at `/`.
2121
2222## Install
2323
24−From the repo root, with your ship running:
24+Build the desk with Nix. `result` is then the desk folder:
25+
26+```sh
27+nix build github:iko-soy/shelf
28+```
29+
30+From a checkout, `nix build` does the same, or you can use `desk/` directly.
31+
32+Then, with your ship running:
2533
2634```
2735~sampel-palnet:dojo> |new-desk %shelf
@@ -29,7 +37,8 @@ From the repo root, with your ship running:
2937```
3038
3139```sh
32−cp -R desk/* /path/to/pier/shelf/
40+cp -R result/* /path/to/pier/shelf/
41+chmod -R u+w /path/to/pier/shelf # files from the Nix store are read-only
3342```
3443
3544```
@@ -37,15 +46,16 @@ cp -R desk/* /path/to/pier/shelf/
3746~sampel-palnet:dojo> |install our %shelf
3847```
3948
40−The page is now at `https://<your-ship>/shelf`. It is meant to be opened
41−through your own domain, though: on the ship's address the page renders, but
42−its links lead to `/`, which belongs to Landscape.
49+The page is now at `https://<your-ship>/shelf`, and Landscape shows a Shelf
50+tile that opens it. It is meant to be opened through your own domain, though:
51+on the ship's address the page renders, but its links lead to `/`, which
52+belongs to Landscape.
4353
4454## Update
4555
46−Copy `desk/*` into the mount again and run `|commit %shelf`. Then check that
47−`.^(cass:clay %cw /=shelf=)` moved: if the new version doesn't build, Clay
48−keeps the old one and logs nothing.
56+Build and copy the desk into the mount again, as above, and run
57+`|commit %shelf`. Then check that `.^(cass:clay %cw /=shelf=)` moved: if the
58+new version doesn't build, Clay keeps the old one and logs nothing.
4959
5060%shelf is installed from your own ship, so it gets no over-the-air updates.
5161After a kernel upgrade, Clay holds it until `desk/sys.kelvin` lists the new
@@ -65,6 +75,9 @@ before you can publish it.
6575 `:treaty|remove-desk ~other-ship %app`, and stop following with
6676 `:treaty|unally ~other-ship`.
6777
78+%shelf has a docket of its own, so `:treaty|publish %shelf` lists it on its
79+own page, where others can install it.
80+
6881A republished app appears once your ship has received its docket from the
6982publisher, which happens a few seconds after you ally them. Apps are sorted by
7083title. %shelf reads the alliance on every request, but browsers may show a
@@ -206,8 +219,10 @@ after %shelf stops. Until you remove it, `/shelf` answers 503 at once.
2062191. Remove the site from your reverse proxy first. Otherwise visitors get that
207220 503 page, or, once the binding is gone, an endless redirect loop between
208221 Landscape's login page and `/`.
209−2. `|uninstall %shelf`. Your `head`/`body` HTML is kept, and installing again
210− brings the page straight back.
222+2. `:docket|uninstall %shelf`, or Uninstall from the tile's menu in
223+ Landscape. This removes the tile and suspends the agent; a plain
224+ `|uninstall %shelf` would leave a suspended tile behind. Your `head`/`body`
225+ HTML is kept, and `|install our %shelf` brings the page straight back.
2112263. To delete that state too: `|nuke %shelf, =desk &` (answer `y`).
2122274. Optionally, free the path. Only the binding's owner can remove it, so take
213228 it over from the dojo, then remove it:
@@ -226,13 +241,16 @@ The desk is self-contained. `desk/` holds everything Clay needs:
226241
227242| Path | What |
228243|---|---|
244+| `desk.docket-0` | What Landscape shows: title, description, color, version, website, license |
229245| `app/shelf.hoon` | The agent: Eyre binding, routing, scries, responses |
230246| `lib/shelf.hoon` | Pure helpers and the page (Sail) |
231247| `sur/shelf.hoon`, `mar/shelf/action.hoon`, `gen/shelf/` | The `head`/`body` settings |
232248| `web/shelf.css`, `web/copy.js` | Inlined into the page at build time with `/*` |
233249| `tests/lib/shelf.hoon` | Unit tests, including the rendered page |
234250| `lib/sigil.hoon`, `lib/sigil/symbols.hoon` | Vendored [sigil renderer](https://github.com/Fang-/suite) (MIT, ~paldev; shapes from `@urbit/sigil-js`, MIT, Tlon) |
235−| other `lib/`, `mar/`, `sur/` files | Copied unmodified from `%base` (urbit/urbit `5a187fe`) and `%landscape` (`sur/treaty`, `sur/docket`; tloncorp/landscape `46c6ed8`) |
251+| other `lib/`, `mar/`, `sur/` files | Copied unmodified from `%base` (urbit/urbit `5a187fe`) and `%landscape` (`sur/treaty`, `sur/docket`, `lib/docket`, `mar/docket-0`; tloncorp/landscape `46c6ed8`) |
252+
253+`flake.nix` makes `nix build` produce the desk as `result`.
236254
237255Run the tests on a ship with the desk installed:
238256
@@ -254,3 +272,10 @@ Some details that are easy to get wrong:
254272- **Clay can refuse a commit silently.** It refuses commits that would stop a
255273 running agent from building, and logs nothing. After `|commit`, check that
256274 `.^(cass:clay %cw /=shelf=)` moved.
275+
276+## License
277+
278+MIT; see [LICENSE](LICENSE). The vendored files keep their own notices:
279+`lib/sigil.hoon` and `lib/sigil/symbols.hoon` are MIT (Fang; shapes from
280+`@urbit/sigil-js`, Tlon), and the files from `%base` and `%landscape` come
281+from urbit/urbit (MIT) and tloncorp/landscape.