fotospiel-app/docs/ops/guest-notification-ops.md

Guest Notification & Push Ops Guide

This runbook explains how to keep the guest notification centre healthy, roll out web push, and operate the new upload health alerts.

1. Database & config prerequisites

1. Run the latest migrations so the push_subscriptions table exists:

   php artisan migrate --force
   

2. Generate VAPID keys (using web-push or any Web Push helper) and store them in the environment:

   PUSH_ENABLED=true
   PUSH_VAPID_PUBLIC_KEY=<base64-url-key>
   PUSH_VAPID_PRIVATE_KEY=<base64-url-key>
   PUSH_VAPID_SUBJECT="mailto:ops@example.com"
   

3. Redeploy the guest PWA (Vite build) so the runtime config exposes the new keys to the service worker.

2. Queue workers

Push deliveries are dispatched on the dedicated notifications queue. Ensure one of the queue workers listens to it:

/var/www/html/scripts/queue-worker.sh default,notifications

If Horizon is in use just add notifications to the list of queues for at least one supervisor. Monitor storage/logs/notifications.log (channel notifications) for transport failures.

3. Upload health alerts

The storage:check-upload-queues command now emits guest-facing alerts when uploads stall or fail repeatedly. Schedule it every 5 minutes via cron (see cron/upload_queue_health.sh) or the Laravel scheduler:

*/5 * * * * /var/www/html/cron/upload_queue_health.sh

Tune thresholds with the STORAGE_QUEUE_* variables in .env (see .env.example for defaults). When an alert fires, the tenant admin toolkit also surfaces the same issues.

4. Manual API interactions

• Register push subscription (from browser dev-tools):

  POST /api/v1/events/{token}/push-subscriptions
  Headers: X-Device-Id
  Body: { endpoint, keys:{p256dh, auth}, content_encoding }
  

• Revoke subscription:

  DELETE /api/v1/events/{token}/push-subscriptions
  Body: { endpoint }
  

• Inspect per-guest state:

  php artisan tinker
  >>> App\Models\PushSubscription::where('event_id', 123)->get();
  

5. Smoke tests

After enabling push:

1. Join a published event, open the notification centre, and enable push (browser prompt must appear).
2. Trigger a host broadcast or upload-queue alert; confirm the browser shows a native notification and that the notification drawer refreshes without polling.
3. Temporarily stop the upload workers to create ≥5 pending assets; re-run storage:check-upload-queues and verify guests receive the “Uploads werden noch verarbeitet …” message.

Document any deviations in a bd issue note for future regressions.