pingd docs

Web Push (browsers)

pingd uses VAPID Web Push for browser notifications. The bundled dashboard turns into a PWA you can install.

1. Generate a VAPID config

One time per deployment:

docker compose exec pingd ./pingd-webpush-keygen --email admin@example.com
swift run pingd-webpush-keygen --email admin@example.com

Or use a support URL instead of an email:

docker compose exec pingd ./pingd-webpush-keygen --url https://example.com/support
swift run pingd-webpush-keygen --url https://example.com/support

The output is an env-ready value:

PINGD_WEBPUSH_VAPID_CONFIG='{"contactInformation":"mailto:admin@example.com","expirationDuration":79200,"primaryKey":"...","validityDuration":72000}'
Treat the VAPID config as a secret. The primaryKey field is the private signing key. Reuse the same value across restarts; rotating it invalidates every existing browser subscription.

2. Set the env var

Add to your Compose file or environment:

PINGD_WEBPUSH_VAPID_CONFIG={"contactInformation":"mailto:admin@example.com","expirationDuration":79200,"primaryKey":"...","validityDuration":72000}

Restart pingd. Verify with:

curl http://localhost:7685/webpush/vapid-key

Returns 200 with the public VAPID key, or 404 if Web Push is unconfigured.

3. Subscribe a browser

Open the dashboard, log in, and click the bell icon to enable notifications. The dashboard fetches the VAPID key, registers the service worker, creates a PushSubscription, and registers the browser as a Web Push device.

Browser requirements

Plain HTTP on a public host or LAN IP does not work. Browsers block pushManager.subscribe() outside secure contexts.