kokkoja-rel/deploy/README.md

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 at kokkoja.andykopra.com.

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://kokkoja.andykopra.com/relay", "storage": "browser", "site": "https://kokkoja.andykopra.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://kokkoja.andykopra.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:

1. DNS: an A record kokkoja.andykopra.com pointing at the VPS (82.221.141.89), in cPanel's Zone Editor, since andykopra.com is on the orangewebsite.com nameservers. Check with host kokkoja.andykopra.com buffy.ns.orangewebsite.com.

2. TLS, after the name resolves and deploy.sh has run once:

   ssh root@vps313847.iceservers.net certbot --nginx -d kokkoja.andykopra.com
   

   certbot adds the TLS listener to the nginx site and turns the plain HTTP block into a redirect. Afterwards setup_vps.sh leaves the installed nginx site alone, so a later change to nginx-site.conf must be carried over by hand.

3. 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://kokkoja.andykopra.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.