Configure and operate push notifications
FF RESTaurent stores every notification in the application and uses Firebase Cloud Messaging (FCM) for best-effort browser delivery. This guide explains how to configure Firebase, test push delivery locally, prepare the production runtime, and diagnose failed delivery.
For authenticated updates to the notification list and unread badge while the application is open, see Real-Time Notification Inbox.
The notification implementation is merged into develop, but the current production web build and Cloud Run deployment do not pass the Firebase environment variables. Complete the production enablement steps before treating push delivery as active.
Understand the delivery contract
The in-app Notification row remains the source of truth. Push delivery never blocks or fails the action that creates a restaurant, publishes a Collection, or sends a payment reminder.
| Event | Audience | Default in-app state | Default push state |
|---|---|---|---|
| Payment reminder | Eligible unpaid participants with paymentRemindersEnabled enabled | Enabled | Sent when the browser has a current subscription |
| New restaurant | Active members except the actor | Enabled | Disabled until the member opts in |
| New public Collection | Active members except the actor | Enabled | Disabled until the member opts in |
| Meal-voting lifecycle | Reserved for a later phase | Not exposed | Not exposed |
Product-event publishers use a deduplication key. Repeating the same publish action does not create or resend the same event. Push-only preferences create a hidden source row, so delivery state remains observable without displaying an in-app entry.
The implementation silently skips push delivery when:
- Firebase is not configured
- The browser does not support service workers or notifications
- The member denies notification permission
- The member has no current Firebase registration token
- Firebase rejects or expires the registered token
Prepare the Firebase project
Use the existing FF RESTaurent Google Cloud project so Cloud Run can authenticate with its service identity.
- Open the Firebase console.
- Select Add Firebase to Google Cloud project and choose the FF RESTaurent project.
- Register a Web app from Project overview.
- Copy
apiKey,projectId,messagingSenderId, andappIdfrom the Web app configuration. - Open Project settings, then Cloud Messaging.
- Enable the Firebase Cloud Messaging API (HTTP v1).
- Under Web Push certificates, generate a key pair and copy the public VAPID key.
The Firebase Web configuration and public VAPID key are client identifiers. Never expose a service-account private key through a VITE_ variable.
Enable the API with Google Cloud CLI if the console reports it as disabled:
$projectId = 'your_project_id_here'
gcloud services enable fcm.googleapis.com --project $projectId
Firebase documents the Web app registration, Web Push certificate, and FCM server environment procedures.
Configure the local web build
Vite reads the Firebase Web configuration at build time. Create apps/web/.env.local with these values:
VITE_API_URL=http://localhost:4000
VITE_FIREBASE_API_KEY=your_web_api_key_here
VITE_FIREBASE_PROJECT_ID=your_project_id_here
VITE_FIREBASE_MESSAGING_SENDER_ID=your_sender_id_here
VITE_FIREBASE_APP_ID=your_web_app_id_here
VITE_FIREBASE_VAPID_KEY=your_public_vapid_key_here
The repository ignores .env.local. Do not commit environment-specific values.
The service worker registers only in a production build. Build and preview the web app instead of using the Vite development server:
npm run build -w @ff-restaurent/web
Set-Location apps/web
npx vite preview --host 0.0.0.0 --port 5173
Open http://localhost:5173 after the preview server starts.
Configure the local API
The API reads FIREBASE_PROJECT_ID and uses Google Application Default Credentials (ADC) to send messages. Authenticate your local shell with Google Cloud CLI:
gcloud auth login
gcloud auth application-default login
gcloud config set project your_project_id_here
Add the Firebase project ID to the same PowerShell session that starts the API:
$env:FIREBASE_PROJECT_ID = 'your_project_id_here'
$env:DATABASE_URL = 'your_existing_database_url_here'
npm run dev -w @ff-restaurent/api
If ADC login is unavailable, store a service-account JSON key outside the repository and point the API process to it:
$env:GOOGLE_APPLICATION_CREDENTIALS = `
'C:\secure\firebase_service_account.json'
$env:FIREBASE_PROJECT_ID = 'your_project_id_here'
Do not commit the JSON key or copy it into the web application. Firebase recommends ADC for Google-hosted runtimes and documents local service-account authentication in the Admin SDK setup guide.
Verify push delivery locally
Use two accounts because product-event notifications exclude the actor.
- Apply the current Prisma migrations and start the API.
- Build and preview the web app at
http://localhost:5173. - Open the recipient account in Chrome or Edge.
- Reset the site's notification permission if the browser previously denied it.
- Open Profile, then Notification preferences.
- Enable Push alert for new restaurants or public Collections.
- Accept the browser permission prompt.
- Use another account to create a restaurant or publish a public Collection.
- Move the recipient tab to the background and confirm that the browser displays the notification.
- Select the notification and confirm that the application opens its internal target.
Inspect the database when you need delivery evidence:
PushSubscriptioncontains the Firebase token and member localeNotification.categoryidentifies the eventNotification.targetUrlcontains an internal application pathNotification.pushStatusrecordsNOT_REQUESTED,PENDING,SENT, orSKIPPEDNotification.pushAttemptedAtandpushSentAtrecord delivery timing
The API removes tokens that Firebase reports as unregistered.
Enable push delivery in production
Production requires both a configured web build and an authorized API runtime. The checked-in deployment workflow does not yet provide the required Firebase values.
Pass Firebase values into the web image
Add build arguments and matching environment assignments for these values in apps/web/Dockerfile:
VITE_FIREBASE_API_KEYVITE_FIREBASE_PROJECT_IDVITE_FIREBASE_MESSAGING_SENDER_IDVITE_FIREBASE_APP_IDVITE_FIREBASE_VAPID_KEY
Store the values as GitHub repository variables and pass them to the web image build in .github/workflows/gcp-deploy.yml. Vite embeds these values in the static assets, so changing them requires a new web build and deployment.
Configure the Cloud Run API
Set FIREBASE_PROJECT_ID on the API service. Keep service-account JSON keys out of Cloud Run because the Firebase Admin SDK uses the attached runtime service account through ADC.
Grant that runtime service account permission to send FCM messages:
$projectId = 'your_project_id_here'
$runtimeServiceAccount = `
'your_runtime_service_account@your_project_id_here.iam.gserviceaccount.com'
gcloud projects add-iam-policy-binding $projectId `
--member "serviceAccount:$runtimeServiceAccount" `
--role roles/firebasecloudmessaging.admin
Google documents the Firebase Cloud Messaging API Admin role and Cloud Run service identity behavior.
Complete the production smoke test
Do not mark production push as enabled until all checks pass:
- Confirm the deployed web assets contain the Firebase Web configuration.
- Confirm the Cloud Run API has
FIREBASE_PROJECT_ID. - Confirm the runtime service account has
roles/firebasecloudmessaging.admin. - Register a real browser from the production Profile page.
- Confirm the database contains its
PushSubscriptionrow. - Trigger an event from another member account.
- Confirm the in-app row exists even if browser delivery fails.
- Confirm successful delivery records
pushStatus = SENT. - Confirm the notification opens only an internal application URL.
Troubleshoot push delivery
Use the source row and browser state to isolate failures.
| Symptom | Check | Resolution |
|---|---|---|
| Browser reports denied permission | Site notification permission | Reset the permission, reload, and enable a push category from Profile again |
| Browser never asks for permission | Build mode and service worker | Use vite preview, confirm /sw.js is registered, and retry from a user action |
No PushSubscription row | Web environment and token registration | Confirm all five VITE_FIREBASE_* values and inspect browser service-worker errors |
Notification exists with SKIPPED | Subscription and API configuration | Confirm the member has a current token, FIREBASE_PROJECT_ID is set, and ADC can send messages |
API logs push_send_failed | FCM API and Identity and Access Management (IAM) | Enable fcm.googleapis.com and grant the runtime service account the FCM API Admin role |
| Actor receives no product notification | Audience rules | This is expected because restaurant and Collection events exclude the actor |
| Re-publishing a Collection sends nothing | Deduplication key | This is expected because one Collection publish event is delivered once |
| Token disappears after a send | Firebase token status | This is expected when Firebase reports the token as unregistered |
Push failures must not change the originating request result. Investigate warnings and delivery status without retrying the product action solely to force a push.
Review the implementation
Use these source files when changing the feature: