Merge branch 'master' into add-profile-image-upload

fraction · Mar 12, 2020 · dba544c · dba544c
2 parents 1f6f635 + 504e9ba
commit dba544c
Show file tree

Hide file tree

Showing 13 changed files with 586 additions and 219 deletions.
diff --git a/.cspell.json b/.cspell.json
@@ -3,6 +3,7 @@
   "language": "en",
   "words": [
     "AGPL",
+    "EACCESS",
     "Argyris",
     "Hintjens",
     "Kata",

diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md
@@ -1,3 +1,5 @@
-**What's the problem you want solved?**
+## What's the problem you want solved?
 
-**Is there a solution you'd like to recommend?**
+## Is there a solution you'd like to recommend?
+
+## What version or commit of Oasis are you using?
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,3 +1,3 @@
-**What's the problem you solved?**
+## What's the problem you solved?
 
-**What solution are you recommending?**
+## What solution are you recommending?
diff --git a/README.md b/README.md
@@ -6,87 +6,69 @@ you follow friends and discover new ones on [Secure Scuttlebutt (SSB)][ssb].
 **🦀 Powered by SSB.**  
 You're the center of your own distributed network. Online or offline, SSB works
 anywhere that you are. Follow the people you want to see and never worry about
-spam again. Migrate your data to another SSB app any time you want.
+spam again. Switch to any SSB app you want at any time.
 
 **🌐 Bring your own browser.**  
 Use your favorite web browser to read and write messages to the people you care
-about. Oasis runs over HTTP, so you don't need to worry about adding another
-Electron app to your computer.
+about. Oasis runs a small HTTP server on your own computer, so you don't need
+to worry about adding another Electron app to your computer.
 
 **🏰 Just HTML and CSS.**  
 No browser JavaScript! Oasis has strict security rules that prevent any
 JavaScript from running in your browser, which helps us make Oasis accessible
 and easy to improve.
 
-![Screenshot of Oasis](./docs/screenshot.png)
-
-## Usage
-
-Start Oasis from a command-line interface with the `oasis` command.
-
-```console
-$ oasis --help
-Usage: oasis [options]
-
-Options:
-  --version   Show version number                                      [boolean]
-  -h, --help  Show help                                                [boolean]
-  --open      Automatically open app in web browser. Use --no-open to disable.
-                                                       [boolean] [default: true]
-  --offline   Don't try to connect to scuttlebutt peers or pubs. This can be
-              changed on the 'settings' page while Oasis is running.
-                                                      [boolean] [default: false]
-  --host      Hostname for web app to listen on  [string] [default: "localhost"]
-  --port      Port for web app to listen on             [number] [default: 3000]
-  --debug     Use verbose output for debugging        [boolean] [default: false]
-  -c --config Show current default configuration      [boolean] [default: false]
-```
-
-## Configuration
+## Example
 
-The above options can be permanently set with a configuration file found in a
-standard folder for configuration, depending on your operating system:
+After installing, launch Oasis from the command line by running:
 
-- Linux: `$XDG_CONFIG_HOME/oasis/default.json`.
-  Usually this is `/home/<your username>/.config/oasis/default.json`
-  <!-- cspell:disable-next-line -->
-- Windows `%APPDATA%\oasis\default.json`.
-- Mac OS, `/Users/<your username>/Library/Preferences/oasis/default.json`
-
-The configuration file can override any or all of the command-line _defaults_.
-Here is an example customizing the port number and the "open" settings:
-
-```json
-{
-  "open": false,
-  "port": 19192
-}
+```sh
+oasis
 ```
 
-### Configuration Semantics
+It will then pop open a browser window for you.
 
-Which value is given is decided like this:
+![Screenshot of Oasis](./docs/screenshot.png)
 
-1. If an argument is given on the command-line, use that value.
-2. Otherwise, use the value from the configuration file if present.
-3. If neither command-line nor configuration file are given, use the built-in default value.
+Use `oasis --help` to get configuration options. You can change the default
+values with a custom [configuration](./docs/configuring.md).
 
 ## Installation
 
-Most people should install stable releases with [npm](https://npmjs.org/) and
-Node.js [**current** or **active LTS** release](https://nodejs.org/en/about/releases/).
+First, you'll need Node.js and npm on your computer. Run `node --version` to see if you have it. If not, or if it's older than the [**current** or **active LTS** version](https://nodejs.org/en/about/releases/), you should [download Node.js](https://nodejs.org/en/about/releases/) first.
+
+Then you can install the stable version of Oasis:
 
 ```shell
-npm --global install 'fraction/oasis#semver:*'
+npm -g install fraction/oasis#semver:
 ```
 
-For faster updates and less stability, install from GitHub and upgrade often.
+Or, for faster updates and less stability, install Oasis from GitHub and upgrade often.
 
 ```shell
-npm --global install fraction/oasis
+npm -g install fraction/oasis
 ```
 
-Want more? Check out [`install.md`](https://github.com/fraction/oasis/blob/master/docs/install.md).
+Check out [`install.md`](https://github.com/fraction/oasis/blob/master/docs/install.md)
+for more information.
+
+## FAQ
+
+### Can I use the same profile from multiple computers?
+
+No, this is a limitation of SSB. You'll need to make a separate profile on each device. There is a workaround [we'd like to implement](https://github.com/fraction/oasis/issues/267) which ties your multiple profiles together.
+
+### Can I run this at the same time as Patchwork and other SSB apps?
+
+Yes! They will both use the same data and profile. You can either run them one at a time or simultaneously. If you run them at the same time, start Patchwork first, then Oasis.
+
+Details: SSB apps have two parts: a "server" that manages the database (on your own computer), and a user interface that gets things from the server to display. Only one server can run at a time, but multiple apps can use it.
+
+| App       | Runs its own SSB server            | Can use SSB server of another app              |
+| --------- | ---------------------------------- | ---------------------------------------------- |
+| Oasis     | Yes, unless one is already running | Yes                                            |
+| Patchwork | Yes                                | No, only uses its own server                   |
+| Patchfox  | No                                 | Yes, depends on other apps to provide a server |
 
 ## Resources
 

diff --git a/docs/MAINTAINERS b/docs/MAINTAINERS
@@ -1 +1,2 @@
 Christian Bundy <christianbundy@fraction.io>
+Cinnamon <cinnamon_oasis@fastmail.com>
diff --git a/docs/configuring.md b/docs/configuring.md
@@ -0,0 +1,28 @@
+# Configuring
+
+The default options can be permanently set with a configuration file found in a
+standard folder for configuration, depending on your operating system:
+
+- Linux: `$XDG_CONFIG_HOME/oasis/default.json`.
+  Usually this is `/home/<your username>/.config/oasis/default.json`
+  <!-- cspell:disable-next-line -->
+- Windows `%APPDATA%\oasis\default.json`.
+- Mac OS, `/Users/<your username>/Library/Preferences/oasis/default.json`
+
+The configuration file can override any or all of the command-line _defaults_.
+Here is an example customizing the port number and the "open" settings:
+
+```json
+{
+  "open": false,
+  "port": 19192
+}
+```
+
+## Semantics
+
+Which value is given is decided like this:
+
+1. If an argument is given on the command-line, use that value.
+2. Otherwise, use the value from the configuration file if present.
+3. If neither command-line nor configuration file are given, use the built-in default value.
diff --git a/docs/install.md b/docs/install.md
@@ -12,40 +12,35 @@ If you want to run Oasis on Android via Termux, see [`with-termux.md`](./with-te
 
 ## Download
 
-### HTTPS
-
-Most people should download Oasis over HTTPS.
+Download Oasis from GitHub over HTTPS.
 
 ```shell
 git clone https://github.com/fraction/oasis.git
 ```
 
-### SSH
+## Install dependencies
 
-If you already have SSH, you may prefer to download over SSH instead.
+Most people should build and install Oasis with npm.
 
 ```shell
-git clone git@github.com:fraction/oasis.git
+cd oasis
+npm install --only=prod
 ```
 
-## Install
+## Start
 
-Most people should build and install Oasis with npm.
+You can try Oasis without installing with:
 
 ```shell
-cd oasis
-npm install
-npm --global install .
+node .
 ```
 
-## Start
+## Install globally
 
-You did it! Oasis should now be installed.
+If you want to install to make `oasis` available globally:
 
 ```shell
-oasis --help
+npm -g install .
 ```
 
-If you have problems, read the documentation on [downloading and installing
-packages globally](https://docs.npmjs.com/downloading-and-installing-packages-globally)
-or [get some help](https://github.com/fraction/oasis/issues/new/choose).
+If you see a permission error, see [resolving EACCESS permission errors](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally). If you any other problems, please [reach out for help](https://github.com/fraction/oasis/issues/new).
Original file line number	Diff line number	Diff line change
		@@ -1 +1,2 @@
		Christian Bundy <christianbundy@fraction.io>
		Cinnamon <cinnamon_oasis@fastmail.com>