Push Proxy Server¶

The Push Proxy Server is needed to forward the push notifications from the Nextcloud server to Firebase/Apple push servers and then the devices. A default push proxy server is provided by Nextcloud GmbH, but when using branded Nextcloud mobile clients a custom push proxy has to be set up on premise.

Setup¶

Hardware¶

• Minimum: 2GB RAM and 2 cores
• Recommendation for large (200k+ user) setups: 16GB RAM and 8 cores

Software¶

The push proxy server can be downloaded from our download server (see the link on your subscription page at https://portal.nextcloud.com/subscription).

Web server¶

The push proxy needs to be available under a domain that serves via HTTPS. Use the web server of your choice to do the SSL offloading and serve the port 8080 (can be changed in the config.yml if needed).

Database¶

On the first install you need to import the server.sql into your MySQL server that the push proxy connects to.

Configuration - Android¶

This push proxy needs configuration files from the Firebase project console.

• Go to Firebase Console -> Project settings -> Service accounts -> Firebase Admin SDK
• Click on Generate new private key
• Read the warning about not storing the key publicly
• Confirm with Generate key
• Download the file and rename it to google-services.json

Configuration - iOS¶

For iOS you need to enter the information:

• pushserver -> apns -> pushKit -> filesCertPassword: certificate password of apnsPushKitFilesCert.p12
• pushserver -> apns -> pushKit -> talkCertPassword: certificate password of apnsPushKitTalkCert.p12
• pushserver -> apns -> strictVoIP -> filesTopic: app bundle ID
• pushserver -> apns -> strictVoIP -> filesCertPassword: certificate password of apnsStrictVoIPFilesCert.p12
• pushserver -> apns -> strictVoIP -> talkTopic: app bundle ID
• pushserver -> apns -> strictVoIP -> talkCertPassword: certificate password of apnsStrictVoIPTalkCert.p12

For more information on how to create the certificates, please check the Push Notifications For Files and Talk article

Example setup¶

Example for a service file for the push proxy:

[Unit]
Description=Push Notifications Proxy
ConditionPathExists=/opt/push-notification-proxy/
After=mysql.service
  
[Service]
Restart=always
RestartSec=3
WorkingDirectory=/opt/push-notification-proxy/
ExecStart=/opt/push-notification-proxy/push-notification-proxy
 
[Install]
WantedBy=multi-user.target

The config.yml needs to look like this (placed in the same folder as the binary is):

database:
  user: "pushnotifications"
  password: "{{mysql_password}}"
  host: "127.0.0.1:3306"
  name: "pushnotifications"
server:
  port: 80
  debug: true
pushserver:
  apns:
    pushKit:
      filesCertPassword: "{{apns_pushkit_files_cert_password}}"
      talkCertPassword: "{{apns_pushkit_talk_cert_password}}"
    strictVoIP:
      filesTopic: "{{apns_strictvoip_files_topic}}"
      filesCertPassword: "{{apns_strictvoip_files_cert_password}}"
      talkTopic: "{{apns_strictvoip_talk_topic}}"
      talkCertPassword: "{{apns_strictvoip_talk_cert_password}}"

The google-services.json from the Firebase Console and the apns*Cert.p12 files from the Apple developer page are also to be placed in the same folder. Then the service can be started and should create following output:

2024/06/10 16:57:45 [Config]        File loaded
2024/06/10 16:57:45 [Database]      Connection established
2024/06/10 16:57:45 [FCM]           FCM Client started
2024/06/10 16:57:45 [APNS]          PushKit Files client started
2024/06/10 16:57:45 [APNS]          PushKit Talk client started
2024/06/10 16:57:45 [APNS]          StrictVoIP Files client started
2024/06/10 16:57:45 [APNS]          StrictVoIP Talk client started
2024/06/10 16:57:45 [APNS]          PushKit Files cert: 'VoIP Services: com.nextcloud.Files' valid until '2025-07-10 14:31:06 +0000 UTC'
2024/06/10 16:57:45 [APNS]          PushKit Talk cert: 'VoIP Services: com.nextcloud.Talk' valid until '2025-07-10 14:25:30 +0000 UTC'
2024/06/10 16:57:45 [APNS]          StrictVoIP Files cert: 'Apple Push Services: com.nextcloud.Files' valid until '2025-07-10 14:28:39 +0000 UTC'
2024/06/10 16:57:45 [APNS]          StrictVoIP Talk cert: 'Apple Push Services: com.nextcloud.Talk' valid until '2025-07-10 14:15:42 +0000 UTC'
2024/06/10 16:57:45 [Network]       Listening on port 80
2024/06/10 16:57:45 [Network]       Starting to listen and serve
...

Updating¶

General¶

Unless mentioned in the From … to … list below, the steps to update are as follows.

• Stop the service
• Replace the push-notification-proxy
• Update the database with server.sql (it's always containing all steps incrementally, so you can run it safely all the time)
• Restart the service

Unless mentioned differently, you can also jump major versions, as long as the changes from below are still applied.

From 2.3 to 2.4¶

• Optional: A new config key enableMetrics was added. When enabled the /metrics endpoint is serving prometheus metrics for monitoring. It is recommended that access to the endpoint is limited to the own monitoring server IP addresses as no authentication check is in place.

From 2.2 to 2.3¶

• No special steps required

From 2.1 to 2.2¶

• New configuration property disabled in sections fcm and apns added. Those allow to disable either push backend, in case only iOS or Android apps are being used

From 2.0 to 2.1¶

• New configuration property host in section server added. Make sure to set it to the TCP address the server should listen to. Otherwise it falls back to 127.0.0.1 (see sample.config.yml)

From 1.1 to 2.0¶

• You need to generate a Firebase Service account config file. See Configuration - Android for detailed steps.
• Most likely you will then be phased with Firebase Cloud Messaging API has not been used in project … before or it is disabled.. See Troubleshooting - Android for details.

From 1.0 to 1.1¶

• No special steps required

From 0.x to 1.0¶

• No special steps required

Troubleshooting¶

iOS - MissingTopic or TopicDisallowed¶

When an error like the following happens when testing the notifications:

2023/06/19 11:30:20 [321B4984-…] 400: TopicDisallowed
2023/06/19 11:30:20 Sending to APNS failed with reason: TopicDisallowed
2023/06/19 11:30:20 [681746F6-…] 400: MissingTopic
2023/06/19 11:30:20 Sending to APNS failed with reason: MissingTopic

Most likely the certificate files are swapped and the names of apnsPushKit…Cert.p12 and apnsStrictVoIP…Cert.p12 need to be swapped, so:

• Rename apnsPushKit…Cert.p12 to other…Cert.p12
• Rename apnsStrictVoIP…Cert.p12 to apnsPushKit…Cert.p12
• Rename other…Cert.p12 to apnsStrictVoIP…Cert.p12

The current naming is naturally grown and can therefore cause confusions.

Android - Firebase Cloud Messaging API has not been used in project … before or it is disabled.¶

After the initial setup or when upgrading to version 2.0 for the first time, the following error can be faced:

2024/06/17 12:16:14 Sending to FCM failed with reason: Firebase Cloud Messaging API has not been used in project nextcloud-a7dea before or it is disabled. Enable it by visiting https://console.developers.google.com/apis/api/fcm.googleapis.com/overview?project=nextcloud-a7dea then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry.

To resolve this, please follow the steps:

• Open the Firebase console: https://console.firebase.google.com/
• Select your project
• In the project overview switch to Cloud Messaging
• At the end of the Firebase Cloud Messaging API (V1) header open the ... menu
• Follow the Manage the API in Google Cloud console link
• In the new Firebase Cloud Messaging API page press the blue Enable button

When visiting the Cloud Messaging settings again there should now be a 🟢 Enabled checkmark:

As per the error message it can take a moment until changes get applied, in our account it took only a few seconds.

UnifiedPush support¶

While Nextcloud recently added WebPush related features, UnifiedPush and mobile clients for it are not supported by the Nextcloud Enterprise subscription.