Docs: Kokkoja in five minutes

README.md

@@ -15,6 +15,8 @@ may be used.
 
 * [An introduction](docs/introduction.md): what Kokkoja does and whom it
   is for.
+* [Kokkoja in five minutes](docs/quickstart.md): the shortest path to a
+  shared page, for someone at home in a terminal.
 * [A guest's Kokkoja](docs/guest.md): joining a session from an
   invitation, and the screen.
 * [A host's Kokkoja](docs/host.md): installing the Kokkoja program,

docs/introduction.md

@@ -146,6 +146,8 @@ view first, since the host sees the same screen and has a few more
 buttons, then from the host's, and finally explains how it works
 underneath, for those who want to run their own server or read the code.
 
+* [Kokkoja in five minutes](quickstart.md), the shortest path for
+  someone at home in a terminal
 * [A guest's Kokkoja](guest.md)
 * [A host's Kokkoja](host.md)
 * [How Kokkoja works](implementation.md)

docs/quickstart.md

@@ -0,0 +1,102 @@
+# Kokkoja in five minutes
+
+The shortest path from nothing to a shared page, for someone who is at
+home in a terminal.  Everything here is said at more length in [A host's
+Kokkoja](host.md), [A guest's Kokkoja](guest.md) and [How Kokkoja
+works](implementation.md).
+
+## What you are installing
+
+Kokkoja has three parts.  The **client** is plain JavaScript that runs
+in a browser.  The **local program**, `kokkoja.py`, serves the client to
+your own browser and keeps your notebooks as directories of SVG files;
+a host needs it, a guest does not.  The **relay** passes the
+participants' messages, encrypted end to end so that it cannot read
+them, and serves the client to guests as a web site; Andy's relay at
+`kokkoja.andykopra.com` is there for you, and you can run your own.
+
+## Requirements
+
+* Linux or macOS.  Windows is untried.
+* Python 3.  The local program uses the standard library only; nothing
+  is installed with pip.
+* Firefox, Brave, Chrome or Safari.
+* A pen tablet, or the pencil of a tablet, for handwriting.  A mouse
+  does for pointing and rough marks.
+
+## Install
+
+    git clone https://git.andykopra.com/ack/kokkoja-rel.git kokkoja
+    cd kokkoja
+
+or download and unpack
+`https://git.andykopra.com/ack/kokkoja-rel/archive/main.zip`.  Nothing
+else touches your system.  Updating is `git pull`; removal is deleting
+the directory.
+
+## Host a session
+
+    python3 kokkoja.py --relay wss://kokkoja.andykopra.com/relay
+
+The program prints `http://localhost:8760/#token=…` and opens your
+browser there.  Enter a name, choose a notebook, press **Start a
+session**.  The relay is remembered, so from now on `python3 kokkoja.py`
+suffices.  Keep the terminal open while the session lasts; Ctrl-C ends
+the program.
+
+**Session** in the toolbar shows the invitation: a link such as
+
+    https://kokkoja.andykopra.com/#join=wss://kokkoja.andykopra.com/relay%23<secret>.<host id>
+
+Send it by any means, or let the other person scan the QR code under it.
+The part after `#` is never sent to the web site; it carries the
+session's secret, so treat the link as you would a meeting link.
+
+## Join a session
+
+Open the invitation link in a browser.  Enter a name and press **Join**.
+That is all; the page is in front of you.  A guest with the local
+program installed can instead paste the link into their own program's
+start screen, and then their notebooks are files on their computer
+rather than in the browser's storage.
+
+## The screen in one paragraph
+
+The toolbar holds the pen, text, eraser and hide tools, colours and
+line widths, the view commands (Fit, A4, Widen, Shrink, Extend), the
+host's page buttons (New, Image, Notebook), your notebook, Keep, Export
+and Session.  Rest the pointer on any button for two seconds for its
+explanation.  Each participant writes on a layer of their own that
+nobody else can change.  The page is saved continuously to the current
+notebook, `Current.svg`; Keep makes a dated copy.  Rest the pen on an
+image to move it, near a corner to scale it.  Ctrl (Command on a Mac)
+with the wheel, or with a pen drag, zooms.
+
+## Where things are
+
+* Notebooks: `~/Documents/Kokkoja/<notebook>/`, one SVG file per page,
+  which any browser displays.
+* The program's settings, including your identity key and the remembered
+  relay: `~/.config/kokkoja/` on Linux, `~/Library/Application
+  Support/kokkoja/` on macOS.
+* Options: `--notebooks DIR`, `--port N` (default 8760), `--no-browser`,
+  `--site URL`, `--config DIR`.
+
+## Your own relay
+
+    python3 -m venv .venv && .venv/bin/pip install -r relay/requirements.txt
+    .venv/bin/python relay/kokkoja_relay.py --host 0.0.0.0 --port 8770
+
+Then hosts start with `--relay ws://<host>:8770`.  For a public server
+with TLS, the web site and a systemd service, `deploy/` has the nginx
+and systemd files and `deploy/README.md` the steps.  The relay stores
+nothing and sees only ciphertext.
+
+## Tests and types
+
+    .venv/bin/pip install -r tests/requirements.txt
+    .venv/bin/python -m unittest discover tests
+    npm install && npm run check
+
+The end-to-end test needs Firefox and geckodriver; the type check is
+TypeScript over JSDoc comments and is the only use of npm.