Commit f3461661a931b968bb62bde67965d30356580d49
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 v12cel committed on 7/9/2020, 6:01:05 PM
Parent: 6cebe23b4a308c44542ec7910f18f0172e47dd65
Files changed
| README.md | changed |
| README.md | |||
|---|---|---|---|
| @@ -21,52 +21,129 @@ | |||
| 21 | 21 … | - *and more* | |
| 22 | 22 … | ||
| 23 | 23 … | ## Joining SSB with Patchfoo | |
| 24 | 24 … | ||
| 25 … | +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.) | ||
| 26 … | + | ||
| 25 | 27 … | Find [this guide](%VaSj08AbdhIa4itK4z8Z91G80o2h5OhRLCEEO6MhAcU=.sha256) [on github](https://github.com/noffle/sailing-patchfoo) or [on | |
| 26 | 28 … | SSB](http://git.scuttlebot.io/%25VaSj08AbdhIa4itK4z8Z91G80o2h5OhRLCEEO6MhAcU%3D.sha256). | |
| 27 | 29 … | ||
| 28 | 30 … | ## Requirements | |
| 29 | 31 … | ||
| 30 | -- [ssb-server][] | ||
| 32 … | +- [ssb-server][] (may be bundled in Patchwork, Patchbay or Oasis) | ||
| 33 … | + | ||
| 34 … | +For development and installing from source: | ||
| 35 … | + | ||
| 36 … | +- Node.js | ||
| 31 | 37 … | - [ssb-npm][] | |
| 32 | 38 … | - [git-ssb][] | |
| 33 | 39 … | ||
| 40 … | +Recommended ssb-server plugins (see "Install extras" below): | ||
| 41 … | + | ||
| 42 … | +- ssb-backlinks | ||
| 43 … | +- ssb-private | ||
| 44 … | +- ssb-search | ||
| 45 … | + | ||
| 46 … | +### Note about Node v12 | ||
| 47 … | + | ||
| 48 … | +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 | ||
| 49 … | + | ||
| 34 | 50 … | ## Install | |
| 35 | 51 … | ||
| 52 … | +**Easy install: use the binary installer below.** | ||
| 53 … | + | ||
| 36 | 54 … | patchfoo can run either as a standalone process or as an ssb-server plugin. | |
| 37 | 55 … | ||
| 38 | 56 … | 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. | |
| 39 | 57 … | ||
| 40 | -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. | ||
| 58 … | +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. | ||
| 41 | 59 … | ||
| 42 | -### Install as a standalone process | ||
| 60 … | +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. | ||
| 43 | 61 … | ||
| 62 … | +### Binary install | ||
| 63 … | + | ||
| 64 … | +This installs a single executable file "patchfoo" on your system, with an embedded Node.js. | ||
| 65 … | + | ||
| 66 … | +Install patchfoo v1.5.1 binary for linux-{x64,armv7,arm64,x86} or macos-x64: | ||
| 67 … | + | ||
| 44 | 68 … | ```sh | |
| 69 … | +curl 'http://localhost:8989/blobs/get/&qmhp9n9eM4GMk4nm9XmCuXzgsJTeQbNhVHRUjgDYs4w=.sha256' | sh | ||
| 70 … | +``` | ||
| 71 … | + | ||
| 72 … | +[Licenses for git-ssb v1.5.1 binary release](&MIPxJWgw33j7u9CvIOUxbPlkzw3UF0LjOePlLUxVY8s=.sha256) | ||
| 73 … | + | ||
| 74 … | +### Install from source | ||
| 75 … | + | ||
| 76 … | +#### as a standalone process | ||
| 77 … | + | ||
| 78 … | +This is how to install patchfoo using git-ssb and ssb-npm and run it as a standalone process with a local ssb-server. | ||
| 79 … | + | ||
| 80 … | +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. | ||
| 81 … | + | ||
| 82 … | +```sh | ||
| 45 | 83 … | git clone ssb://%YAg1hicat+2GELjE2QJzDwlAWcx0ML+1sXEdsWwvdt8=.sha256 patchfoo | |
| 46 | 84 … | cd patchfoo | |
| 47 | 85 … | ssb-npm install --production --branch %azW4q2GOnr52FVPK7pQk06VVMRuUJdUHXKN1PzhB9d0=.sha256 | |
| 48 | 86 … | npm start | |
| 49 | 87 … | ``` | |
| 50 | 88 … | ||
| 51 | -### Install as a ssb-server plugin | ||
| 89 … | +#### as a ssb-server plugin | ||
| 52 | 90 … | ||
| 91 … | +This is the traditional way to install and run patchfoo. | ||
| 92 … | + | ||
| 53 | 93 … | ```sh | |
| 54 | 94 … | cd ~/.ssb/node_modules | |
| 55 | 95 … | git clone ssb://%YAg1hicat+2GELjE2QJzDwlAWcx0ML+1sXEdsWwvdt8=.sha256 patchfoo | |
| 56 | 96 … | cd patchfoo | |
| 57 | 97 … | ssb-npm install --production --branch %azW4q2GOnr52FVPK7pQk06VVMRuUJdUHXKN1PzhB9d0=.sha256 | |
| 58 | 98 … | node enable-plugin.js | |
| 59 | 99 … | ``` | |
| 60 | 100 … | ||
| 101 … | +### Install via ssb-npm | ||
| 102 … | + | ||
| 103 … | +patchfoo sometimes has releases published on ssb-npm. | ||
| 104 … | + | ||
| 105 … | +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`: | ||
| 106 … | +```sh | ||
| 107 … | +npm config set prefix ~/.local | ||
| 108 … | +``` | ||
| 109 … | +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`: | ||
| 110 … | +```sh | ||
| 111 … | +PATH="$HOME/.local/bin:$PATH | ||
| 112 … | +``` | ||
| 113 … | + | ||
| 114 … | +### as a standalone process | ||
| 115 … | + | ||
| 116 … | +This installs patchfoo globally and gives you a `patchfoo` executable. | ||
| 117 … | + | ||
| 118 … | +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. | ||
| 119 … | + | ||
| 120 … | +```sh | ||
| 121 … | +ssb-npm install -g patchfoo --branch %azW4q2GOnr52FVPK7pQk06VVMRuUJdUHXKN1PzhB9d0=.sha256 | ||
| 122 … | +``` | ||
| 123 … | + | ||
| 124 … | +### as a ssb-server plugin | ||
| 125 … | + | ||
| 126 … | +This does a global ssb-npm install and then symlinks it into place and installs it with ssb-server as a plugin. | ||
| 127 … | + | ||
| 128 … | +```sh | ||
| 129 … | +ssb-npm install -g patchfoo --branch %azW4q2GOnr52FVPK7pQk06VVMRuUJdUHXKN1PzhB9d0=.sha256 | ||
| 130 … | +dir=$(dirname $(realpath $(which patchfoo))) | ||
| 131 … | +ln -s "$dir" ~/.ssb/node_modules/ | ||
| 132 … | +node "$dir/enable-plugin.js" | ||
| 133 … | +``` | ||
| 134 … | + | ||
| 61 | 135 … | ## Install extras | |
| 62 | 136 … | ||
| 63 | 137 … | To most effectively render things, patchfoo needs the `ssb-backlinks` | |
| 64 | -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: | ||
| 138 … | +and `ssb-private` ssb-server plugins. The `ssb-search` plugin is also helpful, for fulltext search of your SSB DB. | ||
| 65 | 139 … | ||
| 140 … | +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: | ||
| 141 … | + | ||
| 66 | 142 … | ```sh | |
| 67 | 143 … | sbot plugins.install ssb-backlinks | |
| 68 | 144 … | sbot plugins.install ssb-private | |
| 145 … | +sbot plugins.install ssb-search | ||
| 69 | 146 … | ``` | |
| 70 | 147 … | ||
| 71 | 148 … | ## Config | |
| 72 | 149 … | ||
Built with git-ssb-web