Setting up client push for Nextcloud

With version 21, the optional “Files High Performance Back-end” was introduced at Nextcloud. Technically, this is a service that you can install separately and actively notifies clients about file changes with “client push”.

Function of the client push

Without client push, connected clients periodically check with the server for file changes. If a large number of clients are connected, this can create a noticeable load on the server. Another disadvantage is that file changes are only transmitted with a certain delay.

Client Push is a service that runs parallel to Nextcloud under Linux as a daemon and actively informs the clients of every file change.

The sources including documentation can be found at Github.

The following description refers to Debian-based Linux distributions.


In order to use the extension, Redis must be present and configured in Nextcloud. If you have not yet used Redis, this can be set up as follows.

Installation Redis server

The first step is to install and activate the Redis server as follows:

sudo apt install redis-server
sudo systemctl start redis-server

The default configuration of Redis usually only allows local access. To be on the safe side, however, you should check whether the following line is present in /etc/redis/redis.conf:

bind ::1

If this is not the case, or the line is commented out, this should be corrected and the Redis server restarted afterwards.

Configuration of Redis on Nextcloud

Before configuring Redis, you should ensure that Redis support is present in PHP. You can use the following command for this:

php -i | grep redis

If no result is returned here, the Redis extension is not yet installed. This can then be repeated as follows:

sudo apt install php-redis

If Redis can be used in PHP, you can now add the following section to config/config.php in Nextcloud:

'memcache.locking' => '\\OC\\Memcache\\Redis',
'redis' => 
array (
  'host' => 'localhost',
  'port' => 6379,
  'dbindex' => 0,

If Nextcloud continues to work in the browser, the configuration was successful. If not, you should check again whether the Redis extension for PHP is really activated and whether Redis is running – e.g. with the command line client redis-cli. You can leave the client quit.

redis-cli> quit


The setup is done in several steps:

  1. Installing the “Client Push” app in Nextcloud.
  2. Setting up the push server service
  3. Configuration of the reverse proxy for the push server
  4. Customize Nextcloud configuration

Installing the Client Push app

The “Client Push” app can be installed in Nextcloud via the app management. You can find them in the “Tools” or “Tools” category. After installation, nothing changes in the Nextcloud interface, but you get additional OCC commands in the console.

Setting up the reverse proxy

A reverse proxy is required to use the service, which makes the service accessible in Nextcloud.


Here you add the following information to the configuration of the website for Nextcloud:

location ^~ /push/ {
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

After the configuration adjustment, the web server must be reloaded:

sudo nginx -s reload


The first thing to do here is to ensure that all required modules for the proxy are enabled:

sudo a2enmod proxy
sudo a2enmod proxy_http
sudo a2enmod proxy_wstunnel

Then add the following information to the configuration of the website for Nextcloud:

ProxyPass /push/ws ws://
ProxyPass /push/
ProxyPassReverse /push/

After the configuration adjustment, the web server must be restarted:

sudo systemctl restart apache2

Adjusting the Nextcloud configuration

In order for Nextcloud to accept incoming requests from the push server service, the IP address of the server must be added to the list of “trusted proxies” in config/config.php as follows. Instead of <Nextcloud IP address>, enter the IP address of the server.

'trusted_proxies' => 
array (
  0 => '<Nextcloud IP address>',
  1 => '',
  2 => '::1',

Setting up the push server service

For the push server service, create a new systemd unit in /etc/systemd/system/notify_push.service.

The installation wizard as well as the documentation give an example configuration for systemd. Unfortunately, dependencies are missing, which can lead to the service not starting properly when the server is restarted or logging an error when starting because Nextcloud is not yet accessible. I have therefore entered Redis as a dependency (After) as well as PHP, Apache and MySQL so that the service only starts when Nextcloud is fully functional. If you don’t use Apache but NGIX, you have to adapt the services accordingly. This also applies if you do not use MariaDB/MySQL, but another database system.

You have to modify the information for Environment and ExecStart for your own server. Instead of my-nextcloud-domain.example, enter the name of your own Nextcloud domain. Likewise, the path information for the app and the configuration file must of course correspond to your own installation. PORT= specifies the Redis port, which is usually 7867. At User you enter the user with which Nextcloud or PHP-FPM is running.

Description = Push daemon for Nextcloud clients
After = redis-server.service mysql.service php8.1-fpm.service apache2.service

Environment = PORT=7867
Environment = NEXTCLOUD_URL=https://my-nextcloud-domain.example
ExecStart = /var/www/my-nextcloud-domain.example/apps/notify_push/bin/x86_64/notify_push /var/www/my-nextcloud-domain.example/config/config.php
User = nextcloud

WantedBy =

The service can be started and permanently activated with the following commands:

systemctl enable notify_push
systemctl start notify_push

Checking the functionality

With the following command you can check whether the configuration was successful (instead of /var/www/my-nextcloud-domain.example the path in which your own Nextcloud server is installed):

php /var/www/my-nextcloud-domain.example/occ notify_push:self-test

Then the following output should then appear:

✓ 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

Practical impact in operation

To see the difference in operation, you can create a new folder or file in Nextcloud’s browser interface while having the locally synced folder open in the file manager. The new folder or file should also appear locally within a few seconds.

Leave a public comment

Your email address will not be published. This is not a contact form! If you want to send me a personal message, use my e-mail address in the imprint.

You can use the following HTML tags in the comment:
<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>