ackandClaude Fable 5.1
89b4a41b2a
With the Text tool, Klammertext's codes give letters a keyboard lacks: ^o" is ö, ^s^ ß, ^a1 ā, ^130ED^ a code point of 4 to 6 digits, ^9053 53EF^ a sequence, ^^ a caret, replaced as each code is completed. The public site and relay moved to app.kokkoja.com; the old name redirects. The Markdown documentation is withdrawn from the release while it is converted to Klammertext; the README's links to it are stale until then. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The Kokkoja server
A Kokkoja server is one machine that does two things for a group of
users: it runs the relay, which passes the participants' encrypted
messages, and it serves the client as a web site, so that a guest can
join by opening a link with nothing installed. Neither stores anything.
The first one is Andy's VPS, reached at app.kokkoja.com (the older
name kokkoja.andykopra.com still works, redirected there).
| On the server | What it is |
|---|---|
/opt/kokkoja/relay/ |
the relay's code (relay/ in this repository) |
/opt/kokkoja/venv/ |
Python with the websockets library |
/var/www/kokkoja/ |
the client (client/) and its config.json |
kokkoja-relay.service |
the relay, run as the system user kokkoja, on 127.0.0.1:8770 |
nginx site kokkoja |
https://<site>/ serves the client; wss://<site>/relay reaches the relay |
The client's config.json on the site says
{"relay": "wss://app.kokkoja.com/relay", "storage": "browser", "site": "https://app.kokkoja.com/"}: the notebooks of anyone using
the site are kept in their browser. A host with the local program uses
the server with python3 kokkoja.py --relay wss://app.kokkoja.com/relay;
the invitation is then a link to the site.
Setting up or updating
From the project directory on a development machine:
deploy/deploy.sh
copies the relay, the client and the files in this directory to the
server and runs setup_vps.sh there, which makes or updates everything
in the table and restarts the relay. It can be run again at any time.
KOKKOJA_SERVER names another ssh destination than
root@vps313847.iceservers.net. The VPS accepts root logins from the
keys of Jatke, Kukka and, since 2026-10-09, Olion (Andy's laptop, for
travelling); from any other machine the script fails with "Permission
denied (publickey)".
Steps a person does, once:
-
DNS: an A record
app.kokkoja.compointing at the VPS (82.221.141.89), wherever kokkoja.com's DNS is managed (its registrar, or the orangewebsite.com nameservers if delegated there). The older namekokkoja.andykopra.comkeeps its A record in cPanel's Zone Editor and is redirected to app.kokkoja.com by nginx. Check withhost app.kokkoja.com. -
TLS, after the name resolves and
deploy.shhas run once:ssh root@vps313847.iceservers.net certbot --nginx -d app.kokkoja.com -d kokkoja.andykopra.comcertbot adds the TLS listener to the nginx site and turns the plain HTTP block into a redirect. Afterwards
setup_vps.shleaves the installed nginx site alone, so a later change tonginx-site.confmust be carried over by hand. -
The VPS sentinel sees a new service, a new user, a new nginx site and a new listening socket. After deploying, as root on the VPS:
vps-sentinel --accept
Checks: https://app.kokkoja.com/config.json shows the
configuration above; systemctl status kokkoja-relay is active;
journalctl -u kokkoja-relay -n 20 shows it listening.
Security
The relay sees only ciphertext and room ids and keeps nothing. It runs as a user of its own under systemd's sandboxing (read-only system, no home directories, no new privileges). The site sends a Content Security Policy that lets the client load nothing from anywhere else and forbids framing. What the site cannot protect against is itself: whoever controls the server could serve a changed client to browser-only guests. Participants running the local program are not exposed to that.