How to setup Notify Push in Ubuntu Server

  1. What is Notify Push
  2. Software Environment
  3. Setup
    1. Application installation
    2. Systemd Service
    3. Web Server
    4. Trusted Proxy
    5. Desktop Client Setup
  4. Test
  5. Troubleshooting
  6. Further Reading

 This document explains how to setup notify_push, also known as Files High Performance Backend, in an Ubuntu Server 22.04 system.

What is Notify Push

Notify Push, also known as Files High Performance Backend, is a service that improves the management of web and desktop notifications.  Without this service, users only get notifications about a new event (examples: a new incoming share, a Talk call, a chat mention) when their browser or Desktop client polls this information from the server. With Notify Push, those notifications are pushed to these devices as they happen with two benefits: users are notified sooner and the device polling frequency can be increased, thus leading to a lower server resources consumption. Please note that we are referring here to the browser and the Desktop client as notifications to mobile devices use a different delivery stack.

For more details, we recommend you ro read the Readme file in the app code repository.

Software Environment

The following setup instructions have been tested in the following environment:

  • Nextcloud server address: http://mycloud.com
  • Notify Push system IP: 10.0.1.192 <No10.0.1.192tify Push system IP>
  • Nextcloud server version: 28.0.3
  • Notify Push version: 0.6.9
  • Web Server: Apache2: 2.4.52
  • System architecture: x86_64
  • Nextcloud installation directory: /var/www/nextcloud/
  • Cache (based on Redis 6.0.16) and database (based on MariaDB 10.6.16) hosted in the same system as the web server

Setup

Application installation

Install the application in the Nextcloud server:

$ occ app:install notify_push

NOTE: this command will download the binaries for all supported architectures. It is in general a bad practice to leave unused binary files in the system, so you may remove those that do not match your architecture. Depending on how you want to deploy the Notify Push service, you may want to completely remove the bin folder. Keep reading to know more.

Then give the following value to the base_endpoint variable:

$ occ config:app:set notify_push base_endpoint --value https://mycloud.com/push

Systemd Service

If you are planning to run notify_push in a dedicated system, download the binary from the release page, and put it in its own folder, make it executable and test it:

$ mkdir /opt/notify_push
$ cd /opt/notify_push
$ wget -O ./notify_push https://github.com/nextcloud/notify_push/releases/download/v0.6.9/notify_push-x86_64-unknown-linux-musl
$ chmod +x notify_push 
$ ./notify_push --version
notify_push 0.6.9

If instead you are planning to run notify_push in the same machine of the Nextcloud server, the binary is downloaded in /var/www/nextcloud/apps/notify_push/bin/, please adapt the systemd service accordingly, if so.

Create a file to store the environment variables for the systemd service:

$ mkdir /etc/notify_push
$ vim /etc/notify_push/notify_push.env
PORT=7867
ALLOW_SELF_SIGNED=false 
NEXTCLOUD_URL=http://mycloud.com 
DATABASE_URL=<db_type>://<db_user>:<db_password>@<db_host>:<db_port>/<db_name> 
DATABASE_PREFIX=oc_ 
REDIS_URL=redis://:<redis_pwd>@<redis_host>:<redis_port>

Adjust the parameters as needed and, before proceeding, verify that the system you are running the service on can connect to all the services specified above (Nextcloud, database, Redis).

Take into account the following when setting up the connection:

  • Database and Redis should be reachable from the system where you are installing Notify Push. This is trivial when you are deploying it from the same system where they run, but you may need to think carefully about the security implications if it is not.
  • If protected-mode is enabled in Redis, then you should pass the password specified in the requirepass directive. You don't need to pass a user, so you can specify REDIS_URL as redis://:<redis_pwd>@<redis_host>:<redis_port>.
  • The user that connects to the database needs just the SELECT privileges on the Nextcloud database.

NOTE: The ALLOW_SELF_SIGNED=true is only needed if you are using a self-signed TLS certificate. Keep in mind that notify_push uses an internal trusted authorities database, so a tool like mkcert will not work with it.

Create a systemd service called notify_push:

$ vim /etc/systemd/system/notify_push.service
[Unit]
Description = Push daemon for Nextcloud clients
Documentation = https://github.com/nextcloud/notify_push

