2026-10-06 15:58:02 +02:00
|
|
|
# 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
|
2026-10-10 19:01:20 +02:00
|
|
|
`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)".
|
2026-10-06 15:58:02 +02:00
|
|
|
|
|
|
|
|
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.
|
