kokkoja-rel/docs/quickstart.md

# 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;
without it the notebooks live in the browser's storage.  The **relay**
passes the participants' messages, encrypted end to end so that it
cannot read them, and serves the client as a web site, from which anyone
can host or join with nothing installed; 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

With nothing installed: open `https://kokkoja.andykopra.com/`, enter a
name, press **Start a session**; the notebooks are then in the browser.
With the program, for notebooks as files:

    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, Notebooks), your notebook, Keep, Export
and Session.  Rest the pointer on any button for a second 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.