[Service]
EnvironmentFile = /etc/notify_push/notify_push.env
ExecStart = /opt/notify_push/notify_push

[Install]
WantedBy = multi-user.target

Let the system know about the new systemd service and enable it:

$ systemctl daemon-reload
$ systemctl enable notify_push
$ systemctl start notify_push
$ systemctl status notify_push
● notify_push.service - Push daemon for Nextcloud clients
     Loaded: loaded (/etc/systemd/system/notify_push.service; enabled; vendor preset: enabled)
    Drop-In: /run/systemd/system/service.d
             └─zzz-lxc-service.conf
     Active: active (running) since Fri 2023-02-10 16:56:54 CET; 1h 6min ago
       Docs: https://github.com/nextcloud/notify_push
   Main PID: 897 (notify_push)
      Tasks: 2 (limit: 37737)
     Memory: 5.5M
        CPU: 1.346s
     CGroup: /system.slice/notify_push.service
             └─897 /opt/notify_push/notify_push

Web Server

In the Nextcloud server, enable the relevant proxy modules in Apache:

$ a2enmod proxy
$ a2enmod proxy_http
$ a2enmod proxy_wstunnel

Add the following lines in the Apache Virtual Host file, in the VirtualHost block. In a standard Apache2 installation in Ubuntu, the virtual host files are placed in folder /etc/apache2/sites-available and then symlinked into /etc/apache2/sites-enabled:

$ vim /etc/apache2/sites-enabled/nextcloud.conf
<VirtualHost>

   [...]

   ProxyPass /push/ws ws://10.0.1.192:7867/ws 
   ProxyPass /push/ http://10.0.1.192:7867/ 
   ProxyPassReverse /push/ http://10.0.1.192:7867/

</VirtualHost>

Restart the apache2 service:

$ systemctl restart apache2

Trusted Proxy

In the Nextcloud server, add the IP of the server where the notify_push runs to the trusted proxies in config.php.

$ occ config:system:get trusted_proxies
$ occ config:system:set trusted_proxies <first-available-element-in-array> --value "10.0.1.192"

Desktop Client Setup

Setting up a notify_push service in the server enables the Desktop Client to poll the server for sync updates with a decreased frequency. The parameter that controls this poll frequency is remotePollInterval and it can be changed in the Desktop Client configuration file.

Check the documentation for more information:

https://docs.nextcloud.com/desktop/latest/advancedusage.html?highlight=polling#configuration-file

Test

In the Nextcloud server, run the self-test utility to check that everything is correctly setup:

$ occ notify_push:self-test
✓ redis is configured
✓ push server is receiving redis messages
✓ push server can load mount info from database
✓ push server can connect to the Nextcloud server
✓ push server is a trusted proxy
✓ push server is running the same version as the app

From a client machine, you can test that the setup is correct using the test_client utility.

After starting the utility, you can generate some event that is notified to the user you are monitoring: you should see the entries corresponding to the events written in the log (Received notification notification):

$ ./test_client https://my-nextcloud.com <user> <password>
[2024-03-18 14:07:49.031457 +01:00] INFO [test_client] test_client/src/main.rs:62: Received file update notification notify_file
[2024-03-18 14:07:49.031495 +01:00] INFO [test_client] test_client/src/main.rs:66: Received notification notification
[2024-03-18 14:08:29.083257 +01:00] INFO [test_client] test_client/src/main.rs:62: Received file update notification notify_file_id [43777]
[2024-03-18 14:08:37.613480 +01:00] INFO [test_client] test_client/src/main.rs:66: Received notification notification
If you are using a self-signed certificates, the test_client utility doesn’t work even if your certificate is locally trusted. You’ll get this error:
Connection Failed: tls connection init failed: invalid peer certificate contents: invalid peer certificate: UnknownIssuer

Troubleshooting

There is good troubleshooting information in this section of the code repository Readme.

Further Reading

Nextcloud Customer Portal article about scaling with notify_push:

https://portal.nextcloud.com/article/Scalability/Scaling-of-Nextcloud-Files-Client-Push-(Notify-Push)

Please contact us for any question or remark related to this article. We can help you in the deployment of basic and advanced services related to the Nextcloud platform