Skip to main content
OJS for Everyone Logo
OJS for EveryoneThe Practical Guidebook

Upgrading OJS

Always back up first

Before upgrading, take a full backup of your database and files directory. Upgrades cannot be automatically reversed.

Pre-Upgrade Checklist​

  • Backup database: mysqldump -u ojsuser -p ojs > ojs_backup_YYYYMMDD.sql
  • Backup files directory: tar -czf ojs-files-backup.tar.gz /var/www/ojs-files
  • Backup config.inc.php: cp config.inc.php config.inc.php.bak
  • Check the release notes for breaking changes
  • Test the upgrade on a staging server first
  • Disable any custom plugins and note their versions

Upgrade Steps​

1. Download the New Release​

wget https://pkp.sfu.ca/software/ojs/download/ojs-3.5.x.tar.gz
tar -xzf ojs-3.5.x.tar.gz

2. Replace Application Files​

# Preserve your config and data
cp /var/www/html/ojs/config.inc.php /tmp/config.inc.php.bak

# Replace application files (do NOT delete the public/ or cache/ subdirectories of your files_dir)
rsync -av --exclude='config.inc.php' \
          --exclude='public/' \
          ojs-3.5.x/ /var/www/html/ojs/

3. Restore Config​

cp /tmp/config.inc.php.bak /var/www/html/ojs/config.inc.php

4. Run the Upgrade Script​

cd /var/www/html/ojs
php tools/upgrade.php upgrade

Review the output for any errors before proceeding.

5. Clear Caches​

php lib/pkp/tools/cacheClear.php

Or via the admin panel: Administration → Clear Caches

6. Re-enable Plugins​

Re-enable and update any plugins that were disabled before the upgrade.

Troubleshooting​

IssueSolution
Blank page after upgradeCheck PHP error log; run php tools/upgrade.php upgrade again
Missing tablesConfirm the upgrade script completed without errors
Plugin errorsDisable the plugin; check for a compatible version
File permission errorschown -R www-data:www-data /var/www/html/ojs

Further Reading​