Manual for Bouncer 0.5.7. Chapters state version and distribution limits. Source cdd3b59, site build 20 November 2026. Your server or app may run an earlier version.
On this page
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.