On this page
Running gnotifd
gnotifd is the gnotif server, the program behind gnotif.xyz: one binary that keeps its state in one SQLite file. It needs a tx-indexer for the chain, the package path of the gnotif registry, and a VAPID key pair to sign its pushes.
gnotifd serves only the HTTP API, under /v1/ at its root; to serve it under a path, such as /onyx/, strip that path in front of gnotifd. Dapps serve their own pages.
Install
With Go 1.27 or later:
go install github.com/gfanton/gnotif/cmd/gnotifd@latest
Or run the container image.
Make the VAPID keys
gnotifd signs every push with a VAPID key pair. Make the pair once, in a file that only you can read:
touch vapid.env
chmod 600 vapid.env
gnotifd keygen > vapid.env
> writes into the file that already exists and keeps its mode, so only you can read the private key.
The file holds two lines, the environment variables gnotifd reads the pair from:
GNOTIF_VAPID_PUBLIC_KEY=...
GNOTIF_VAPID_PRIVATE_KEY=...
Load them into the terminal you start gnotifd from:
export $(cat vapid.env)
Warning
A new key pair stops every push until each page calls
enable()again, since a push service accepts only pushes signed with the key the subscription was made with. Keep the pair for the life of the server, keep the private key secret, and keepvapid.envoutside any source checkout.
Start gnotifd
Start gnotifd on onyx's public indexer, following the registry from its v0:
gnotifd -indexer https://indexer.onyx.testnets.gno.land/graphql/query \
-registry gno.land/r/nym-gfanton001/gnotif/v0 -start-height 256562 \
-vapid-subject <contact>
<contact> is an email address or https URL where push services can reach you, such as ops@example.org.
gnotifd listens on 127.0.0.1:8080 and writes gnotif.db in the current directory. It logs to standard error. Stopping it with Ctrl-C or SIGTERM writes the pushes it still holds in memory to the database before it exits; a hard kill loses them (How gnotif works).
Dapp pages call gnotifd from their own origins, and a page served over https cannot call a plain http URL on another host, so put gnotifd behind a reverse proxy that terminates TLS.
Flags
gnotifd takes these flags:
| Flag | Default | Meaning |
|---|---|---|
-indexer |
required | tx-indexer GraphQL URL |
-registry |
required | package path of the gnotif registry realm, ending in /v<N> |
-vapid-subject |
required | email address or https URL where push services can reach the operator |
-start-height |
none | height to read from on the first start, at or before the registry's deploy |
-listen |
127.0.0.1:8080 |
HTTP listen address |
-db |
gnotif.db |
SQLite database file, or the http:// or https:// URL of a remote store |
-poll |
5s |
indexer poll interval; must be positive |
-max-age |
10m |
oldest event that still sends a notification; must not be negative |
-push-hosts |
the four hosts in the allowlist | comma-separated push service hosts |
-stream-max |
0 |
most live connections held at once; 0 turns live connections off |
-hub-listen |
none | address of the external hub listener |
-publish |
none | URL receiving each window's matches for an external hub |
gnotifd -h prints the flags with their defaults. Durations take Go's syntax, such as 30s, 10m or 1h. The VAPID keys come only from GNOTIF_VAPID_PUBLIC_KEY and GNOTIF_VAPID_PRIVATE_KEY, the publish token only from GNOTIF_PUBLISH_TOKEN, and every other setting only from flags.
The indexer and the start height
-indexer is the GraphQL URL of a tx-indexer that reads the chain. onyx's public indexer answers at https://indexer.onyx.testnets.gno.land/graphql/query. gnotifd sends it one request per poll, so -poll sets the load. While it reads a block too large to read whole, a poll sends one request per transaction in that block.
-registry is the path the registry is deployed at. It ends in /v<N>, with no leading zero, such as gno.land/r/nym-gfanton001/gnotif/v0. gnotifd builds its triggers from that version's events and from every later version under the same prefix, never from an earlier one. A server set to v0 follows v0 and v1. To stop following an older version, start a new database at the later version.
-start-height matters only while the database is empty: the first start reads the chain from that height, and gnotifd refuses to start without it. Later starts resume where the database stopped and ignore the flag.
Use a height at or before the deploy of the configured version. Registry v0 was deployed on onyx at height 256563, so the examples use 256562. Deploying the registry notes the indexer's height right before the deploy for this. A height far below the deploy only costs time (How gnotif works).
While it catches up, gnotifd skips realm events older than -max-age, so a restart after downtime sends no burst of stale notifications. It always applies the registry's events. Against a chain that makes blocks only on transactions, such as a local gnodev, raise -max-age, to 1h for instance: the first block after a quiet spell can carry an old time.
When the indexer reports a height below what gnotifd already stored, gnotifd logs indexer behind stored bound on every poll until the indexer catches up, and waits for it. That happens when the indexer re-syncs from scratch, or when several indexers answer behind one URL.
gnotifd skips a transaction it cannot process whole, and logs skip oversized transaction as an error, with its height, index and hash. That happens when the indexer's answer for the transaction is too large to read, or, with a remote store, when committing it takes more than 1,000 statements, about one per event that matches a trigger. Its events are lost, and every other transaction is read. When the lost events declared or removed a trigger, gnotifd's triggers no longer match the registry's.
The push service allowlist
gnotifd sends a request to every endpoint it stores, so it accepts a subscription only when the endpoint is an https URL on a known push service. The default list:
| Host | Push service |
|---|---|
fcm.googleapis.com |
|
updates.push.services.mozilla.com |
Mozilla |
web.push.apple.com |
Apple |
*.notify.windows.com |
Microsoft |
An entry *.suffix matches any host under suffix on the default port. Any other entry must equal the endpoint's host, port included. Case does not matter. -push-hosts replaces the whole list, so repeat the defaults you keep.
Storage and backups
With a file, the database is one SQLite file in WAL mode: while gnotifd runs, gnotif.db sits next to gnotif.db-wal and gnotif.db-shm. Stop gnotifd before copying the database, and copy any -wal or -shm file left beside it.
The subscriptions and opt-ins exist only in the database. To start a new database, name a new file or an empty remote store with -db and give a -start-height at or before the registry's deploy; each browser then turns notifications on again from its dapp's page. Start a new database when:
- the database is lost;
- gnotifd's
-registrychanges, to another registry or another version: the old triggers and opt-ins would stay, and an earlier version's removals would stop applying; - gnotifd refuses the database with
database was made by an older gnotifd: an older release made it, before a change to the database's layout.
gnotifd also refuses a database made by a newer release, with database was made by a newer gnotifd. Run the release that made it instead, since a new database drops every subscription. A refused database is left untouched.
Remote store and external hub
Two services can run beside gnotifd. A remote store holds its database, at the URL -db names in place of a file. An external hub holds its live connections, attached with -hub-listen and -publish. Protocols gives the contract each one speaks. Keep the store and gnotifd's -hub-listen listener off the public network: anyone who reaches the store can read, change or drop every subscription.
Run the container image
Build the image from a checkout:
docker build -t gnotifd .
Print its flags to check it:
docker run --rm gnotifd -h
A release tag vX.Y.Z also publishes ghcr.io/gfanton/gnotifd:X.Y.Z, built for linux/amd64.
The image runs a static gnotifd as a non-root user, with -db /data/gnotif.db -listen 0.0.0.0:8080 by default and a volume at /data. Arguments to docker run replace those defaults, so pass -db and -listen again with your flags:
docker run -d --name gnotifd -p 127.0.0.1:8080:8080 -v gnotif-data:/data --env-file vapid.env \
gnotifd -db /data/gnotif.db -listen 0.0.0.0:8080 \
-indexer https://indexer.onyx.testnets.gno.land/graphql/query \
-registry gno.land/r/nym-gfanton001/gnotif/v0 -start-height 256562 \
-vapid-subject <contact>
--env-file reads the vapid.env that gnotifd keygen wrote.
What version 0 leaves to the operator
gnotifd version 0 has no health endpoint, no abuse limits and no metrics. Cover each yourself:
- Health: there is no health endpoint.
GET /v1/vapidanswers while the HTTP server runs, but says nothing about the watch loop: watch the log forwatch tick failed. - Abuse limits: gnotifd has no caps per IP and no send budget per declarer. Anyone can register subscriptions and opt-ins, and a subscription stays until its page deletes it or a push to it comes back expired.
-stream-maxcaps live connections in total, not per client. Rate-limit/v1/at the reverse proxy. - Monitoring: there are no metrics, only the log. gnotifd logs nothing for a push it sent, nor for a retry after a 429 or 5xx answer. It logs a network failure and a push dropped after a day as warnings, a push the service rejected as an error, and an expired subscription at info level. A live connection refused at
-stream-max, and one dropped for reading too slowly, are logged as warnings, and a live opt-in set it refuses at info level, with the reason and the number of opt-ins.