Files
cabinchat/README.md
T
Pascal SuterandClaude Opus 5.5 1459b3228d Cabin Chat 4.0: accounts, https, PWA, mentions, notifications
- accounts with name + password (salted sha256), one account on several
  devices at once, profile menu: change password, profile picture,
  link another device (QR code + one-time link), logout, delete account
- @mentions with picker and highlighting
- https by default with the router web admin's certificate; --http,
  --cert/--key installer options
- logo/favicon, app manifest, service worker (installable PWA)
- browser notifications via the service worker, no internet needed
- devserver: https option, ignore connections reset by the browser

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 15:28:11 +01:00

124 lines
5.9 KiB
Markdown

# cabinchat
A lightweight, web-based chat application for a small group of people to
communicate with each other (e.g. aboard a commercial flight), hosted on
OpenWrt devices such as the GL.iNet Beryl 7.
Browser-based group chat for a GL.iNet travel router (or any OpenWrt box).
Nothing to install on the phones, no extra packages on the router: it runs on
the built-in `uhttpd` web server with one small shell CGI script.
Group chat and private chats, photos, replies, emoji, @mentions, typing
notices, accounts with passwords (one account on several devices at once),
profile pictures, device linking by QR code, installable as an app (PWA) and
browser notifications. Messages disappear after 24 hours.
## Install on the router
Straight from git, in an SSH session on the router (`ssh root@192.168.8.1`):
curl -fsSL https://git.psuter.ch/psuter/cabinchat/raw/branch/main/dist/install-cabinchat.sh | sh
Add options after `sh -s --`, e.g. `... | sh -s -- -p 8090`. If `curl` is
missing, `wget -qO- <same URL> | sh` works too.
Or copy it over from a checkout:
scp -O dist/install-cabinchat.sh root@192.168.8.1:/tmp/
ssh root@192.168.8.1 sh /tmp/install-cabinchat.sh
Open `https://192.168.8.1:8088` (or `https://chat.lan:8088`) on the router's WiFi.
Running a newer installer over an existing install upgrades it and keeps
accounts, messages, photos, the port and the http/https choice. Options:
-p <port> port (default 8088)
--http plain http instead of https
--cert <file> --key <file> https with your own certificate (PEM, kept on upgrades)
wipe delete all messages and photos (accounts stay)
uninstall remove everything
## HTTPS, app install and notifications
By default the chat uses https with the certificate of the router's web admin
(GL.iNet: the one nginx uses). That certificate is self-signed, so every
browser shows a warning once; accept it to continue. If the router has no
certificate or uhttpd lacks TLS support, the installer falls back to http.
Browsers only offer some features on a *trusted* https connection:
| | trusted cert | router's self-signed cert | `--http` |
|---|---|---|---|
| chat, photos, accounts | ✓ | ✓ (after the warning) | ✓ |
| install as app (Android/desktop) | ✓ | no | no |
| Add to Home Screen (iOS) | ✓ | ✓ | ✓ |
| notifications | ✓ | usually blocked (browser-dependent) | no |
To get everything, give the installer a certificate the phones trust, e.g. a
Let's Encrypt certificate for a name in a domain you own (obtained at home via
DNS challenge), and point that name at the router:
`uci add_list dhcp.@dnsmasq[0].address='/chat.example.com/192.168.8.1'`.
Checking a certificate needs no internet, so this works in the air.
Notifications work while the chat is open in the background: in another tab,
or minimized with the screen on. Real push to a closed app needs the browser
maker's push service (internet), so phones that freeze background apps stop
getting notified until the chat is opened again.
## Accounts
Joining asks for a name and a password. A new name creates an account; an
existing name needs its password. Log in with the same name on more devices
to use them in parallel, or use *Link another device* in the profile menu
(click your name at the bottom of the chat list): it shows a QR code and a
link that log the other device in. Each link works once, for 10 minutes. The
profile menu also changes the password, sets a profile picture, controls
notifications, logs out and deletes the account (with everything it posted).
Passwords are stored as salted SHA-256 hashes (busybox has nothing slower).
Without https they cross the WiFi in plain text.
## Project layout
www/index.html the whole web app (HTML/CSS/JS, no external files)
www/cgi-bin/chat backend (POSIX sh + busybox); the API is described at its top
www/sw.js service worker (app install, notification clicks, offline page)
www/manifest.json app manifest
www/logo.svg logo and favicon; PNG icons are made from it by icons.sh
www/VERSION version string, bump it for a new release
data/, www/img/ chat data while developing (created on first use)
installer.sh.in installer template
build.sh bundles www/ into dist/install-cabinchat.sh
devserver.py dev server that behaves like uhttpd (stdlib Python)
icons.sh regenerates the PNG icons (needs inkscape + Pillow)
## Develop on a notebook or in Termux
python3 devserver.py # Termux: pkg install python
# open http://localhost:8088, or the LAN URL it prints from a phone
Edit `www/`, reload the browser. Chat data lives in `data/` and photos in
`www/img/` (delete both to start over). Open the page in two browsers (or a
normal and a private window) to test private chats, mentions and typing
notices. App install and notifications work on `localhost`; to try them from
a phone, run `devserver.py --cert cert.pem --key key.pem`. When you're happy:
bump `www/VERSION`, run `sh build.sh`, copy `dist/install-cabinchat.sh` to the
router.
> **Before every commit, run `sh build.sh` and commit the rebuilt
> `dist/install-cabinchat.sh` together with your changes.** The built
> installer is tracked in git on purpose: the curl one-liner above installs
> whatever is in `dist/` on `main`, so a stale installer means people get an
> old version.
## Storage
On the router's flash, outside the web root: `/www-chat/data/messages` (one
line per message), `seq`, `gen`, and `accounts/`, `names/`, `sessions/`,
`avatars/` (one small file per account, name, logged-in device and profile
picture); photos in `/www-chat/htdocs/img/` with random file names. Messages
older than 24 h are dropped on the fly. Photos are refused once they pass
50 MB. Presence, typing notices, device-link codes and the long-poll event
token live in RAM under `/tmp/cabinchat/`. Limits are at the top of
`www/cgi-bin/chat`.