Notifications

Notifications

Kinboard supports web push notifications — every device that opts in gets push messages for shopping-list changes, todo deadlines, calendar reminders, and birthday reminders.

Requirements (read this first)

Web push has hard browser-level requirements. If any of these aren't met, the Settings → Notifications toggle won't work and you'll usually get no error in the UI — just silence.

• HTTPS or http://localhost. The Service Worker API and Push API only work in a secure context. On a plain-HTTP LAN deployment (http://192.168.x.x:3001), browsers refuse to register the service worker that delivers push messages, and the PWA install prompt also won't fire. The exception http://localhost is a developer convenience — only the same machine qualifies, not phones on the LAN. To enable push on a self-host, terminate TLS in front of the webapp; the easiest path is documented in Self-hosting → From scratch: Traefik + Let's Encrypt. Cloudflare Tunnel is a no-port-forwarding alternative.
• A modern browser. Push API + Service Workers: Chrome 50+, Edge 17+, Firefox 44+, Safari 16.4+ (iOS 16.4+, macOS 13+ Ventura). Older Safari simply has no Push API surface — the toggle will be greyed out.
• iOS additionally requires the PWA to be installed via Add-to-Home-Screen. Apple delivers web push only to home-screen-installed PWAs, not to plain Safari tabs. Subscribing from regular Safari appears to succeed but the subscription is silently dropped — you'll never receive a push. The install flow is in the iOS section below.
• VAPID keys must be set on the server. Generated automatically by setup.sh (which runs npx web-push generate-vapid-keys) and written to webapp/docker/.env as VAPID_PUBLIC_KEY / VAPID_PRIVATE_KEY. If Node.js wasn't on PATH when you ran setup.sh, the keys are empty and push stays disabled — install Node.js, then run ./setup.sh --force to regenerate.

The Notifications settings page in the app detects the first three at runtime and surfaces a hint card explaining the missing requirement instead of an inert toggle. Server-side VAPID readiness shows up in /api/notifications/configured.

TL;DR — getting notifications working on a phone

1. Install Kinboard as a PWA (Add-to-Home-Screen). On iOS this is mandatory — Apple won't deliver web push to plain Safari, only to installed PWAs. On Android it's recommended for reliability.
2. Open Kinboard via the home-screen icon (not the browser bookmark).
3. Go to Settings → Notifications.
4. Tap Subscribe. Allow the permission prompt the first time.
5. Pick which event types you want pushed (shopping items, task assignments, daily todo digest).
6. (Optional) Set your quiet hours.
7. Tap Send test to verify a notification reaches your device.

If step 4 doesn't show the prompt, see Troubleshooting below.

Two PWAs available. Kinboard ships two installable PWAs that share the same backend: the main Kinboard PWA (full app) and a shopping-only PWA scoped to the shopping list. Push subscriptions are per-origin, so both PWAs share the same notification permission and can receive any notification type. Pick whichever install fits your phone usage. See Shopping-only PWA below.

What you can subscribe to

Per-device, in Settings → Notifications:

