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

Tutorial: Upgrade OJS to 3.5.0-4

Role: Site Administrator
Time: 30–60 minutes
OJS Version: 3.5.0-3 → 3.5.0-4

This tutorial walks through upgrading Open Journal Systems (OJS) from version 3.5.0-3 to 3.5.0-4 via SSH on a shared or VPS hosting environment. It covers database and file backups, file replacement, database migration, plugin conflict resolution, and post-upgrade health checks.

LTS Candidate

OJS 3.5.0-4 is a strong candidate for Long-Term Support (LTS) designation by PKP. Once confirmed, versions 3.3 and 3.4 will enter a one-year end-of-life window. Check the PKP roadmap for the latest status.

Before You Start​

You will need:

  • SSH access to your server
  • Your database credentials (from config.inc.php)
  • PHP 8.2 or higher
  • wget or curl available on the server
  • At least 2 GB of free disk space
  • OJS currently running on 3.5.0-3

Confirm your current version​

cat /path/to/ojs/dbscripts/xml/version.xml | grep release

Expected output:

<release>3.5.0.3</release>

Check PHP version​

php -v

Check disk space​

df -h ~

Step 1 — Database Backup​

Always back up your database before any upgrade. This is your safety net if anything goes wrong.

mysqldump -u YOUR_DB_USER -p YOUR_DB_NAME > ~/ojs_db_backup_$(date +%F).sql

Verify the backup was created:

ls -lh ~/ojs_db_backup_*.sql
tip

A healthy backup should be several MB in size. If the file is 0 bytes, the backup failed — do not proceed.

warning

Replace YOUR_DB_USER and YOUR_DB_NAME with your actual credentials from config.inc.php.

Step 2 — File Backup​

Create a compressed archive of your entire OJS installation:

tar -czf ~/ojs_files_backup_$(date +%F).tar.gz /path/to/your/ojs/

Verify the archive:

ls -lh ~/ojs_files_backup_*.tar.gz
tip

Keep both backups for at least 2–4 weeks after the upgrade before deleting them.

Step 3 — Download OJS 3.5.0-4​

Download the official release package from PKP:

cd ~
wget https://pkp.sfu.ca/ojs/download/ojs-3.5.0-4.tar.gz

Verify the download:

ls -lh ~/ojs-3.5.0-4.tar.gz
warning

Only download from the official PKP website (pkp.sfu.ca). Do not use unofficial mirrors or third-party sources.

Step 4 — Extract the Package​

cd ~
tar -xzf ojs-3.5.0-4.tar.gz

Verify the contents:

ls ~/ojs-3.5.0-4/

You should see standard OJS directories: api, classes, config.inc.php, dbscripts, lib, plugins, tools, etc.

Step 5 — Copy New Files​

Use rsync to copy new files while preserving your configuration, uploaded files, and plugins:

rsync -av --exclude='config.inc.php' \
          --exclude='public/' \
          --exclude='files/' \
          --exclude='plugins/' \
          ~/ojs-3.5.0-4/ /path/to/your/ojs/
Critical

The --exclude flags are essential. They prevent overwriting your config.inc.php, user-uploaded files, and custom plugins. Do not remove them.

The final line of rsync output should show the total size and transfer speed — no errors.

Step 6 — Run the Database Upgrade​

Navigate to your OJS directory and run the upgrade script:

cd /path/to/your/ojs/
php tools/upgrade.php upgrade

A successful upgrade produces output like this:

2026-05-06 07:08:43 [pre-install]
2026-05-06 07:08:43 [load: upgrade.xml]
2026-05-06 07:08:43 [version: 3.5.0.4]
2026-05-06 07:08:43 [migration: PKP\migration\upgrade\v3_5_0\I10962_UpdateEmailTemplateVariables]
2026-05-06 07:08:43 [migration: PKP\migration\upgrade\v3_5_0\I11603_AddMissingUserRoleAssignmentInvitationEmail]
...
Successfully upgraded to version 3.5.0.4

Troubleshooting: Plugin Conflicts​

