{"id":13725775,"url":"https://github.com/nextcloud/notify_push","last_synced_at":"2026-01-12T10:53:53.215Z","repository":{"id":40243256,"uuid":"312696987","full_name":"nextcloud/notify_push","owner":"nextcloud","description":"Update notifications for nextcloud clients","archived":false,"fork":false,"pushed_at":"2025-05-07T15:08:27.000Z","size":1206,"stargazers_count":255,"open_issues_count":76,"forks_count":49,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-05-07T15:23:35.657Z","etag":null,"topics":["nextcloud"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nextcloud.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.md","dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-11-13T22:24:38.000Z","updated_at":"2025-05-07T15:07:07.000Z","dependencies_parsed_at":"2023-10-15T23:13:36.940Z","dependency_job_id":"fbdfe481-6d09-4a1e-8a9c-7916c8e11c3c","html_url":"https://github.com/nextcloud/notify_push","commit_stats":{"total_commits":525,"total_committers":40,"mean_commits":13.125,"dds":"0.23619047619047617","last_synced_commit":"4a81d4eaa588e9fe0f4917e05b9975917e8631e1"},"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nextcloud%2Fnotify_push","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nextcloud%2Fnotify_push/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nextcloud%2Fnotify_push/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nextcloud%2Fnotify_push/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nextcloud","download_url":"https://codeload.github.com/nextcloud/notify_push/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254493378,"owners_count":22080126,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["nextcloud"],"created_at":"2024-08-03T01:02:34.616Z","updated_at":"2026-01-12T10:53:53.208Z","avatar_url":"https://github.com/nextcloud.png","language":"Rust","readme":"\u003c!--\n  - SPDX-FileCopyrightText: 2020 Nextcloud GmbH and Nextcloud contributors\n  - SPDX-License-Identifier: AGPL-3.0-or-later\n--\u003e\n\n# Client Push\n\n[![REUSE status](https://api.reuse.software/badge/github.com/nextcloud/notify_push)](https://api.reuse.software/info/github.com/nextcloud/notify_push)\n\nUpdate notifications for nextcloud clients\n\n## About\n\nThis app attempts to solve the issue where Nextcloud clients have to periodically check the server if any files have\nbeen changed. In order to keep sync snappy, clients wants to check for updates often, which increases the load on the\nserver.\n\nWith many clients all checking for updates a large portion of the server load can consist of just these update checks.\n\nBy providing a way for the server to send update notifications to the clients, the need for the clients to make these\nchecks can be greatly reduced.\n\nUpdate notifications are provided on a \"best effort\" basis, updates might happen without a notification being sent and a\nnotification can be sent even if no update has actually happened. Clients are advised to still perform periodic checks\nfor updates on their own, although these can be run on a much lower frequency.\n\n## Requirements\n\nThis app requires a redis server to be setup and for nextcloud to be configured to use the redis server.\n\n## Quick setup\n\nThe app comes with a setup wizard that should guide you through the setup process for most setups.\n\n- Install the \"Client Push\" (`notify_push`) app from the appstore\n- Run `occ notify_push:setup` and follow the provided instructions,\n  If the setup wizard fails you can find manual instructions below.\n\n## Manual setup\n\nThe setup required consists of three steps\n\n- Install the `notify_push` app from the appstore\n- Setting up the push server\n- Configuring the reverse proxy\n- Configuring the nextcloud app\n\n\u003e __For Nextcloud Snap users:__ \\\n\u003e The snap team made a wiki page how to install Client Push in Nextcloud snap.\n\u003e\nSee [their Wiki page](https://github.com/nextcloud-snap/nextcloud-snap/wiki/Configure-HPB-client-push-for-Nextcloud-snap)!\n\n### Push server\n\nThe push server should be setup to run as a background daemon, the recommended way is by setting it up as a system\nservice in the init system.\nIf you're not using systemd then any init or process management system that runs the push server binary with the\ndescribed environment variables will work.\n\n#### systemd\n\nFor systemd based setups, you can create a systemd service by creating a file named\n`/etc/systemd/system/notify_push.service` with the following\ncontent.\n\n```ini\n[Unit]\nAfter=network.target mariadb.service nginx.service postgresql.service redis.service\nDescription = Push daemon for Nextcloud clients\nDocumentation = https://github.com/nextcloud/notify_push\n\n[Service]\n# Change if you already have something running on this port\nEnvironment = PORT=7867\nExecStart = /path/to/push/binary/notify_push /path/to/nextcloud/config/config.php\n# requires the push server to have been build with the systemd feature (enabled by default)\nType = notify\nUser = www-data\nRestart = always\nRestartSec = 60\n\n[Install]\nWantedBy = multi-user.target\n```\n\nIf the push server has not been compiled with the optional systemd feature (enabled by default) the `Type=notify` line\nhas to be removed.\n\n#### OpenRC\n\nFor OpenRC based setups, you can create an OpenRC service by creating a file named `/etc/init.d/notify_push` with the\nfollowing content.\n\n```sh\n#!/sbin/openrc-run\n\ndescription=\"Push daemon for Nextcloud clients\"\n\noutput_log=${output_log:-/var/log/$RC_SVCNAME.log}\npidfile=${pidfile:-/run/$RC_SVCNAME.pid}\n\ncommand=${command:-/path/to/push/binary/notify_push}\ncommand_user=${command_user:-www-data:www-data}\ncommand_args=\"--port 7867 /path/to/nextcloud/config/config.php\"\ncommand_background=true\n\ndepend() {\n        need net\n        use nginx php-fpm8 mariadb postgresql redis\n}\n\nstart_pre() {\n        checkpath --file --owner $command_user $output_log\n}\n```\n\nAdjust the paths, ports and user as needed.\n\n#### Configuration\n\nThe push server can be configured either by loading the config from the nextcloud `config.php` or by setting all options\nthrough environment variables.\n\nRe-using the configuration from nextcloud is the recommended way, as it ensures that the configuration remains in sync.\n\nIf using the `config.php` isn't possible, you can configure the push server by setting the following environment\nvariables:\n\n- `DATABASE_URL` connection url for the Nextcloud database, e.g. `postgres://user:password@db_host/db_name`\n- `DATABASE_PREFIX` database prefix configured in Nextcloud, e.g. `oc_`\n- `REDIS_URL` connection url for redis, e.g. `redis://redis_host`\n- `NEXTCLOUD_URL` url for the nextcloud instance, e.g. `https://cloud.example.com`\n\nOr you can specify the options as command line arguments, see `notify_push --help` for information about the command\nline arguments.\n\nIf a config option is set in multiple sources, the values from the command line argument overwrite values from the\nenvironment\nwhich in turns overwrites the values from the `config.php`.\n\nThe port the server listens to can only be configured through the environment variable `PORT`, or `--port` argument and\ndefaults to 7867.\nAlternatively you can configure the server to listen on a unix socket by setting the `SOCKET_PATH` environment variable\nor `--socket-path` argument.\n\nNote that Nextcloud loads all files matching `*.config.php` in the config directory in additional to the main config\nfile.\nYou can enable this same behavior by passing the `--glob-config` option.\n\n\u003cdetails\u003e\n\u003csummary\u003eUsing a separate redis instance for the push server\n\u003c/summary\u003e\n\nYou can optionally use a different redis instance for communications between the Nextcloud server and the push daemon.\n\nThis allows spreading moving the load away from the normal redis usage or use a redis setup more optimized for the specific usage (`PUBSUB` traffic instead of cache storage).\n\nYou can configure this by setting the `notify_push_redis` config option in the `config.php` of the Nextcloud server, this accepts the same options as the normal redis configurations.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eConnecting to redis over TLS\n\u003c/summary\u003e\n\nYou can connect to redis over TLS by specifying `rediss://` as the redis url.\n\nThe client certificate and key can be set with the `--redis-tls-cert` and `--redis-tls-key` arguments (or the\n`REDIS_TLS_CERT` and `REDIS_TLS_KEY` environment variables).  \nThe certificate authority for validating the server certificate can be set with the `--redis-tls-ca` argument (or the\n`REDIS_TLS_CA` environment variable).\n\nAdditionally, you can disable validating the hostname of the server certificate with\n`--redis-tls-dont-validate-hostname` or disable all certificate validation altogether with `--redis-tls-insecure` (or\nthe `REDIS_TLS_DONT_VALIDATE_HOSTNAME` and `REDIS_TLS_INSECURE` environment variables respectively).\n\n\u003c/details\u003e\n\n#### TLS Configuration\n\nThe push server can be configured to serve over TLS. This is mostly intended for securing the traffic between the push\nserver\nand the reverse proxy if they are running on different hosts, running without a reverse proxy (or load balancer) is not\nrecommended.\n\nTLS can be enabled by setting the `--tls-cert` and `--tls-key` arguments (or the `TLS_CERT` and `TLS_KEY` environment\nvariables).\n\n#### Starting the service\n\nOnce the systemd service file is set up with the correct configuration you can start it using\n\n- systemd: `sudo systemctl start notify_push`\n- OpenRc: `sudo rc-service notify_push start`\n\nand enable it to automatically start on boot using\n\n- systemd: `sudo systemctl enable notify_push`\n- OpenRc: `sudo rc-update add notify_push`\n\nEvery time this app receives an update you should restart the systemd service using\n\n- systemd: `sudo systemctl restart notify_push`\n- OpenRc: `sudo rc-service notify_push restart`\n\n\u003cdetails\u003e\n\u003csummary\u003eAlternatively, you can do this automatically via systemctl by creating the following systemd service and path (click to expand)\u003c/summary\u003e\n\nFirst create a oneshot service to trigger the daemon restart\n\n`/etc/systemd/system/notify_push-watcher.service`\n\n```ini\n[Unit]\nDescription = Restart Push daemon for Nextcloud clients when it receives updates\nDocumentation = https://github.com/nextcloud/notify_push\nRequires = notify_push.service\nAfter = notify_push.service\nStartLimitIntervalSec = 10\nStartLimitBurst = 5\n\n[Service]\nType = oneshot\nExecStart = /usr/bin/systemctl restart notify_push.service\n\n[Install]\nWantedBy = multi-user.target\n```\n\nThen create a `path` job to trigger the restart whenever the push binary is changed\n\n`/etc/systemd/system/notify_push-watcher.path`\n\n```ini\n[Unit]\nDescription = Restart Push daemon for Nextcloud clients when it receives updates\nDocumentation = https://github.com/nextcloud/notify_push\nPartOf = notify_push-watcher.service\n\n[Path]\nPathModified = /path/to/push/binary/notify_push\nUnit = notify_push-watcher.service\n\n[Install]\nWantedBy = multi-user.target\n```\n\nAdjusting the path as needed.\n\nFinally, enable it with\n\n```bash\nsudo systemctl enable notify_push-watcher.path\n```\n\n\u003c/details\u003e\n\n### Reverse proxy\n\nIt is **strongly** recommended to set up the push service behind a reverse proxy, this both removes the need to open\na new port to the internet and handles the TLS encryption of the connection to prevent sending credentials in plain\ntext.\n\nYou can probably use the same webserver that you're already using for your nextcloud.\n\n#### Nginx\n\nIf you're using nginx, add the following `location` block to the existing `server` block of the nextcloud server.\n\n```nginx\nlocation ^~ /push/ {\n    proxy_pass http://127.0.0.1:7867/;\n    proxy_http_version 1.1;\n    proxy_set_header Upgrade $http_upgrade;\n    proxy_set_header Connection \"Upgrade\";\n    proxy_set_header Host $host;\n    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n}\n```\n\nNote that both trailing slashes are required.\n\nOnce the nginx configuration is edit you can reload nginx using.\n\n```bash\nsudo nginx -s reload\n```\n\n#### Apache\n\nTo use apache as a reverse proxy you first need to enable the proxy modules using\n\n```bash\nsudo a2enmod proxy\nsudo a2enmod proxy_http\nsudo a2enmod proxy_wstunnel\n```\n\nThen add the following lines to the `\u003cVirtualHost\u003e` block used for the Nextcloud server.\n\n```apacheconf\nProxyPass /push/ws ws://127.0.0.1:7867/ws\nProxyPass /push/ http://127.0.0.1:7867/\nProxyPassReverse /push/ http://127.0.0.1:7867/\n```\n\nAfterwards you can restart apache using\n\n```bash\nsudo systemctl restart apache2\n```\n\n#### Caddy v2\n\n```Caddyfile\nhandle_path /push/* {\n    reverse_proxy http://127.0.0.1:7867\n}\n```\n\n### Nextcloud app\n\nOnce the push server is configured and the reverse proxy setup, you can enable the `notify_push` app and tell it where\nthe push server is listening.\n\n- enable the app `occ app:enable notify_push`\n- set the url of the push server `occ notify_push:setup https://cloud.example.com/push`\n\nThe app will automatically run some tests to verify that the push server is configured correctly.\n\n### Logging\n\nBy default, the push server only logs warnings, you can temporarily change the log level with an occ command\n\n```bash\nocc notify_push:log \u003clevel\u003e\n```\n\nWhere level is `error`, `warn`, `info`, `debug` or `trace`, or restore the log level to the previous value using\n\n```bash\nocc notify_push:log --restore\n```\n\nAlternatively you can set the log level of the push server in the `LOG` environment variable.\n\n### Metrics\n\nThe push server can expose some basic metrics about the number of connected clients and the traffic flowing through the\nserver\nby setting the `METRICS_PORT` environment variable.\nThe metrics endpoint will listen on all interfaces by default (0.0.0.0).\nHowever, it is also possible to bind the metrics listener to a local UNIX socket by specifying a path via the\n`METRICS_SOCKET_PATH` environment variable.\n\nOnce set the metrics are available in a prometheus compatible format at `/metrics` on the configured port or UNIX socket.\n\nAdditionally you can manually check the metrics by running the `occ notify_push:metrics` command, this will function\neven if you haven't setup `METRICS_PORT` or `METRICS_SOCKET_PATH`.\n\n### Self-signed certificates\n\nIf your nextcloud is using a self-signed certificate then you either need to set the `NEXTCLOUD_URL` to a non-https,\nlocal url,\nor disable certificate verification by setting `ALLOW_SELF_SIGNED=true`.\n\n## Troubleshooting\n\nWhen running into issues you should always first ensure that you're on the latest release, as your issue might either\nalready be fixed or additional diagnostics might have been added.\n\n### \"push server is not a trusted proxy\"\n\n- Ensure you haven't added a duplicate `trusted_proxies` list to your `config.php`.\n- If you're modified your `forwarded_for_headers` config, ensure that `HTTP_X_FORWARDED_FOR` is included.\n- If your nextcloud hostname resolves do a dynamic ip you can try setting the `NEXTCLOUD_URL` to the internal ip of the\n  server.\n\n  Alternatively, editing the `/etc/hosts` file to point your nextcloud domain to the internal ip can work in some\n  setups.\n- If you're running your setup in docker and your containers are linked, you should be able to use the name of the\n  nextcloud container as hostname in the `NEXTCLOUD_URL`\n\n## Developing\n\nFor information about how to use the push server in your own app or client, see [DEVELOPING.md](./DEVELOPING.md)\n\n## Test client\n\nFor development and testing purposes a test client is provided which can be downloaded from\nthe [current release](https://github.com/nextcloud/notify_push/releases/latest) page.\u003cbr\u003e\n(Click the `test_client` for your platform to download the binary.)\n\n```bash\ntest_client https://cloud.example.com username password\n```\n\nNote that this does not support two-factor authentication of non-default login flows, you can use an app-password in\nthose cases.\n","funding_links":[],"categories":["Rust","others"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnextcloud%2Fnotify_push","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnextcloud%2Fnotify_push","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnextcloud%2Fnotify_push/lists"}