uniqush-push: APNs, FCM and Web Push from One Go Server

The Cross-Platform Notification Problem uniqush-push Addresses

uniqush-push addresses the server-side fragmentation created by vendor-specific push APIs. An application may need to reach iOS through APNs, Android through FCM, Kindle devices through ADM, and browsers or de-Googled systems through Web Push or UnifiedPush. Without an intermediary, each destination introduces a separate protocol, credential format, response model and maintenance burden.

The project places those systems behind the `uniqush-push` REST API and stores device subscriptions in Redis. It is aimed at server operators who already handle application delivery infrastructure, rather than developers seeking a hosted push dashboard. A user still needs accounts or credentials for the relevant vendors, working client applications that register subscriptions, and procedures for deciding what notifications to send.

This boundary matters because a push server holds routing data and provider credentials while also accepting delivery requests. The default REST frontend listens on `localhost:9898`. According to the README, the API has no authentication, and reaching `/addpsp` can change where a service sends pushes. Public exposure therefore needs an authenticated reverse proxy or another explicit access-control layer. The documented default keeps that control problem away from an open network interface, but it also means a local integration must still be able to call the service.

Redis Storage, Provider Backends and Request Flow

Based on the repository layout, the main server logic is divided into REST handling, persistence, delivery and provider-specific packages. Top-level files such as `restapi.go`, `pushbackend.go`, `metrics.go` and `configparser.go` connect the frontend to shared push and configuration behavior. The `srv/` directory contains service implementations, while `db/` handles Redis-backed state. This structure gives each push vendor a separate backend rather than combining all protocols in one request handler.

Subscriptions are the core persisted records. The README states that every subscription lives in Redis and warns that Redis snapshots only periodically by default. Losing those records would force clients to subscribe again and could interrupt notification routing until registration completes. A replica may receive read traffic through `slave_host` and `slave_port`, while the main Redis connection is configured under `[Database]` with `host`, `port` and `password`.

Provider configuration is added through `/addpsp`. APNs supports certificate authentication and `.p8` token authentication. For token authentication, the documented fields are `authkey`, `keyid` and `teamid`. FCM moved from its legacy endpoint to HTTP v1 and now accepts `projectid` and `credentialsfile`; `gcm` is an alias for that backend. The README also documents `replace=true` when migrating an existing APNs certificate service to token authentication, with subscriptions retained. Removing the old service is not the documented migration path because rebinding has separate behavior in `docs/delivery-point-rebinding.md`.

The Dockerfile confirms that the binary is built with `CGO_ENABLED=0`, uses CA certificates from the builder image and starts as user `65534:65534`. Its scratch image listens on port `9898`, but the README still advises against treating that container behavior as permission to publish an unauthenticated API.

Building uniqush-push and Starting Its First Local Server

The README requires Go 1.26 or newer and Redis. Build the server directly from the repository. A successful build leaves the `uniqush-push` binary in the current directory.

git clone https://github.com/uniqush/uniqush-push.git
cd uniqush-push
go build

Copy `conf/uniqush-push.conf` to `/etc/uniqush/uniqush-push.conf`, which is the default location, or pass another path with `-config`. Before startup, confirm that Redis is reachable and has persistence enabled. The server also needs at least one configured push service provider before it can deliver useful notifications.

Start the binary and query its version endpoint from another terminal. The version request uses the stock local address; a nondefault configuration must match its `[WebFrontend] addr` setting.

uniqush-push
curl http://localhost:9898/version

The `.deb` and `.rpm` packages install a systemd unit but do not enable it. Once Redis and a provider are configured, the documented commands start the service and show its status.

systemctl enable --now uniqush-push
systemctl status uniqush-push

For package-managed installations, use `systemctl edit uniqush-push` for local service changes. The README specifically warns against editing the unit directly because a package upgrade replaces it. Source and tarball installations do not receive a working systemd unit automatically.

Choosing the Correct APNs and FCM Configuration

The 2.9.x line represents a substantial compatibility repair after the project was dormant from 2020 through 2026. Release 2.8.0 changed APNs to the HTTP/2 API by default and added the `apns-push-type` header required by iOS 13 and later. The README says earlier releases could not deliver because Apple switched off the binary protocol on 2021-03-31. An installation using one of those older releases should not be treated as equivalent to the current APNs behavior.

