Skip to main content
OJS for Everyone Logo
OJS for EveryoneThe Practical GuidebookRSYN Research LLP

Job Runner

info

These recommendations are for high-volume journal, press, or preprint services. Low-volume services can use the built-in job runner with no configuration.

OJS uses a job queue to handle long-running tasks: sending bulk email notifications, compiling statistics, depositing DOIs, updating the search index, and more.

On a high-volume site, these tasks may slow down the server. Administrators can move these tasks to separate requests or threads to keep the site responsive.

CLI Commands​

# List available command-line options
php lib/pkp/tools/jobs.php usage

# List pending jobs
php lib/pkp/tools/jobs.php list

# View failed jobs
php lib/pkp/tools/jobs.php failed

# Run all pending jobs
php lib/pkp/tools/jobs.php run

# Run a single job
php lib/pkp/tools/jobs.php run --once

Running Jobs​

Configure one of the following methods. Enabling two methods does not improve performance.

Workers run as daemons, waiting for jobs and processing them in a separate process.

php lib/pkp/tools/jobs.php work

Pass --help for all options. In production, use Supervisor to keep the worker running.

Install Supervisor:

sudo apt-get install supervisor

Create a config file at /etc/supervisor/conf.d/ojs-worker.conf:

[program:ojs-queue-worker]
process_name=%(program_name)s
command=/usr/bin/php /var/www/html/ojs/lib/pkp/tools/jobs.php work
directory=/var/www/html/ojs
autostart=true
autorestart=true
redirect_stderr=true
stdout_logfile=/var/log/ojs-worker.log

Replace paths as appropriate for your server. Then reload Supervisor:

supervisorctl reread
sudo service supervisor restart
warning

Workers are long-running processes that load the application in memory. Changes to the application will not take effect until the worker is restarted:

php lib/pkp/tools/jobs.php restart

Do not restart Supervisor abruptly — it will kill jobs mid-execution. Always use the restart command above.

Once workers are configured, disable the built-in job runner:

job_runner = Off

Cron​

A cron job can process jobs at regular intervals:

# Run all jobs
* * * * * php /var/www/html/ojs/lib/pkp/tools/jobs.php run >> /dev/null 2>&1

# Run one job at a time (reduces resource spikes)
* * * * * php /var/www/html/ojs/lib/pkp/tools/jobs.php run --once >> /dev/null 2>&1

Running all jobs at once: A large batch of resource-intensive jobs could spike server load.

Running one job at a time: Less likely to spike resources, but jobs may back up (e.g., 100 email jobs at 1/minute = 100 minutes to send).

Once a cron job is set up, disable the built-in runner:

job_runner = Off

Run Jobs with Scheduled Tasks​

To process jobs as part of your OS task scheduler, enable:

process_jobs_at_task_scheduler = On

This requires both job_runner and task_runner (under [schedule]) to be Off.

Built-in Job Runner​

If you cannot configure workers or cron jobs, use the built-in runner. It runs jobs off the back of user requests.

job_runner = On

Tune the built-in runner in config.inc.php:

; Maximum number of jobs per request
job_runner_max_jobs = 30

; Maximum seconds per request (keep below PHP max_execution_time)
job_runner_max_execution_time = 30

; Maximum memory usage (percentage or fixed MB)
job_runner_max_memory = 80

Monitoring Jobs​

Monitor pending and failed jobs via CLI or the admin interface:

  • Pending jobs: php lib/pkp/tools/jobs.php list or Administration → Jobs
  • Failed jobs: php lib/pkp/tools/jobs.php failed or Administration → Failed Jobs (you can also retry from the admin UI)

To automatically delete failed jobs after a set number of days:

delete_failed_jobs_after = 180

Troubleshooting​

The best way to troubleshoot failed jobs is through Administration → Failed Jobs. The table shows what failed, when, and with what exceptions.

warning

Never run jobs while the site is under maintenance (e.g., during an upgrade).