ackandClaude Opus 4.8
cc0b8dbd31
From the development repository at 3f1da52. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
108 lines
4.3 KiB
Markdown
108 lines
4.3 KiB
Markdown
# 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, Expand, 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.
|