Skip to content

FreeSpeech Push Gateway 1.5.0

Choose a tag to compare

@rebisway rebisway released this 12 Nov 10:26
· 4 commits to main since this release

The push gateway wakes the phones of FreeSpeech users when a message waits for them. It is the only component that holds the Firebase (FCM) and Apple (APNs) keys. A relay calls it to wake a phone; the gateway receives neither identity nor content, and the notification itself never carries the text of a message. A gateway with no linked relay refuses every request.

Who needs it

Most relay administrators do not need to install a gateway. Two are available free of charge: https://push1.rebisway.com and https://push2.rebisway.com. To use one, link your relay to it (see below); its administrator checks who asks and accepts the link. Installing your own gateway is for those who run their own Firebase project, for instance with an application they build themselves.

What this gateway does

  • It receives signed wake-up requests from the relays linked to it and passes them to Firebase.
  • A relay is linked only by keys and the agreement of both administrators (requests / accept); no secret is shared between servers.
  • It checks the link with each relay every minute (peer-check sets the interval) and raises an alarm after three failed checks. peers shows the state of each link.
  • Several gateways can serve the same relays (load, failure): the relay switches by itself and sets aside a failed or saturated gateway for a few tens of seconds. Push:MaxConcurrent (default 100) limits the simultaneous requests of one gateway.
  • Everything is set without a restart with the admin command, including e-mail notifications.

What you need

  • A Debian 12/13 or Ubuntu 22.04/24.04 machine, with sudo.
  • A domain name whose DNS points to the machine, and ports 80 and 443 reachable.
  • A Firebase project with the Android application org.freespeech.mobile and the Firebase Cloud Messaging API (V1) enabled, and a service-account key file (Firebase console > Project settings > Service accounts > Generate new private key). Keep this file on the gateway only, never in a repository.
  • A relay to link (see below).

Installation

The archive holds the program, the systemd service, an nginx example and the install.sh script. The .NET runtime is installed by the script.

sha256sum -c --ignore-missing SHA256SUMS
tar -xzf freespeech-push-1.5.0.tar.gz
cd freespeech-push-1.5.0
sudo bash install.sh push.example.org --email admin@example.org

The script installs the packages, opens the firewall (SSH, 80, 443), installs the service, writes appsettings.Local.json with a randomly drawn admin secret, sets up nginx and the certificate, then runs check. --email is the address Let's Encrypt keeps for expiry notices: giving it accepts its subscriber agreement. Other options: --contact, --no-certificate, --no-firewall.

The Firebase key file is not in the archive. Until it is in place, check fails and the service is not started. Put it in /var/www/freespeech_push/secrets/firebase-service-account.json (owner www-data, mode 600), then:

sudo systemctl start freespeech-push

Link a relay to a gateway

On the relay: admin add push https://push1.rebisway.com (or push2, or your own gateway). The gateway's administrator sees your request with the name, address and fingerprint of your relay, and accepts it after checking who asks: give a way to reach you with --contact when you install the relay, or set Peer:Contact in its appsettings.Local.json. The relay knows within a minute (admin list push). Linking to both public gateways lets the relay switch by itself if one fails.

On your own gateway, the administrator reads the requests and accepts:

fspush requests
fspush accept <id>

Compare the fingerprint with the one the relay's administrator reads before accepting.

Update

Install the recent applications first, then run install.sh again with the newer archive, giving the same domain and e-mail address: the program is replaced, appsettings.Local.json and the secrets folder are never rewritten.

Other systems

The installation script and the guide cover Debian and Ubuntu. The program itself is portable .NET 10 and runs wherever the ASP.NET Core 10 runtime does (Windows, macOS, other Linux distributions, x64 and ARM): extract the publish folder, write appsettings.Local.json, run dotnet FreeSpeech.Push.dll check, then run the gateway behind an HTTPS reverse proxy. These setups are not documented here and are not tested.

Backup

/var/lib/freespeech-push/peer-identity.json (the gateway's key: losing it means linking each relay again), peers.json and settings.json, mode 600; and /var/www/freespeech_push/appsettings.Local.json with secrets/.

Documentation

  • Step-by-step installation, manual included: INSTALL_PUSH.en.md
  • Gateway commands: cli-push.en.md
  • How it works: HOW_IT_WORKS.en.md, protocol: PROTOCOL.en.md section 9

Licence AGPL-3.0-or-later. Source code: https://git.rebisway.com/rebisway/freespeech