- GL.iNet: nginx terminates https with the web admin's certificate and
serves static files (conf.d/zz-cabinchat.conf, after gl.conf so the
admin stays nginx's default server); /cgi-bin/ goes to uhttpd on
127.0.0.1 (fcgiwrap is shared with the admin and runs only 4 scripts)
- --name <host>: also serve https://<host>/ on port 443 plus an http
redirect, add the name to dnsmasq; guessed from dnsmasq entries that
contain "chat" and match the certificate; server_name as regex since
GL's server_names_hash_bucket_size is too small
- config checked with nginx -t, falls back to uhttpd; kept on firmware
updates via /etc/sysupgrade.conf
- fix: TLS detection failed when /usr/lib/libustream-ssl.so is missing
- fix: previous version read from the wrong place ("upgrading 1.x")
- fix: photos of expired messages and deleted accounts were never
removed (file name check rejected ".jpg")
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
156 lines
7.8 KiB
Markdown
156 lines
7.8 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, or `https://<name>` if you set up a name (see below). The installer prints
|
|
the addresses at the end.
|
|
|
|
Running a newer installer over an existing install upgrades it and keeps
|
|
accounts, messages, photos and the settings below. Options:
|
|
|
|
-p <port> port (default 8088)
|
|
--name <host> also serve https://<host>/ (GL.iNet/nginx only)
|
|
--no-name forget the name
|
|
--http plain http instead of https (--https switches back)
|
|
--cert <file> --key <file> https with your own certificate (PEM)
|
|
--no-nginx GL.iNet: use uhttpd alone (--nginx switches back)
|
|
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.
|
|
|
|
On GL.iNet firmware the web admin runs on nginx. The installer adds
|
|
`/etc/nginx/conf.d/zz-cabinchat.conf`: nginx does https with the admin's
|
|
certificate (`/etc/nginx/nginx.cer`) and serves the static files on port 8088,
|
|
and passes `/cgi-bin/chat` to a small uhttpd instance that only listens on
|
|
`127.0.0.1:8088`. (nginx's own CGI helper, fcgiwrap, runs only 4 scripts at a
|
|
time and is shared with the web admin; the chat keeps one waiting request per
|
|
open browser, so it gets its own.) The config is checked with `nginx -t`
|
|
first; if nginx refuses it, the installer falls back to uhttpd alone.
|
|
|
|
On other OpenWrt routers uhttpd does https itself (needs `libustream-ssl`).
|
|
If the router has no certificate or no TLS support, the installer falls back
|
|
to http.
|
|
|
|
The router's factory certificate is self-signed, so every browser shows a
|
|
warning once; accept it to continue.
|
|
|
|
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, use a certificate the phones trust, e.g. a Let's Encrypt
|
|
certificate for a domain you own (obtained at home via DNS challenge, a
|
|
wildcard `*.example.com` is handy). On GL.iNet, install it as the web admin's
|
|
certificate (`/etc/nginx/nginx.cer` with the full chain, and `nginx.key`),
|
|
then run the installer with `--name chat.example.com`. nginx then also
|
|
serves the chat on `https://chat.example.com/` (port 443, next to the web
|
|
admin, which keeps answering on the IP address and other names), redirects
|
|
http to https, and the installer adds the name to the router's DNS so it
|
|
resolves without internet. Checking a certificate needs no internet either,
|
|
so this works in the air. If the router's DNS already has a name that
|
|
contains "chat" and matches the certificate, the installer picks it without
|
|
`--name`. Elsewhere, pass the certificate with `--cert`/`--key`.
|
|
|
|
**Firmware updates** (GL.iNet, with "keep settings"): the installer adds
|
|
`/www-chat/` and the nginx config file to `/etc/sysupgrade.conf`, so they are
|
|
kept along with the uhttpd and DNS settings and the web admin's certificate.
|
|
If a future firmware's nginx should reject the chat's config file, run the
|
|
installer again (or delete `/etc/nginx/conf.d/zz-cabinchat.conf`).
|
|
|
|
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. Installer settings:
|
|
`hostname`, `http-only`, `no-nginx`, `tls/` in the same data folder. 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`.
|