Push notifications
Push wakes a phone when a request arrives. Without push, Bouncer still works: the apps see every request whenever they're open. Push is off until you turn it on.
What a push contains
Bouncer sends pushes through Firebase Cloud Messaging (FCM), Google's push service. FCM is not end-to-end encrypted, so a push carries only an event ID, never a name, resource, reason, duration or credential:
{"v": "bouncer.v1", "event_id": "evt_01jbx3k9n3q5s7t9v1w3x5y7z9"}
The phone wakes, fetches the details from your Bouncer server with its device token, and builds the notification itself. If it can't reach your server, it shows a generic notification instead.
Only three kinds of event are pushed: a new request, a request that closed (so the phone can take the notification down), and a new device paired to the same person. The others (a grant revoked, a grant suspended, a policy loosened) are seen when an app next looks.
What each platform gets
| Platform | Push |
|---|---|
| Android | FCM, with the event ID only |
| iOS | FCM, delivered through Apple's push service. The alert text is fixed ("Open Bouncer to check your inbox."); the app fetches the details when it's opened |
| Windows | No remote push. The Windows app follows events only while it or its tray icon is running. Nothing arrives while it's closed |
Push works only with app builds made for the Firebase project your server sends to. Each app build carries one Firebase project's settings, and a phone's push address belongs to that project only. What matters is the target project, fcm.project_id: the server sends through that project, with a service-account key that is allowed to send for it. Usually the key comes from the same project, but a service account can also be given permission to send for another one.
So, for the apps your people install:
- The official builds, the ones the Bouncer project makes and hands out, carry the Bouncer project's own Firebase settings. Your server can push to them only with a service-account key for that project. This guide doesn't cover getting one; ask whoever gave you access to Bouncer. Without it, leave push off: the apps still work, and see requests whenever they're open.
- Apps you build yourself can carry your own Firebase project's settings (the repository's
app/lib/push/firebase_config.dartsays how). Then use a key from your own project, as below.
To move phones from one Firebase project to another, the server can send through more than one project: see push.fcm_also in the config reference.
Turn push on
You need a Firebase project and its service-account key file, a JSON file you download from the Firebase console under Project settings, Service accounts. The key file is a secret: it lets anyone send pushes as your project. Keep it out of chat, Git and backups that aren't encrypted.
-
Put the key file on the server, readable only by the server's user:
sudo install -m 0400 -o 10001 -g 10001 ./service-account.json /etc/bouncer/secrets/fcm-service-account.json shred -u ./service-account.json -
In
/etc/bouncer/config/bouncer.yaml, replacepush: nullwith:push: fcm: project_id: example-firebase-project service_account_file: /run/secrets/fcm-service-account.json -
In
deploy/compose/.env, add the push compose file, which mounts the key file:COMPOSE_FILE=compose.yaml:compose.push.yaml -
Recreate the container, so it gets the new secret file, and check the log:
docker compose up -d --wait --wait-timeout 120 docker compose logs bouncerWait for the command to succeed before testing push. If it fails or times out, inspect the log and fix the start-up fault first.
A key file that is missing or isn't a service-account key stops start-up, with a message naming the file. Its contents are never shown.
Expected result: when a request arrives, each push sent leaves a log line push sent with the event ID, the device ID, the Firebase project and the delay. The log never holds a phone's push token or the key.
To turn push off again, set push: null and run docker compose exec bouncer bouncer-admin config reload.
If a bad key prevents start-up, set push: null, remove compose.push.yaml (and compose.push2.yaml, if present) from COMPOSE_FILE, then run the Compose start command again. Fix the key before enabling push again.
Moving to another Firebase project
fcm_also needs server build 0.3.8+25 or later.
A phone's push token belongs to the Firebase project in its app build. If you move to a new project while some phones still have the old build, list both: the new one under fcm, the old one under fcm_also, each with its own key file (and add compose.push2.yaml to COMPOSE_FILE for the second file). Bouncer tries them in order. When no push sent line names the old project any more, remove fcm_also. The repository's deploy/compose/README.md has the step-by-step version.
Limits
- If a phone is offline while five or more requests are pending, FCM may drop the pushes for some of them. The requests are still in the app's inbox.
- Pushes are retried for a while if FCM is busy, and given up at the request's deadline.
- A failed push never approves or denies anything.
How this was checked
Not verified for this page. Our test run had push turned off, because it needs a real Firebase project and key. The behaviour above comes from the server source (server/src/push.rs) and its tests, which run against a fake FCM.