# 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.