Push notification relay for Bulwark Webmail. Terminates JMAP PushSubscription
pushes from the user's mail server and forwards them as Firebase Cloud
Messaging, Web Push or UnifiedPush pings so the
mobile app (or PWA) wakes up and fetches new mail over its own JMAP
connection.
Designed so self-hosters don't need their own Firebase project, a single hosted instance serves every Bulwark client that opts in. The relay never sees mail content: only push tokens and endpoints, JMAP ids, state strings, the label a client registered with, and timing.
| Method | Path | Purpose |
|---|---|---|
POST |
/api/push/register |
Mobile app stores its FCM token against an opaque subscriptionId |
POST |
/api/push/register/web |
PWA stores a Web Push subscription (endpoint + keys) against an opaque subscriptionId |
POST |
/api/push/register/unifiedpush |
Mobile app stores a UnifiedPush endpoint (endpoint + optional Web Push keys) against an opaque subscriptionId. Delivery is encrypted Web Push when keys are present (connector >= 3.0), a plain POST of the ping otherwise. Works without VAPID configured - distributors don't require it |
POST |
/api/push/register/apns |
iOS app stores its APNs device token (deviceToken + environment) against an opaque subscriptionId |
DELETE |
/api/push/register/:id |
Tear down mapping (logout / uninstall) |
GET |
/api/push/verify/:id |
Poll for the JMAP PushVerification code. It stays readable until the next registration replaces it |
GET |
/api/push/active/:id |
Liveness probe. { active: true } once the subscription has forwarded a push or its client picked up the verification code, and for 10 minutes after registering. 404 if unknown. Clients use it to reap dead leftover subscriptions without touching live ones |
POST |
/api/push/jmap/:id |
JMAP server posts PushVerification, StateChange or EmailPush (draft-ietf-jmap-emailpush) here, and the relay dispatches to the transport of the stored record. For EmailPush only the message ids are forwarded, never any other property the server included |
GET |
/api/push/vapid-public-key |
Returns the relay's VAPID public key so browsers can subscribe |
GET |
/api/health |
Liveness probe. Answers { ok: true } and nothing else; how many records there are is in /metrics |
GET |
/metrics |
Prometheus metrics, off by default. With METRICS_TOKEN set it wants Authorization: Bearer <token> and answers 401 without it; unset, it answers 404 |
Every register route answers 503 when the relay has no credentials for that
transport (except UnifiedPush, which needs none), 400 to a body it can't use,
413 to one over 64 KB, 429 past the limit per client address and 507 when
the store is full (see Limits). It answers 403 and 409 as described
under Record ownership. A wrong method on a known path
answers 405.
A record is named by its subscriptionId, which is the JMAP deviceClientId:
the mail server shows it to every client of the same user, and it is in the push
URL. For a record registered without a secret, knowing the id is enough to
replace or delete the record, read its verification code and post to it. Every
webmail and app released so far registers that way, and their records keep
working exactly like that.
A client can bind its record to a secret instead:
-
Registering. Each register route takes an optional
secretin the body: 32 to 128 characters ofA-Z,a-z,0-9,_and-, random and the client's own (32 random bytes in base64url are 43 characters). Asecretof any other shape answers400and stores nothing. The secret is bound when the id is first registered, and only to an id of 40 characters or more (32 random bytes in base64url again); the released clients' ids are 32 hex digits and never take one. A registration that brought a secret answers{ "ok": true, "owned": true }. An older relay ignores the field and answers{ "ok": true }, which tells a client its record there has no secret. A browser should then not send theAuthorizationheader to that relay, since an older relay's CORS answer doesn't allow it and the browser would block the request. -
Afterwards. A registration for that id needs the same
secretin its body, on any of the four routes, and may change the transport; without it, or with another one, it answers403and the record stays as it was.DELETE /api/push/register/:idandGET /api/push/verify/:idneedAuthorization: Bearer <secret>and answer403without it (a refused poll doesn't count as the code being collected).POST /api/push/jmap/:idneeds the record's push key in the query,?k=<push key>(below), and answers403without it, forwards nothing and stores no code.kgiven twice counts as missing; percent-encoding is decoded first. Each route looks in its one place only: the secret on the push URL, the push key in a header or in a registration, and the secret in the query of a DELETE all count as missing.GET /api/push/active/:idstays open, because other devices of the account ask it about ids that aren't theirs, and it only says yes or no. -
Push key. The mail server only has a URL, and it keeps that URL, so the URL doesn't carry the secret. It carries a push key the client derives from the secret, and the key lets its holder push and post a verification code, nothing else. The rule is fixed: the push key is SHA-256 over the ASCII bytes
bulwark-relay-push-key-v1:followed by the secret's, written in base64url without padding, 43 characters. The client hands the mail server.../api/push/jmap/<id>?k=<push key>as the PushSubscription'surl. The relay derives the same key from the secret at registration. Two values to check a client against:Secret Push key AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8(bytes 0 to 31)j5u1SE4uZtEqYP6s1cBnuAyp6AeXXZzlUO2d2N1yHX4-_64 timesNYzeMuKHzCMv54rOjyAWixIcpOUb6s7Otgp4-ONFwk8Where the push URL ends up: Stalwart doesn't return a PushSubscription's
urlto clients, but writes it, query and all, into its own log with every push event (push-subscription.successand.error). A proxy's access log holds it unless its format leaves out path and query (see Behind a reverse proxy). The legacy-proxy returns it to every other client of the same user, until it stops doing so. Whoever reads it can push to the record and post a verification code, and nothing more. -
409. A registration that brings asecretfor an id that exists without one, or for an id shorter than 40 characters, answers409and changes nothing. A client that wants a secret registers a new id with it. A record is never given a secret in place: otherwise anyone who knows an old client's id could delete its record and register the id again with a secret of their own, and the old client would be locked out of its id. -
Freed. When a record with a secret is deleted or expires, its id is free again, and the next registration decides, with or without a secret.
The relay stores a SHA-256 of the secret and one of the push key, never either value, and compares in constant time. It doesn't log a query string, and neither the secret, the push key nor their hashes go into the logs or into a metric.
Old and new together: a new client works with an older relay, which ignores the
unknown secret field, the header and the query, so its record just has no
secret there. The mail server posts to whatever URL it was given, query and all.
A record a new client made with a secret can't be registered by an older client
build on the same device (403) until it is deleted or expires; that only
happens after a downgrade.
What POST /api/push/jmap/:id answers decides whether the mail server tries
again. Stalwart tries a non-2xx answer again after a minute, 3 attempts by
default, merging whatever arrived meanwhile into one push.
| Push service said | Relay does | Answer |
|---|---|---|
| 2xx | 200 { ok: true } |
|
404, 410 (FCM UNREGISTERED, APNs Unregistered, BadDeviceToken, DeviceTokenNotForTopic) |
Deletes the record | 200 { ok: false } |
| 429, 408, 5xx, no answer within 8 s, network error, a name that resolves to no public address | Keeps the record | 503 { ok: false } (500 when FCM or APNs can't be reached at all) |
| Any other 4xx | Keeps the record, logs it | 200 { ok: false } |
Every push carries the same fields, whatever the transport:
| Field | What it holds |
|---|---|
kind |
jmap-email-push for an EmailPush, jmap-state-change for a StateChange |
accountLabel |
The label the client registered (on a UnifiedPush endpoint without keys only when it looks like a sign-in name, otherwise empty) |
accountId |
The JMAP account the push is about; of several in a StateChange, the one with new mail |
emailIds |
The new messages' ids, nothing else about them |
changed |
The accounts and states, in the shape of a StateChange, for clients that read only that |
sub |
Which registration the push is for: the first 16 bytes of SHA-256 over the subscriptionId, base64url (22 characters) |
A device with several registrations (two logins, or one browser with two
accounts on one endpoint) compares sub with the same hash of each of its ids.
The id itself never goes out: the push service reads FCM, APNs and plain
UnifiedPush payloads, and the id is what registers a record. Web Push and
UnifiedPush with keys get the fields as encrypted JSON, UnifiedPush without keys
as plain JSON, FCM as data strings (emailIds and changed JSON-encoded), and
APNs under body, next to a fixed "New message" alert. A push stays under 3,000
bytes: older ids are left out first, then accounts without new mail; the other
fields always stay. Clients ignore fields they don't know.
- Urgency, for Web Push and UnifiedPush. New mail goes out at high urgency, or
what the client asked for in its
emailPushconfig. A ping withEmailbut noEmailDeliverygoes at normal urgency, anything else at low. FCM and APNs always go at high priority. - Topic. Web Push pings for new mail in one account carry an RFC 8030
Topic, so a device that was offline gets the last one, not all of them.EmailPushpushes don't, since each names other messages. UnifiedPush gets no Topic. - Burst limit. Every subscription gets 10 pushes at once and one more every 20
seconds, whatever the transport, and every endpoint (or FCM or APNs token) 30 at
once and one more every 2 seconds, however many subscriptions share it (one per
account in a browser or app). Past that the relay answers
429without calling the service (held: "rate-limit"or"endpoint-rate-limit"), and the mail server's next attempt carries everything that piled up. An endpoint counts as one however it is written: the host in lower case and without a trailing dot, no default port; in the path, characters a path may hold written as%XXread as themselves, the hex digits of other%XXin upper case (%2Fstays apart from/), repeated slashes as one, no.or..segments, no trailing slash; no fragment. On FCM, Mozilla, Apple, ntfy.sh and Conversations' server, which keep the device in the path, none of the query counts, whatever it holds. Elsewhere only the value of atokenparameter counts when there is one (WNS, which Edge uses, Gotify and the UnifiedPush FCM distributor keep the device there): its name read decoded and in any case, and of two the first; without one all of the query counts, since a service the relay doesn't know may keep the device in another parameter. The same holds for a backoff. The endpoint is stored and called as the client registered it. - Backoff. After a
429, or any answer withRetry-After, the relay leaves that endpoint (or token) alone for as long as the service says (60 seconds without a header, an hour at most), for every subscription on it. Registering the same endpoint again doesn't end it; a new endpoint starts afresh. Stalwart gives up after about two minutes, so a longer wait costs the alerts in between: the service asked for it, and each one is in the log. At most 10,000 endpoints are remembered in backoff; past that the oldest backoff is dropped. - Host hold. After
429s for 20 different devices on one host within a minute, registered from at least 5 different client addresses (an IPv6 client counted by its /56, as under Limits), the relay leaves the whole host alone, for two minutes at most. Only devices that have delivered a push before count, a device is its endpoint without query and fragment, written one way as above, and browsers and native apps count separately. Devices whose client address the relay can't tell (see Limits), and records registered before its last start, count as one address together. Endpoints that differ only in their query (WNS, which Edge uses) count as one device per host and path, so they are held one by one. Held pushes count inrelay_pushes_held_total. The 20 isPUSH_HOST_THROTTLE_LIMIT, and the number of addresses is 5 or that setting, whichever is smaller: below 5 the hold asks for as many addresses as devices, so at 1 one device of one caller holds its host for everyone, even where addresses are unknown (they count as one).
The host hold needs client addresses: behind a reverse proxy, set TRUST_PROXY.
Without it every registration comes from the proxy's address, all devices count as
one address, and the hold never comes on; each endpoint still backs off on its own
when its service answers 429. Addresses are kept in memory only, so right after a
restart the hold counts a device's address only once its client has registered
again (every page load, every app start).
Only https URLs without credentials, on public addresses. Names without a dot,
.local, .internal and the like are refused at registration. A stored record with
such a name is deleted instead of called. What a name resolves to is checked on every
connection, and counts as a temporary failure when it isn't public. Redirects are not
followed, and only the first 4 KB of an answer are read. To reach a distributor
on your own network, name it in PUSH_ALLOW_PRIVATE_ENDPOINTS.
Per subscriptionId: an FCM token (Android app), an APNs device token (iOS
app), a Web Push subscription (endpoint + p256dh/auth keys for the PWA), or
a UnifiedPush endpoint (Android app without Google Play services), the
verification code, an optional free-form accountLabel (max 120 chars), the
SHA-256 of the record's secret and of its push key if it has one, and timestamps. No server URL, no
mail content.
Nothing else a client sends is kept. The endpoint is stored as the URL parser
writes it, up to 2,048 characters, and is refused (400) with a control
character, tab or newline anywhere in it. The keys are base64 or base64url of
exactly 65 and 16 bytes, with no other character. An FCM token is 64 to 2,048
characters (Firebase hands out about 160), an APNs token 64 to 200 hex digits. The
label is printable text, the verification code 1 to 512 printable ASCII
characters. A record takes at most 4 KB as JSON, a registration at most 3 KB of it;
real ones take a few hundred bytes.
The accountLabel is what the client sends, and Bulwark clients send the sign-in
name. It is stored here and copied into every push: encrypted to the device for Web
Push and UnifiedPush with keys, but readable to Google and Apple in FCM and APNs
payloads, and to the distributor on a UnifiedPush endpoint without keys. Whatever a
client registers is what goes to them. The relay never needs the label to be a
sign-in name: it only hands it back, so the client can tell which account a push
is for. A client can register any opaque text up to 120 characters instead, such
as a random value it keeps with the account, and match pushes by that; one of
letters, digits, _ and - also reaches a UnifiedPush device without keys. The
apps released so far pick the account by the sign-in name in the push, so the
relay passes on whatever label was registered, unchanged.
Subscriptions with no push and no registration for 90 days are evicted. One that never delivered a push and whose verification code no client picked up goes after 7 days without a registration; a real device registers again on every page load and app start. Expired records go at every start and within the hour while the relay runs.
The store is a snapshot, subscriptions.json in PUSH_DATA_DIR, and a journal
next to it, subscriptions.journal, which takes one numbered line per change, on
disk before the change is answered. A request that changes nothing (the same
verification code again, a push within a minute of the last) writes nothing. Once
the journal is larger than the snapshot (and at least 1 MB), and when the relay
stops, the journal is folded into a new snapshot that records the number of the
last change it holds. That one is written atomically, with the previous version
kept as subscriptions.json.bak. A crash at any point of a fold loses no change
that was answered: a start replays the journal's changes past the snapshot's
number. A journal only ever continues a snapshot with a number: on an older
relay's subscriptions.json, or an empty directory, the first change writes a
snapshot in this relay's form before the journal begins (the file is left as it is
until that change). A journal that doesn't continue the snapshot (one left from
before an older relay wrote subscriptions.json, which then has no number) is kept
as subscriptions.journal.stale-<time> with a warning, not replayed. A
change that can't be written is answered 500, is not kept, and counts in
relay_store_write_failures_total; a snapshot that can't be written is tried again
a minute later, while the journal keeps taking changes. The first one, on a store
without a number, comes before any journal: until it is written every change is
answered 500, and it too is tried at most once a minute. A snapshot that isn't
valid is kept as subscriptions.json.corrupt-<time> and logged as an error, and the relay starts
from the previous version. The journal is replayed onto that version only when it
continues it; a journal that continues the snapshot that isn't valid is set aside
as above, so every change since the previous version was written is lost, and
those records stay as the previous version has them until their clients register
again. A file that can't be read at all (permissions, a bad
mount) stops the relay at startup with an error, so it can't overwrite the store.
A relay that starts on the subscriptions.json of an older relay takes every
record from it.
One data directory takes one relay. Before it reads the store, a relay writes a
token of its own into subscriptions.lock, then refreshes the file's modification
time every fifth of PUSH_LOCK_STALE_MS (every 2 seconds by default), and removes
it when it stops cleanly. A start that finds a lock refreshed within
PUSH_LOCK_STALE_MS (10 seconds by default) doesn't start: it exits with an error
that says how many seconds ago the lock was refreshed, and by which process and
host. A lock that wasn't refreshed for longer is taken over, with a warning: its
relay was killed, crashed or lost its machine. Of two relays that start at the same
moment, one runs. A relay checks its token before every write and at every
refresh; when another token is there, because another relay took the lock over,
it writes nothing more and exits with an error. This works the same in containers
and under orchestrators that give each instance a new host name (Kubernetes,
Swarm), and on a directory several machines share, as long as their clocks agree
within a few seconds.
What that means after a crash: a relay restarted on the same directory waits until
the lock is stale. Docker's restart policy tries again after 0.1, 0.2, 0.4, ... seconds,
so with the default the relay is back after about 10 to 15 seconds; Kubernetes
retries after 10 seconds. Update strategies that start the new instance before
the old one stops (a Kubernetes RollingUpdate, Swarm's start-first) keep the new
one out until the old one is gone; use Recreate or stop-first. A clean stop
removes the lock at once. A relay that is paused (a suspended machine, a stopped
process, a stall) for less than PUSH_LOCK_STALE_MS carries on as before. Paused
longer, it carries on too if no other relay started meanwhile; if one did and took
the lock over, the paused relay stops at its next write or refresh, without
writing. Set the same PUSH_LOCK_STALE_MS for every relay that may use the
directory: a start judges a lock by its own setting.
Only the relay's user may read the store: the data directory is mode 700 and the store's files 600, and a start narrows what it finds wider (the directory with a warning in the log). The FCM and APNs key files are yours to keep at 600.
Registration needs no credential, so the relay bounds how many records it keeps and how fast one client address may add them. The defaults are far above what Bulwark clients send: a browser registers once per account and page load, an app once per account and start.
| Var | Default | What happens at the limit |
|---|---|---|
PUSH_MAX_SUBSCRIPTIONS |
50000 |
Records the store takes. A new subscriptionId past it takes the place of a record that gives way (below); when none may, it gets 507 {"error":"Relay is full"} and nothing is stored. An id that is there can always register again, be pushed to, polled and deleted. A warning is logged at most once a minute |
PUSH_MAX_SUBSCRIPTIONS_PER_ADDRESS |
1000 |
Records registered from one client address. A new subscriptionId from an address that holds as many gets 507 {"error":"Too many devices registered from this address"}; its existing devices register again as before. Off where the relay can't tell addresses apart (below) |
PUSH_REGISTER_BURST |
60 |
Registrations one client address may make at once, on the four register routes together. Past it: 429 with Retry-After in seconds, and nothing is stored or changed |
PUSH_REGISTER_REFILL_MS |
2000 |
Time until that address may make one more |
TRUST_PROXY |
0 |
Number of proxies in front of the relay, see below |
Who gives way when the store is full: first a record that never delivered a push
and whose verification code no client collected, the one registered longest ago;
then one that never delivered but whose code was collected (a device set up that
has had no mail yet), also the one registered longest ago; then the record whose
last delivered push is the oldest. Never one registered in the last 10 minutes (a
device in the middle of its setup), no record with a collected code while one
without is in those 10 minutes, and never one that delivered a push in the last 30
days. The new record is written before the one that gives way is deleted, so a write
that fails loses neither. When only the delete can't be written, both stay and the
store holds one record more than PUSH_MAX_SUBSCRIPTIONS; it stays that much over
until records leave (a client's delete, an expiry), since each new device after
that still takes the place of just one. A dropped device gets its record back the
next time its client registers (every page load, every app start), and counts in
relay_subscriptions_unregistered_total{reason="evicted"}. A push counts as
delivered when the endpoint answered 2xx; the relay can't tell a
real push service from an endpoint the registering client runs itself, so the
limit per address is what bounds records kept alive that way.
Which address records count for is the address of their last registration since the relay started; it is kept in memory only, never in the store, so after a restart a record counts for no address until its client registers again.
How large the store can get: 50,000 records of the largest kind the relay takes
(every field at its limit, the two hashes included) are 195 MB on disk. The
snapshot is read a line at a time, and a start that also folds a journal into it
peaks at about 215 MB of heap and 340 MB resident (measured with Node 22 on Linux,
--max-old-space-size=256, which gives V8 304 MB in all). That start is the peak:
a fold while the relay runs writes the records it holds 500 at a time, so it needs
little beyond them. Real records are a few hundred bytes, so a full
store of real devices is a tenth of that. Give the container memory for the store
and Node besides; a
subscriptions.json written by an older relay is read whole once, which takes
about four times its size.
Which address a registration counts for:
- With
TRUST_PROXY=0the client address is the socket's. Without a proxy in front, the relay sees IPv6 clients only when it listens on an IPv6 address (HOST; the default0.0.0.0takes IPv4 only), and they count by their /56 there too. - With
TRUST_PROXY=1it is the last entry ofX-Forwarded-For, the one the proxy appended; whatever the client wrote in front of it is ignored. With2it is the second from the end, and so on. A request without the header counts by its socket. - A port after the address is ignored. An IPv4 client counts by its address, an IPv6 client by its /56, since providers hand a customer a /56 or a /48: all the /64s in one /56 are one client, for the rate, the records per address and the host hold. An entry that is no address at all counts for one budget shared by all such entries.
- When the address is a loopback, private, shared (100.64/10) or link-local one
the relay can't tell its clients apart, and one budget for all of them would
refuse real devices. That is the proxy's own address with
TRUST_PROXY=0behind a proxy, and the entry the trusted proxy appended when yet another proxy stands in front of it (thenTRUST_PROXYis one too low). Then neither the rate nor the count per address applies, onlyPUSH_MAX_SUBSCRIPTIONS, and the relay logs once, as a warning, thatTRUST_PROXYshould be set. The proxy has to set or appendX-Forwarded-Foritself; withTRUST_PROXY=2and more, each proxy must be the only way to the next.
What the clients do with the answers: the webmail reports "Relay register failed:
429" (or 507) and tries again on the next page load, or when an open tab comes to
the front 15 minutes later or more. The app reports "The push relay rejected the
registration" and tries again at its next start. Neither retries at once, and a
device that is registered already keeps getting its pushes. The mail server sees
no change.
docker-compose.yml publishes the port on 127.0.0.1 for a proxy on the same
host. Have the proxy send the client address and set TRUST_PROXY=1, and limit the
register routes there as well, as the first line of defence. For nginx:
# http block: per client address, 30 a minute, bursts of 60, like the relay's own limit
limit_req_zone $binary_remote_addr zone=relay_register:10m rate=30r/m;
server {
# ...
location /api/push/register {
limit_req zone=relay_register burst=60 nodelay;
# 429 like the relay: the iOS app reads a 503 as "this relay has no APNs"
limit_req_status 429;
proxy_pass http://127.0.0.1:3003;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
location / {
proxy_pass http://127.0.0.1:3003;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}The prefix also covers DELETE /api/push/register/:id, which a client sends once
on logout.
Two things about nginx's own limit. Its 429 carries none of the relay's CORS
headers, so a browser sees a network error instead ("Could not reach the push
relay" in the webmail), which the webmail retries the same way as a 429, at the
next page load. And a browser's preflight OPTIONS before a registration (when it
has none cached) counts against the zone too, so the zone runs out up to twice as
fast as the relay's own budget. nginx doesn't count a request whose key is empty,
so to leave preflights out, key the zone on a map that is empty for OPTIONS:
# http block, instead of the limit_req_zone above
map $request_method $relay_register_key {
OPTIONS "";
default $binary_remote_addr;
}
limit_req_zone $relay_register_key zone=relay_register:10m rate=30r/m;Keep the subscription ids and secrets out of the proxy's access log. nginx's
default combined format writes the whole request line, and for /api/push/ that
is the id in the path and, on the push URL, the record's secret in the query.
Log those requests without the path and the query, or not at all:
# http block
log_format relay_push '$remote_addr [$time_local] "$request_method" $status $body_bytes_sent $request_time';
server {
# ...
location /api/push/register {
access_log /var/log/nginx/relay-push.log relay_push;
# ... limit_req and proxy_pass as above
}
location /api/push/ {
access_log /var/log/nginx/relay-push.log relay_push; # or: access_log off;
proxy_pass http://127.0.0.1:3003;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}nginx's error log still quotes the request line when it can't reach the relay, so keep it readable to the operator only.
Requests by route, status and duration, with a short hash that follows one subscription through the logs. Failed forwards also log the push service's host, status and its reason, with any URL in it removed. Never the subscription id, a query string, a record's secret or its hash, an endpoint path, keys, tokens or the label.
npm install
echo '{...}' > data/fcm-service-account.json # Firebase service account JSON
npm run devmkdir -p data
cp path/to/fcm-service-account.json data/
docker compose up -dThe container runs read-only, without capabilities and with no-new-privileges:
the relay can write the data volume and /tmp, nothing else, and its own code
belongs to root. The data directory on the host has to be writable for the
container's relay user.
It joins the external bulwark network, through which Prometheus scrapes
/metrics. Every container on that network reaches port 3003 directly, without
the reverse proxy and its limits; requests from there come from a private address
and get no limit per client address (see Limits). Keep only trusted
containers on it.
An older relay reads subscriptions.json and ignores subscriptions.journal, so
stop this one cleanly first: docker compose stop sends SIGTERM, the relay waits
for a push still on its way (up to PUSH_FORWARD_TIMEOUT_MS and a second), folds
the journal into subscriptions.json and removes it. The compose file gives it 30
seconds for that. Then check that data/subscriptions.journal is gone before you
start the older image. If it is still there (the stop was cut short, or the log
says "stopped with changes left in subscriptions.journal"), start this version
again and stop it again. Coming back to this version later is safe either way: a
journal always continues a snapshot with a number, and the older relay writes
subscriptions.json without one on every change it makes, also on one it undoes
again. So once the older relay has changed anything, the journal is set aside as
subscriptions.journal.stale-<time> and what the older relay wrote stands. The
changes in that journal, which the older relay never saw, are not applied; those
devices get their records back when their clients register again. If the older
relay changed nothing, subscriptions.json is still this version's and the
journal is replayed as after any unclean stop.
A relay from before record ownership (see Record ownership)
keeps a record's secret while it doesn't touch the record, but writes the record
without it at that client's next registration. Back on this version, such a
record has no secret any more, and its client's next registration with the secret
answers 409; the client then registers a new id, as for any 409.
| Var | Default | Notes |
|---|---|---|
PORT |
3003 |
HTTP listen port |
HOST |
0.0.0.0 |
|
PUSH_DATA_DIR |
./data |
Where the store (subscriptions.json and its journal) and the FCM key live |
FCM_SERVICE_ACCOUNT_JSON |
unset | Either the full JSON inline or an absolute path; falls back to $PUSH_DATA_DIR/fcm-service-account.json |
VAPID_PUBLIC_KEY |
unset | Base64url-encoded P-256 public key for Web Push. Generate with npx web-push generate-vapid-keys |
VAPID_PRIVATE_KEY |
unset | Matching private key. Web Push is disabled if either VAPID var is missing |
VAPID_SUBJECT |
mailto:postmaster@localhost |
mailto: or https: contact the push services can reach if the relay misbehaves (RFC 8292) |
APNS_KEY_ID, APNS_TEAM_ID |
unset | APNs signing key id and team id. APNs is disabled if either is missing |
APNS_KEY |
$PUSH_DATA_DIR/apns-key.p8 |
The .p8 key, inline PEM or a path |
APNS_TOPIC |
org.bulwarkmail.mobile |
Bundle id of the app |
PUSH_ALLOW_PRIVATE_ENDPOINTS |
unset | Comma-separated hosts that may be called even though they aren't public, such as your own ntfy |
PUSH_FORWARD_TIMEOUT_MS |
8000 |
How long one attempt at a push service may take, start to finish. Keep it below the mail server's own timeout (Stalwart: 10 s), or the same push goes out twice |
PUSH_SUBSCRIPTION_BURST |
10 |
Pushes one subscription may get at once, any transport. Past it the mail server gets 429 |
PUSH_SUBSCRIPTION_REFILL_MS |
20000 |
Time until one more is allowed |
PUSH_HOST_THROTTLE_LIMIT |
20 |
Devices that delivered before getting a 429 from one host within a minute before the whole host is left alone. They must come from 5 client addresses, or from this many when it is below 5 |
PUSH_MAX_SUBSCRIPTIONS |
50000 |
Records the store takes; a new device past it takes the place of one that never delivered, or gets 507. See Limits |
PUSH_MAX_SUBSCRIPTIONS_PER_ADDRESS |
1000 |
Records one client address may hold; a new device past it gets 507. Off where addresses can't be told apart |
PUSH_REGISTER_BURST |
60 |
Registrations one client address may make at once; past it 429 with Retry-After |
PUSH_REGISTER_REFILL_MS |
2000 |
Time until that address may make one more |
PUSH_LOCK_STALE_MS |
10000 |
How long the data directory's lock may go without a refresh before a start takes it over (at least 1000); the holder refreshes it every fifth of this. See What it stores |
TRUST_PROXY |
0 |
Proxies in front of the relay. With 1 the client address is the last entry of X-Forwarded-For |
METRICS_TOKEN |
unset | Turns on /metrics. Prometheus sends it as a bearer token (authorization: { credentials: <token> } in the scrape config) |
METRICS_TOKEN_FILE |
unset | Path to a file holding the token instead, read on every scrape |
FCM_ORIGIN, APNS_ORIGIN |
the real services | Point every push at another server, for tests |
Licensed under the GNU Affero General Public License v3.0 only. See LICENSE.