From f3461661a931b968bb62bde67965d30356580d49 Mon Sep 17 00:00:00 2001 From: cel Date: Thu, 9 Jul 2020 13:50:56 -0400 Subject: Expand readme installation info - Add binary installer - Add ssb-npm install - Explain various use cases - Also mention ssb-search as a recommended plugin - Mention issue with sodium-native in Node v12 --- README.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 82 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 7d777cb..a5732f1 100644 --- a/README.md +++ b/README.md @@ -22,24 +22,62 @@ Plain SSB web UI. Uses HTML forms instead of client-side JS. Designed for use on ## 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][] +- [ssb-server][] (may be bundled in Patchwork, Patchbay or Oasis) + +For development and installing from source: + +- Node.js - [ssb-npm][] - [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 can 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. +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 -### Install as a standalone process +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 @@ -48,7 +86,9 @@ ssb-npm install --production --branch %azW4q2GOnr52FVPK7pQk06VVMRuUJdUHXKN1PzhB9 npm start ``` -### Install as a ssb-server plugin +#### as a ssb-server plugin + +This is the traditional way to install and run patchfoo. ```sh cd ~/.ssb/node_modules @@ -58,14 +98,51 @@ ssb-npm install --production --branch %azW4q2GOnr52FVPK7pQk06VVMRuUJdUHXKN1PzhB9 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 %azW4q2GOnr52FVPK7pQk06VVMRuUJdUHXKN1PzhB9d0=.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 %azW4q2GOnr52FVPK7pQk06VVMRuUJdUHXKN1PzhB9d0=.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. If you are using a ssb-server distribution like Patchwork, Patchbay or Oasis's ssb-server, these are already included. If you are using ssb-server from the command-line, the plugins have to be installed separately: +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 -- cgit v1.2.3