• Shopping list — new items ("someone added milk to the list")
• Shopping list — reminders ("you have 12 items still to buy")
• Tasks — new tasks ("Mom assigned a task to you")
• Tasks — daily reminder (8:00 AM digest of today's pending tasks)
• Calendar reminders — a heads-up before an upcoming event
• Birthday reminders — see Birthday reminders below

Plus Quiet hours — a daily window during which no push is delivered (you still get the badge in-app the next morning).

Birthday reminders

Per-device toggle in Settings → Notifications. When enabled, Kinboard sends a push notification ahead of each tracked birthday, timed by a per-birthday lead time (the "notify N days before" field on the birthday entry itself, not a single global setting) — so you can get a week's notice for a birthday that needs gift shopping and a same-day nudge for one that doesn't. Respects quiet hours like every other push type. See Birthdays → Reminders.

Installing as a PWA

The PWA install is what makes Kinboard feel like a native app on phones — and it's required for push to work on iOS. Per platform:

iOS (Safari)

1. Open Kinboard in Safari (not Chrome — iOS Chrome is just a Safari skin and won't install)
2. Tap the Share button (square with up-arrow)
3. Scroll down, tap Add to Home Screen
4. Confirm — an icon now lives on your home screen
5. Open Kinboard from that icon (not from Safari) — it launches in standalone mode without the URL bar
6. Push subscriptions made in this standalone mode work; subscriptions made in plain Safari are silently dropped by iOS

Android (Chrome / Edge / Firefox)

1. Open Kinboard in the browser
2. Browser usually offers an Install app prompt automatically — tap it
3. Or go to the browser menu → Install app / Add to Home screen
4. Confirm — icon lands on home screen
5. Push works from either the PWA or the regular browser tab on Android, but the PWA is more reliable when the browser is closed

Desktop (Chrome / Edge)

1. Look for the install icon in the address bar (a small monitor with a down-arrow)
2. Click it → Install
3. The app gets its own desktop icon + opens in a chromeless window
4. Push works either way on desktop

The kiosk install on the Mele 4C is also a Chrome PWA install — but the kiosk doesn't typically use push (it shows everything live anyway).

Shopping-only PWA (separate install)

Kinboard also ships a dedicated shopping-only PWA, installed separately from the main app and scoped to just the shopping list — the two coexist on the same device. For what it gives you, the install steps (iOS/Android), and the full comparison table, see Shopping → Standalone shopping-list PWA.

Notifications inside the shopping PWA: because both PWAs share the same origin, push permission is per-origin — toggle Settings → Notifications inside either PWA and the subscription works for both. If you have only the shopping PWA installed and the main PWA isn't installed at all, push still works fine via the shopping PWA's service worker.

How push works (the boring bits)

Web Push uses the VAPID protocol:

• The browser registers with the push service (Apple / Google / Mozilla)
• It returns an opaque endpoint URL the server can POST to
• Kinboard signs each push payload with the VAPID private key; the push service verifies and delivers
• The browser's service worker shows the notification, with sound, vibration, badge, etc.

VAPID keys are generated once per Kinboard instance via setup.sh:

NEXT_PUBLIC_VAPID_PUBLIC_KEY=<generated>
VAPID_PUBLIC_KEY=<same>
VAPID_PRIVATE_KEY=<generated>
VAPID_SUBJECT=mailto:admin@example.com

If you regenerate the keys, every existing subscription becomes invalid and users have to re-toggle the push subscription on each device.

Server-side cron

Reminders that aren't event-triggered (the daily 8:00 AM todo digest, calendar reminders, birthday reminders) run on a schedule via the cron container. Configuration in webapp/docker/ofelia.ini:

[job-exec "todo-reminders"]
schedule = 0 0 8 * * *      # daily at 08:00
container = kinboard-webapp
command = /usr/local/bin/todo-reminders

[job-exec "process-notifications"]
schedule = @every 60s         # every minute
container = kinboard-webapp
command = /usr/local/bin/process-notifications

The container shells into the webapp container and curls the corresponding /api/cron/* endpoint. Each endpoint is gated by the Authorization: Bearer ${CRON_SECRET} header — the CRON_SECRET is in the env so only a process inside the Docker network can call cron endpoints.

iOS quirks (recap)

iOS supports web push only for installed PWAs (Apple's restriction, not ours). Subscriptions made in plain Safari are silently dropped by iOS. The ShoppingInstallPrompt component nudges iOS users toward the dedicated Shopping-only PWA install when they hit the shopping page; either PWA install satisfies iOS's "must be standalone" requirement and unlocks push.

Full step-by-step in Installing as a PWA → iOS (Safari) above.

Quiet hours

Per-device quiet window. Quiet-hours-mode suppresses push delivery during the window — there's no queue-and-summarize-afterward behavior; you just don't get a digest at the end. Anything that happened during quiet hours is still visible in-app as normal (badges, lists) the next time you open Kinboard.

Testing

In Settings → Notifications, click Send test when subscribed. The webapp posts a test message via /api/notifications/test and you should get a "Test notification" pop on the device within ~5 seconds.

There's also a stand-alone Tkinter GUI in tools/notification-tester.py for end-to-end debugging. It connects to your Kinboard URL, lists subscribed devices, lets you fire arbitrary push payloads. Useful when developing new notification types.

Disabling notifications globally

Just don't set VAPID_* keys in .env. The webapp detects missing keys and hides the Notifications settings page.

For per-family disable: each user toggles their own subscription off. There's no admin override.

Troubleshooting

Symptom	Likely cause
"Not supported" banner	Browser doesn't support Web Push (older Safari without PWA, some lockdown browsers). Try Chrome / Edge / Firefox.
"Notifications blocked"	User denied the browser permission prompt. Reset via browser site settings.
Test notification doesn't arrive	VAPID subject doesn't match the URL Kinboard runs on, OR endpoints are unreachable from the host. Check webapp logs.
Notifications work in browser but not in iOS PWA	iOS requires the standalone display mode to be in manifest.json. Kinboard's manifest is correct; verify the PWA was actually installed via Add-to-Home-Screen and not just bookmarked.
Daily reminder fires twice	The cron container restarted while a job was running. Idempotency is best-effort; fix is to investigate why cron restarted.

Related

• Architecture — push_subscriptions and notification_preferences tables
• Quick-start — setup.sh is what generates VAPID keys for you
• Birthdays — where the per-birthday lead time is set
• See webapp/src/lib/push-sender.ts for the server-side push code