APNs token authentication requires three values when adding the push service provider: `authkey`, `keyid` and `teamid`. An existing certificate-based provider should be migrated with `replace=true` if subscriptions are to remain attached to the delivery point. The README explicitly says not to use `/rmpsp` for that transition. Complete device delivery still requires paid Apple Developer Program membership. The local APNs conformance suite can exercise the HTTP/2 contract against a simulator, but the project states that it cannot establish delivery to a physical Apple device without the required account.

FCM now uses HTTP v1. The legacy endpoint was decommissioned on 2024-06-20, so older credentials or configuration based on an API key will not match the current setup. Configuration uses `projectid` and `credentialsfile`. The README reports confirmed browser delivery against a real Firebase project on 2026-09-01 and says devices do not need to resubscribe after migration. Android delivery had not yet been checked at publication, which makes the `android` path a specific verification gap.

`go.mod` requires Go `1.26.0`. The Dockerfile uses a Go 1.27 builder, but the README's stated minimum for building remains Go 1.26 or newer. For release-specific migration steps, the project directs users to `docs/upgrading.md` rather than suggesting that every upgrade is configuration-compatible.

Web Push Credentials and the Limits of Provider Coverage

Web Push is the backend with no vendor service dependency according to the README. It supports browsers and is also associated with UnifiedPush, de-Googled Android and Linux desktop use. Provider setup begins by generating a VAPID key pair. This command prints the generated pair and exits without starting the server.

uniqush-push -generate-vapid-keys

The repository includes `examples/webpush-demo/` and `examples/unifiedpush-demo/`, which are more appropriate starting points than the general tests when the immediate goal is to inspect a client-server flow. The repository also includes `examples/fcm-demo/` for the current FCM configuration.

Provider support should not be read as equal verification. The README says FCM was checked against Google, including browser delivery. It describes APNs work as repaired and verified as far as possible without a paid Apple account. ADM is believed to work but has not been re-verified. Web Push and UnifiedPush are described as new. No documentation excerpt establishes current coverage for every possible client, browser, payload size, authentication mode or vendor edge case.

The appropriate alternative depends on the required destination. Calling each vendor SDK directly avoids maintaining a central subscription store and provider abstraction, but the application then owns each vendor protocol and error model. A hosted notification service can reduce server administration, although it introduces an external dependency not described by this repository. uniqush-push is more relevant when one application-facing subscription layer and a self-hosted Redis-backed deployment justify operating the abstraction.

For operations, Go's `go test ./...` command runs the repository tests, including the local APNs conformance suite. Live checks are opt-in and use build tags for Apple or Google. Running tests does not itself establish delivery to every physical device type.

Deployment Security, Upgrades and Redis Recovery

The largest operational constraint is the unauthenticated REST API. The stock configuration is appropriate for local use because `[WebFrontend] addr` defaults to `localhost:9898`. A reverse proxy must authenticate requests before they reach endpoints such as `/addpsp`. The container configuration changes the listen address to `0.0.0.0`, so a deployment based directly on that image must supply access control outside the container.

Redis availability and persistence are part of delivery correctness, not secondary administration. The server uses Redis to retain every subscription. A missing primary connection prevents expected operation, while incomplete persistence can make recent subscriptions disappear after a restart. The default Redis snapshot schedule does not provide a substitute for a documented recovery procedure, and the excerpt does not state whether Redis replication is sufficient for the intended recovery point objective.

The project uses the Apache-2.0 license, with third-party license information in `THIRD-PARTY-LICENSES`. That is relevant to redistribution and compliance review, although this article does not provide legal advice. The project also supports `.deb`, `.rpm`, source builds, tarballs and a scratch-based container, so deployment choices differ in service integration and upgrade ownership.

Maintenance activity is recent rather than dormant now. The repository is not archived, its last push was on 2026-10-12, and the listed 2.9.1 release was published on 2026-10-09. Upgrade work is not free of migration cost because upstream API shutdowns changed APNs and FCM configuration, and the README asks upgraders to consult `docs/upgrading.md` release by release. Web Push and UnifiedPush are newer code paths with less documented deployment history, while ADM lacks renewed verification.

Editorial conclusion

uniqush-push fits teams operating their own notification backend across several push services. It is a poor fit for applications requiring client authentication, an unmanaged delivery platform, or full vendor coverage without further verification. Verify provider credentials, Redis persistence, the authenticated proxy boundary and the target platform path before sending production notifications. The repository is not archived, its last push was on 2026-10-12, and releases 2.8.0 through 2.9.1 were published in September and October 2026.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. uniqush/uniqush-push on GitHub