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>
76 lines
3.6 KiB
Markdown
76 lines
3.6 KiB
Markdown
# 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:
|
|
|
|
1. DNS: an A record `app.kokkoja.com` pointing 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
|
|
name `kokkoja.andykopra.com` keeps its A record in cPanel's Zone
|
|
Editor and is redirected to app.kokkoja.com by nginx. Check with
|
|
`host app.kokkoja.com`.
|
|
|
|
2. TLS, after the name resolves and `deploy.sh` has run once:
|
|
|
|
ssh root@vps313847.iceservers.net certbot --nginx -d app.kokkoja.com -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://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.
|