How to configure Nextcloud background jobs with cron

Nextcloud background jobs handle housekeeping work such as notification cleanup, file maintenance, activity processing, and app-supplied tasks outside normal page requests. Cron mode lets the operating system call cron.php every five minutes, which gives production servers a predictable scheduler instead of waiting for browser traffic.

The setting has two layers. The occ background:cron command tells Nextcloud to expect cron, and the web-server user's crontab invokes the PHP script that runs due jobs. Both layers should agree before treating the warning on the administration page as resolved.

Examples use the common Debian and Ubuntu web-server user www-data and a Nextcloud directory at /var/www/nextcloud. Replace the user, PHP command, or install path when the server uses a different package, container, virtual host layout, or HTTP account.

1. Change to the Nextcloud installation directory.

   $ cd /var/www/nextcloud

   Use the directory that contains occ and cron.php. Some archive, package, and container installs use paths such as /var/www/html or /usr/share/webapps/nextcloud instead.

2. Set Nextcloud background jobs to cron mode.

   $ sudo -E -u www-data php occ background:cron
   Set mode for background jobs to 'cron'

   -E preserves environment variables that some installations use for PHP or database access. Replace www-data with the HTTP user used by the server.

3. Confirm that Nextcloud saved cron mode.

   $ sudo -E -u www-data php occ config:app:get core backgroundjobs_mode
   cron

4. Open the web-server user's crontab.

   $ sudo crontab -u www-data -e

   Edit the crontab for the web-server user, not for root, so cron.php runs with the same file permissions as the web application.

5. Add the five-minute cron.php entry and save the crontab.

   */5 * * * * php -f /var/www/nextcloud/cron.php

   Use an absolute path to cron.php. If php is not in the cron user's default path, use the full PHP CLI path, such as /usr/bin/php.
   Tool: Crontab Generator

6. List the web-server user's crontab.

   $ sudo crontab -u www-data -l
   */5 * * * * php -f /var/www/nextcloud/cron.php

7. Check the cron marker after the next scheduled run.

   $ sudo -E -u www-data php occ config:app:get core lastcron
   1782688474

   lastcron is stored as a Unix timestamp and should change after cron.php runs. If it stays blank or unchanged after more than one interval, confirm that the system cron service is installed and running on the server.