Remora/README.md

Sandbar mobile

An installable companion for 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 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=../sandbar-mobile/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.