Fork ssb-viewer as custo-viewer
Rebrand package.json (name, homepage, repository) so render.js's page footer, which is built from pkg.homepage + git HEAD, points at this repo rather than upstream's ssb:// URL. Track package-lock.json instead of ignoring it. It was gitignored upstream, but this is a deployed application on a 469MB box running node 18 — a reproducible dependency tree is the difference between RESTORE.md working and not. Upstream's README is kept verbatim as UPSTREAM-README.md; the new one documents the custo data model, including the two things that will otherwise cost someone an afternoon: custodisco is the string "true", and no message ever sets content.channel. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0192zBTNZKZn5svyJ5HTnYds
This commit is contained in:
Claude Opus 5
@@ -1,128 +1,59 @@
|
||||
# ssb-viewer
|
||||
# custo-viewer
|
||||
|
||||
HTTP server for read-only views of SSB content. Serves content as web pages or as scripts for embedding in other web pages.
|
||||
The web view behind **[www.cust.ooo](https://www.cust.ooo)** — a fork of
|
||||
[ssb-viewer](https://gitlab.com/dwynen/ssb-viewer) that renders custo items from a
|
||||
Scuttlebutt pub.
|
||||
|
||||
## Install & Run
|
||||
Upstream's own docs are kept verbatim in [UPSTREAM-README.md](UPSTREAM-README.md).
|
||||
|
||||
Before you install or upgrade ssb-viewer, make sure the plugin is disabled.
|
||||
Otherwise sbot will crash while you install, because it tries to execute half-compiled JS.
|
||||
If you're running the install inside the same docker container as sbot, this will kill your build
|
||||
and leave you in a broken state where sbot doesn't start anymore.
|
||||
## What custo adds
|
||||
|
||||
As a sbot plugin:
|
||||
```sh
|
||||
mkdir -p ~/.ssb/node_modules
|
||||
cd ~/.ssb/node_modules
|
||||
| | |
|
||||
|---|---|
|
||||
| `/items` | One merged grid of every item the pub knows about, across all kiosks. New kiosks appear by being followed — no code change. |
|
||||
| known-blob gate | `serveBlob` only serves blobs referenced by a feed we replicate, so the node never hands out a stranger's cached blob. |
|
||||
| exit on dead sbot | `bin.js` exits when its muxrpc handle dies, instead of holding the port open and hanging every request forever. |
|
||||
| `blob-wanter.js` | Standing `blobs.want` orders for our own feeds' blobs, replacing what `ssb-blobs` `sympathy` used to do before it was turned off. |
|
||||
|
||||
# for a new installation:
|
||||
git clone ssb://%MeCTQrz9uszf9EZoTnKCeFeIedhnKWuB3JHW2l1g9NA=.sha256 ssb-viewer && cd ssb-viewer
|
||||
## The data model
|
||||
|
||||
# for an upgrade:
|
||||
cd ssb-viewer && git pull
|
||||
An **item** is an ordinary `type: "post"` carrying custo's own fields:
|
||||
|
||||
npm install
|
||||
sbot plugins.enable ssb-viewer
|
||||
# restart sbot
|
||||
```
|
||||
|
||||
Or standalone:
|
||||
```sh
|
||||
git clone ssb://%MeCTQrz9uszf9EZoTnKCeFeIedhnKWuB3JHW2l1g9NA=.sha256 ssb-viewer && cd ssb-viewer
|
||||
npm install
|
||||
./bin.js
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
To view a thread as a web page, navigate to a url like `http://localhost:8807/%MSGID`.
|
||||
|
||||
To embed a thread into another web page, load it as follows:
|
||||
|
||||
```html
|
||||
<script src="http://localhost:8807/%MSGID.js"></script>
|
||||
```
|
||||
|
||||
To add more than the base styles, you can also load `http://localhost:8807/static/nicer.css`.
|
||||
|
||||
## Routes
|
||||
|
||||
- `/%msgid`: web page showing a message thread
|
||||
- `/%msgid.js`: script to embed a message thread
|
||||
- `/%msgid.json`: message thread as JSON
|
||||
- `/&feedid`: web page showing a complete feed
|
||||
- `/user-feed/&feedid`: web page showing messages from followed users and channels of a feed
|
||||
- `/channel/#channel`: web page showing messages in a specific channel
|
||||
|
||||
### Query options
|
||||
|
||||
- `noroot`: don't include the root message in the thread
|
||||
- `base=...`: base url for links that ssb-viewer can handle
|
||||
- `msg_base=...`: base url for links to messages
|
||||
- `feed_base=...`: base url for links to feeds
|
||||
- `blob_base=...`: base url for links to blobs
|
||||
- `img_base=...`: base url for embedded blobs (images)
|
||||
- `emoji_base=...`: base url for emoji images
|
||||
|
||||
The `*_base` query options overwrite the defaults set in the config.
|
||||
The `base` option is a fallback instead of specifying the URLs separately.
|
||||
The base options are mostly useful for embedding, where the script is embedded
|
||||
on a different origin than where ssb-viewer is running. However, you may not
|
||||
need them, as the ssb-viewer embed script will detect the base where it is
|
||||
included from.
|
||||
|
||||
## Config
|
||||
|
||||
To change `ssb-viewer`'s default options, edit your `~/.ssb/config`, to have
|
||||
properties like the following:
|
||||
```json
|
||||
{
|
||||
"viewer": {
|
||||
"port": 8807,
|
||||
"host": "::"
|
||||
}
|
||||
}
|
||||
{ "type": "post", "custodisco": "true", "nft": "mint",
|
||||
"text": "\n\n…\n\n a #custodisco item ",
|
||||
"mentions": [{ "name": "photo.jpg", "type": "image/jpeg", "link": "&…sha256" }] }
|
||||
```
|
||||
You can also pass these as command-line options to `./bin.js` or `sbot` as,
|
||||
e.g. `--viewer.port 8807`.
|
||||
|
||||
- `viewer.port`: port for the server to listen on. default: `8807`
|
||||
- `viewer.host`: host address for the server to listen on. default: `::`
|
||||
- `viewer.base`: default base url for links that ssb-viewer can handle
|
||||
- `viewer.msg_base`: base url for links to ssb messages
|
||||
- `viewer.feed_base`: base url for links to ssb feeds
|
||||
- `viewer.blob_base`: base url for links to ssb blobs
|
||||
- `viewer.img_base`: base url for embedded blobs (images)
|
||||
- `viewer.emoji_base`: base url for emoji images
|
||||
- `viewer.require_opt_in`: whether to serve content from feeds that have not published a `publicWebHosting` `about` message. default: `true`
|
||||
- `viewer.disallowRobots`: whether to direct search engines to not index the site. default: `true`
|
||||
A **transfer** of custody is a reply to that message:
|
||||
|
||||
## References
|
||||
```json
|
||||
{ "type": "post", "custodisco": "true", "nft": "give",
|
||||
"target": "@…ed25519", "root": "%…sha256", "branch": "%…sha256" }
|
||||
```
|
||||
|
||||
- Concept: [ssb-porthole][]
|
||||
- UI ideas: [sdash][], [patchbay][]
|
||||
- Server techniques: [ssb-web-server][], [ssb-ws][], [git-ssb-web][]
|
||||
Two things to know before writing a query against this:
|
||||
|
||||
- `custodisco` is the **string** `"true"`, not a boolean.
|
||||
- **No message ever sets `content.channel`.** The `#custodisco` hashtag exists only in
|
||||
post text. Anything keyed on the channel index will silently return nothing — which is
|
||||
why `/channel/custodisco` renders an empty page.
|
||||
|
||||
[ssb-porthole]: %cgkDJXsh6pO5m458B3ngEro+U0qUMGTY1TRGTZOP6lQ=.sha256
|
||||
[patchbay]: %s9mSFATE4RGyJx9wgH22lBrvD4CgUQW4yeguSWWjtqc=.sha256
|
||||
[sdash]: %qrU04j9vfUJKfq1rGZrQ5ihtSfA4ilfY3wLy7xFv0xk=.sha256
|
||||
[git-ssb-web]: %q5d5Du+9WkaSdjc8aJPZm+jMrqgo0tmfR+RcX5ZZ6H4=.sha256
|
||||
[ssb-web-server]: %gYctTCrA06BhAGGvQ6PJ0H2eCCQLj1iEsmfn8SD5+nk=.sha256
|
||||
[ssb-ws]: %tFjo5SoD+Y0SaB5vqZYppmoPmv9LKB5wMPl96qtu4qk=.sha256
|
||||
Messages are published by the kiosks (`/home/trav/custodisco-kiosk/ssb-post.sh`), not by
|
||||
this viewer. The viewer is read-only.
|
||||
|
||||
## License
|
||||
## Running it
|
||||
|
||||
Copyright (c) 2016-2020 Secure Scuttlebutt Consortium
|
||||
`bin.js` connects to a local `ssb-server` and serves on `conf.viewer.port` (8807).
|
||||
See `UPSTREAM-README.md` for the plugin-vs-standalone options.
|
||||
|
||||
This program is free software: you can redistribute it and/or modify
|
||||
it under the terms of the GNU Affero General Public License as
|
||||
published by the Free Software Foundation, either version 3 of the
|
||||
License, or (at your option) any later version.
|
||||
## Deployment
|
||||
|
||||
This program is distributed in the hope that it will be useful,
|
||||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
GNU Affero General Public License for more details.
|
||||
Deployed by rsync from a laptop, not by `git pull` — the server holds no push
|
||||
credentials, and one deploy path is better than two. The script, the systemd units, the
|
||||
nginx config, and the disaster-recovery runbook all live in the ops repo alongside this
|
||||
one (`documents/custo/ssb-viewer`), which is the source of truth for the server itself.
|
||||
|
||||
You should have received a copy of the GNU Affero General Public License
|
||||
along with this program. If not, see <http://www.gnu.org/licenses/>.
|
||||
**Never commit secrets here.** Keys and server config belong in the ops repo.
|
||||
|
||||
AGPL-3.0+, inherited from upstream.
|
||||
|
||||
Reference in New Issue
Block a user