If the upgrade fails with a fatal error like this:

Fatal error: Cannot declare class PKP\plugins\generic\somePlugin\SomePlugin,
because the name is already in use in ...

Temporarily move the conflicting plugin out of the way and re-run:

mv /path/to/ojs/plugins/generic/conflictingPlugin ~/conflictingPlugin_backup
php tools/upgrade.php upgrade

After the upgrade succeeds, either restore the plugin (if a 3.5-compatible version exists) or remove it permanently.

Step 7 — Clear Caches​

Clear all cached files so the new version loads cleanly:

php tools/fileCacheTool.php --flush-all

You can also clear caches from the admin panel: Administration → Clear Caches and Clear Template Cache.

Step 8 — Verify the Upgrade​

Run the built-in version check to confirm all components are aligned:

php tools/upgrade.php check

Expected output:

Code version:      3.5.0.4
Database version:  3.5.0.4
Latest version:    3.5.0.4
Your system is up-to-date
tip

All three version numbers must match. If the database version differs from the code version, the database upgrade did not complete — re-run Step 6.

Step 9 — Database Health Check​

After the upgrade, verify database integrity.

Check for corrupt tables​

mysqlcheck -u YOUR_DB_USER -p --check YOUR_DB_NAME

Every table should return OK. Any table showing error or corrupted needs repair before the site is put back into production.

Check table count and total size​

mysql -u YOUR_DB_USER -p YOUR_DB_NAME -e "
SELECT
  COUNT(*) AS total_tables,
  ROUND(SUM(data_length + index_length) / 1024 / 1024, 2) AS total_size_mb
FROM information_schema.tables
WHERE table_schema = 'YOUR_DB_NAME';"

Check for duplicate rows​

mysql -u YOUR_DB_USER -p YOUR_DB_NAME -e "
SELECT 'versions' AS table_name, product AS key1, COUNT(*) AS duplicates
FROM versions GROUP BY product, major, minor, revision, build HAVING COUNT(*) > 1
UNION ALL
SELECT 'users', email, COUNT(*)
FROM users GROUP BY email HAVING COUNT(*) > 1
UNION ALL
SELECT 'plugin_settings', CONCAT(plugin_name,'|',setting_name), COUNT(*)
FROM plugin_settings GROUP BY plugin_name, context_id, setting_name HAVING COUNT(*) > 1
UNION ALL
SELECT 'journal_settings', CONCAT(journal_id,'|',setting_name,'|',locale), COUNT(*)
FROM journal_settings GROUP BY journal_id, setting_name, locale HAVING COUNT(*) > 1;"
tip

An empty result means no duplicates — your database is clean.

Step 10 — Cleanup​

Once everything is verified, remove the downloaded package and extracted folder:

rm -rf ~/ojs-3.5.0-4/ ~/ojs-3.5.0-4.tar.gz
note

Keep your database and file backups for at least 2–4 weeks before deleting them.

Post-Upgrade Checklist​

  • Database backed up
  • Files backed up
  • OJS 3.5.0-4 package downloaded and extracted
  • New files synced (config, uploads, plugins preserved)
  • Database upgraded successfully
  • Code version, Database version, and Latest version all show 3.5.0.4
  • All database tables return OK
  • No duplicate rows found
  • Caches cleared
  • Site loads and admin login works — verify manually
  • Plugins functioning correctly — verify manually
  • Email sending works — send a test notification

Troubleshooting​

ProblemSolution
Fatal error: Cannot declare classPlugin conflict — move the plugin folder out, re-run upgrade, then restore or remove it
Successfully upgraded but site shows old versionClear browser cache and OJS template cache
Database version does not match code versionRe-run php tools/upgrade.php upgrade
Table shows error in mysqlcheckRun mysqlcheck --repair YOUR_DB_NAME for that table
White screen after upgradeCheck PHP error log; clear all caches; verify file permissions
Email not sending after upgradeRe-check SMTP settings in config.inc.php and test from Administration panel

Next Steps​