77 lines
3.7 KiB
Markdown
77 lines
3.7 KiB
Markdown
# Remora
|
|
|
|
An installable companion for [Sandbar](https://git.veillax.com/Veillax/sandbar): push notifications, on-call actions
|
|
(acknowledge, snooze, escalate, resolve), topics, monitors and Hammerhead tunnel status.
|
|
|
|
It is a PWA with plain ES modules and no build step. See [docs/design.md](docs/design.md) for why it is not a native app.
|
|
|
|
## What you need
|
|
|
|
- A Sandbar server with the mobile endpoints. They are on the `feature/mobile-push` branch of Sandbar and not released yet.
|
|
- HTTPS for the server (or `localhost` while developing). Browsers only allow service workers and push on secure origins.
|
|
|
|
## Run it against a local Sandbar
|
|
|
|
Start Sandbar and let it serve this folder:
|
|
|
|
```
|
|
cd ../sandbar
|
|
SANDBAR_ADMIN_EMAIL=dev@example.com SANDBAR_ADMIN_PASSWORD=choose-a-password \
|
|
SANDBAR_APP_DIR=../remora/public SANDBAR_PUSH_DEV=1 \
|
|
go run ./cmd/sandbar -listen 127.0.0.1:8090 -url http://127.0.0.1:8090
|
|
```
|
|
|
|
Open `http://127.0.0.1:8090/app/`, sign in, then Settings, Turn on notifications.
|
|
`SANDBAR_PUSH_DEV=1` is only for development: it allows `http` push endpoints and private addresses.
|
|
|
|
To work on the app files with their own server, run `npm run serve` (port 5173) and start Sandbar with
|
|
`SANDBAR_APP_ORIGIN=http://localhost:5173`. Enter the Sandbar address on the sign-in screen.
|
|
|
|
## Install it for real
|
|
|
|
1. Put Sandbar behind HTTPS and set `SANDBAR_URL` and `SANDBAR_APP_DIR` (or host `public/` anywhere and set `SANDBAR_APP_ORIGIN`).
|
|
Set `SANDBAR_VAPID_SUBJECT=mailto:you@example.com` so push services can reach you. The VAPID key is created on first use
|
|
and stored in the database; moving to a new database means people must turn notifications on again.
|
|
2. On Android, open `/app/` in Chrome, sign in, turn on notifications, then Install app.
|
|
3. On iPhone (iOS 16.4 or later), open `/app/` in Safari, Share, Add to Home Screen, open it from the Home Screen, then turn on notifications.
|
|
|
|
To see Hammerhead in the Status tab, set `SANDBAR_HAMMERHEAD_URL`, `SANDBAR_HAMMERHEAD_EMAIL` and
|
|
`SANDBAR_HAMMERHEAD_PASSWORD` on Sandbar, using an account without two-factor sign-in.
|
|
|
|
## What is in it
|
|
|
|
| Tab | What it does |
|
|
| --- | --- |
|
|
| Alerts | Open and recent alerts. Acknowledge, Snooze 30 min, Escalate now, Resolve. Updates live and by push. |
|
|
| Topics | Follow topics (they become push subscriptions), read the last 7 days, send a message. |
|
|
| Monitors | Every monitor with up, down or pending, last check and 30 day uptime. Read-only. |
|
|
| Status | Who is on call, and Hammerhead edges (online or offline) when linked. |
|
|
| Settings | Turn push on or off, send a test, list and remove devices, sign out (deletes this phone's API key). |
|
|
|
|
Notifications for a firing alert carry Acknowledge and Snooze buttons that work without opening the app (Android and desktop).
|
|
|
|
## Layout
|
|
|
|
```
|
|
public/ the app, served as is
|
|
index.html app.css app.js the page
|
|
api.js Sandbar API client (also used by tests)
|
|
store.js sign-in and topics in IndexedDB, shared with the worker
|
|
sw.js push, notification buttons, offline shell
|
|
scripts/ make-icons.mjs (regenerates the PNG icons), serve.mjs (dev server)
|
|
test/ node --test: API client and service worker
|
|
docs/design.md why a PWA
|
|
```
|
|
|
|
```
|
|
npm test
|
|
```
|
|
|
|
## Not done
|
|
|
|
- Push delivery was verified with Sandbar's Go tests (the payload is decrypted and the VAPID signature checked), but not
|
|
through a real Google, Apple or Mozilla push service. The in-app browser used for development refuses service workers,
|
|
so the service worker is tested in a simulated scope, not in a browser.
|
|
- No offline data beyond the app shell, no incident screens, no editing of monitors or schedules.
|
|
- Hammerhead sign-in with two-factor accounts is not supported.
|