path: root/README.md

# patchfoo

> 扒扯福 <páchěfú>, the fortune of raked-together chatter

Plain SSB web UI. Uses HTML forms instead of client-side JS. Designed for use on low-power and low-resource computers.

## Goals

- Support all message schemas commonly used in the main SSB network.
- Make efficient use of screen space, memory, and CPU.
- Run well in [dillo](http://dillo.org/) browser.
- Serve as a place for experimenting with new HTML-based SSB UIs.

## Features

- Render messages with author name and icons.
- Render core ssb message types, git-ssb message types, and raw messages.
- View public log, private log, user feeds, channels, and search.
- Paginate views bidirectionally.
- Compose, preview and publish public and private messages.
- *and more*

## Joining SSB with Patchfoo

Note: these guides may or may not be updated for using the binary installer, which may be an easier way to install patchfoo. (See the Install section below.)

Find [this guide](%VaSj08AbdhIa4itK4z8Z91G80o2h5OhRLCEEO6MhAcU=.sha256) [on github](https://github.com/noffle/sailing-patchfoo) or [on
SSB](http://git.scuttlebot.io/%25VaSj08AbdhIa4itK4z8Z91G80o2h5OhRLCEEO6MhAcU%3D.sha256).

## Requirements

- [ssb-server][] (may be bundled in Patchwork, Patchbay or Oasis)

For development and installing from source:

- Node.js
- [ssb-npm][] ≥ [v2.0.4](%aiHW6ONQvfcCoj+I5PVWlwumjHaOUhLjnuMBBy4RXfY=.sha256)
- [git-ssb][]

Recommended ssb-server plugins (see "Install extras" below):

- ssb-backlinks
- ssb-private
- ssb-search

### Note about Node v12

If you are installing patchfoo from source or ssb-npm with Node v12 or later, after the installation process you may need to separately install sodium-native v3. Some of patchfoo's dependencies still depend on sodium-native v2 which does not work easily with Node v12. sodium-native v2 can be swapped with v3 without any problem. More info in this thread: %VPeffQAd5jva0VwOVnttfGDPDrLGxxSsIpea3Z1GncI=.sha256

## Install

**Easy install: use the binary installer below.**

patchfoo can run either as a standalone process or as an ssb-server plugin.

Running as a ssb-server plugin is faster and uses less resources. But it requires you to run ssb-server from the command-line, or use a ssb-server distribution that allows installing ssb-server plugins.

Running as a standalone process should work while you are running a ssb-server distribution such as Patchwork, Patchbay, or Oasis. It also could potentially work with ssb-server implementations other than the Node.js one.

The binary installer installs patchfoo to run as a standalone process. It bundles Node.js so you don't need to have node/npm installed. You still need a ssb-server running though. You also need a connection to the main SSB network for the installation script to fetch the necessary blobs.

### Binary install

This installs a single executable file "patchfoo" on your system, with an embedded Node.js.

Install patchfoo v1.5.1 binary for linux-{x64,armv7,arm64,x86} or macos-x64:

```sh
curl 'http://localhost:8989/blobs/get/&qmhp9n9eM4GMk4nm9XmCuXzgsJTeQbNhVHRUjgDYs4w=.sha256' | sh
```

[Licenses for git-ssb v1.5.1 binary release](&MIPxJWgw33j7u9CvIOUxbPlkzw3UF0LjOePlLUxVY8s=.sha256)

### Install from source

#### as a standalone process

This is how to install patchfoo using git-ssb and ssb-npm and run it as a standalone process with a local ssb-server.

Running as a standalone process this way is useful if you can use git-ssb and ssb-npm and are either just trying out patchfoo, or want to continue using a ssb-server distribution that doesn't allow installing ssb-server plugins, or want to develop patchfoo and not have to frequently restart ssb-server.

```sh
git clone ssb://%YAg1hicat+2GELjE2QJzDwlAWcx0ML+1sXEdsWwvdt8=.sha256 patchfoo
cd patchfoo
ssb-npm install \
  --branch %e/unnFWjNwhJuFtH+DmkNqqvVggrufu/sZxRU5e59Is=.sha256 \
  --branch %FlwIBeDR/liKcEvok7uF9o3e7Qib36aMj1orj3aiFVQ=.sha256
npm start
```

#### as a ssb-server plugin

This is the traditional way to install and run patchfoo.

Using `--production` skips installing `ssb-client`, which is not needed for plugin usage. If you want to also be able to run patchfoo as a standalone process, omit the `--production` option in the commands below, and add the extra `--branch` parameter as used above.

```sh
cd ~/.ssb/node_modules
git clone ssb://%YAg1hicat+2GELjE2QJzDwlAWcx0ML+1sXEdsWwvdt8=.sha256 patchfoo
cd patchfoo
ssb-npm install --production --branch %e/unnFWjNwhJuFtH+DmkNqqvVggrufu/sZxRU5e59Is=.sha256
node enable-plugin.js
```

### Install via ssb-npm

patchfoo sometimes has releases published on ssb-npm.

To install packages globally with [ssb-]npm, you need a npm prefix set. That is a directory that npm packages will get installed to when do a global (`-g`) install. If you don't already have a npm prefix set, I recommend using `~/.local`:
```sh
npm config set prefix ~/.local
```
The `bin` directory under the prefix should also be in your `$PATH`. On some GNU/Linux systems, `~/.profile` automatically adds `~/.local/bin` to `$PATH` if that exists as a directory. Otherwise, you should edit your `~/.profile` or similar file to add the npm prefix's `bin` directory to `$PATH`:
```sh
PATH="$HOME/.local/bin:$PATH
```

### as a standalone process

This installs patchfoo globally and gives you a `patchfoo` executable.

Note: if you previously installed a patchfoo binary release, [ssb-]npm will not overwrite it. You must manually remove it (e.g. `rm ~/.local/bin/patchfoo`) before installing via ssb-npm.

```sh
ssb-npm install -g patchfoo \
  --branch %e/unnFWjNwhJuFtH+DmkNqqvVggrufu/sZxRU5e59Is=.sha256 \
  --branch %FlwIBeDR/liKcEvok7uF9o3e7Qib36aMj1orj3aiFVQ=.sha256
```

### as a ssb-server plugin

This does a global ssb-npm install and then symlinks it into place and installs it with ssb-server as a plugin.

```sh
ssb-npm install -g patchfoo --branch %e/unnFWjNwhJuFtH+DmkNqqvVggrufu/sZxRU5e59Is=.sha256
dir=$(dirname $(realpath $(which patchfoo)))
ln -s "$dir" ~/.ssb/node_modules/
node "$dir/enable-plugin.js"
```

## Install extras

To most effectively render things, patchfoo needs the `ssb-backlinks`
and `ssb-private` ssb-server plugins. The `ssb-search` plugin is also helpful, for fulltext search of your SSB DB.

If you are using a ssb-server distribution like Patchwork, Patchbay or Oasis's ssb-server, these plugins are already included. If you are using ssb-server from the command-line, the plugins have to be installed separately:

```sh
sbot plugins.install ssb-backlinks
sbot plugins.install ssb-private
sbot plugins.install ssb-search
```

## Config

Pass config options with args
e.g. `npm start -- --patchfoo.port 8027` if running standalone,
or `sbot server --patchfoo.port 8027` if running as an sbot plugin.
To make config options persistent, set them in `~/.ssb/config`, e.g.:
```json
{
  "patchfoo": {
    "port": 8027,
    "host": "::",
    "filter": "all",
    "showPrivates": true,
    "previewVotes": true,
    "voteBranches": false,
    "ooo": true,
    "nav": [
      "new",
      "public",
      "private",
      "mentions",
      "peers",
      "status",
      "channels",
      "tags",
      "friends",
      "search"
      "live",
      "compose",
      "drafts",
      "emojis",
      "self",
      "searchbox"
    ],
    "dir": "patchfoo",
    "scriptDir": "script",
    "draftsDir": "drafts"
  }
}
```

### Config options

- `port`: port for the server to listen on. default: `8027`
- `host`: host address for the server to listen on. default: `localhost`
- `base`: base url that the app is running at. default: `/`
- `blob_base`: base url for links to ssb blobs. default: same as `base`
- `img_base`: base url for blobs embedded as images. default: same as `base`
- `encode_msgids`: whether to URL-encode message ids in local links. default: `true`
- `auth`: HTTP auth password. default: `null` (no password required)
- `allowAddresses`: Array of IP addresses allowed to connect. default: `null` (allow any to connect). Note if host is `localhost` then this setting is useless.
- `allowHosts`: Array of hostnames allowed that patchfoo may be connected at, or `*` to allow using any hostname. Default is to allow patchfoo's configured port, at patchfoo's configured host, `localhost`, `127.0.0.1` or `::1`. If hostname includes trailing colon without port, it means use patchfoo's server port. `*` for the port means allow connections at any port. If hostname begins with `.`, subdomains under it are allowed too.
- `trustedReferers`: Array of URL patterns allowed as base of HTTP Referers for POST & PUT requests to patchfoo, or `*` to allow any. Default is `http://` followed by patchfoo's host and port, or `localhost`, `127.0.0.1` or `[::1]` at patchfoo's port. Port may be wildcard (`*`) to allow any port, or blank (trailing `:`) for patchfoo's port. Subdomains can be allowed by beginning the hostname with a period (`.`). patchfoo subpaths which may contain arbitrary blob content are excluded from the set of allowed referers.
- `filter`: Filter setting. `"all"` to show all messages. `"invert"` to show messages that would be hidden by the default setting. Otherwise the default setting applies, which is so to only show messages authored or upvoted by yourself or by a feed that you you follow. Exceptions are that if you navigate to a user feed page, you will see messages authored by that feed, and if you navigate to a message page, you will see that message - regardless of the filter setting. The `filter` setting may also be specified per-request as a query string parameter.
- `showPrivates`: Whether or not to show private messages. Default is `true`. Overridden by `filter=all`.
- `previewVotes`: Whether to preview creating votes/likes/digs (`true`) or publish them immediately (`false`). default: `false`
- `previewContacts`: Whether to preview creating contact/(un)follow/block messages (`true`) or publish them immediately (`false`). default: `false`
- `voteBranches`: whether to publish vote messages with thread `branch` and `root` properties, and include `vote` messages in `branch` properties of a posts. default: `false`.
- `ooo`: if true, use `ssb-ooo` to try to fetch missing messages in threads. also can set per-request with query string `?ooo=1`. default: `false`
`codeInTextareas`: if `true`, render markdown code blocks in textareas. if `false`, render them in `pre` tags. default: `false`
- `nav`: array of nav links. Each item may be a string, object or special value. Special values are `"searchbox"` and `"self"`, which are the search field box, and link to the current feed id's page, respectively. Any other string is interpretted to be a link to the page of that name prefixed with a forward slash. An object may have properties `name` and `url`, and that will be interpretted as a link with given name and URL (with `toUrl` conversions applied). default is the list in the readme above.
- `dir`: name of directory in `~/.ssb/` to use for patchfoo things. default: `"patchfoo"`.
- `scriptDir: name of directory in patchfoo's directory (as set by `patchfoo.dir` config option above) to use for user scripts. default: `"script"`.
- `draftsDir: name of directory in patchfoo's directory (as set by `patchfoo.dir` config option above) to use for message draft data. default: `"drafts"`.
- `newLimit: limit of messages to show on `/new` page. Default: 500. Overridable with query string parameter `limit=...`.
- `dualMarkdownPreview`: Preview messages in composer in multiple SSB markdown implementations, `ssb-marked` and `ssb-markdown` >= 3. Overridable with query string parameter `dualMd=1`.
- `replyMentionFeeds`: Mention thread branch authors in "reply" property, like Patchwork. Default `true`.

## TODO

- Add more sophisticated private messages view.
- Count digs
- Show network status
- Add UI for using pub invites

[ssb-server]: %M0TrM+oJT2i/phUJO/fZ2wkK2AN2FB1xK0tqR7SNj58=.sha256
[patchbay]: %s9mSFATE4RGyJx9wgH22lBrvD4CgUQW4yeguSWWjtqc=.sha256
[ssb-npm]: %iqhz/sQCZCSp91JYAqfQPzHuDYrjw1geKPf1wJ1CvlA=.sha256
[git-ssb]: %n92DiQh7ietE+R+X/I403LQoyf2DtR3WQfCkDKlheQU=.sha256

## Art

> ![pache-hoo.png](&w2mUNZR/7zpDlif1dICILO2Gy94vzi411mxAhqeup30=.sha256)

Doodle by [Mia Gooper](@EZArijiRCJQLZAnpcZOTYzu8IVaUMyqQPGGDLFS2klk=.ed25519) from disussion of Chinese translation of the name of patchfoo: %SLqfK1QQ/JHeZzK4uOsWqX4YdQwMVdEJVtlLyD1582g=.sha256

> ![troglodita-med.jpg](&dGBjqrtI3jswU83CHyOQ1wwNtFhXcZkYfYSaV6jZT8U=.sha256)

[Troglodita Seal of Approval](https://ccom.uprrp.edu/~humberto/pages/troglodita.html), presented by [@hoz](@RtsOc2h1gqh0fRrjrUTHAkRBu9YyDgsD+EWsfLpykrc=.ed25519) in %w+oNAm1KCYmh5iKs2OIBE2PdyJX52ZSmX6VqRHwVObc=.sha256

## License

Copyright (C) 2017-2020 Secure Scuttlebutt Consortium

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.

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.

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/>.