How to Upgrade OJS 3.x: Complete Migration Checklist

Upgrading Open Journal Systems (OJS) is one of the most anxiety-inducing tasks for journal managers. A failed upgrade can mean days of downtime, corrupted submission data, broken plugins, and frustrated reviewers. Yet staying on an outdated version exposes your journal to security vulnerabilities and missing critical features like improved metadata export, ORCID integration, and enhanced indexing compatibility. This guide provides a step-by-step checklist for upgrading OJS 3.x safely, whether you are moving from OJS 3.3 to 3.4 or catching up from an older release.

Before You Start: Pre-Upgrade Checklist

1. Verify your current version. Log into your OJS admin dashboard and check Administration > System Information. Note your exact version number. OJS 3.4 requires PHP 8.1 or higher, so if you are running PHP 7.4, you will need to upgrade PHP first.

2. Create a complete backup. Back up your entire OJS installation directory and your MySQL or MariaDB database. Use mysqldump for the database and tar for the files directory. This is non-negotiable: a backup is your rollback insurance if anything goes wrong. Store the backup off-server.

3. Audit your plugins. List every plugin installed on your journal. Check each plugin’s compatibility with your target OJS version. Third-party plugins from the PKP plugin gallery list compatible versions. Plugins that are not compatible will need to be disabled or replaced before upgrading.

4. Schedule downtime. Notify your editors, reviewers, and authors. A typical OJS upgrade takes 1-2 hours, but the process may extend if you encounter compatibility issues. Schedule the upgrade during your journal’s lowest-traffic period.

5. Set up a staging environment. The safest approach is to clone your production OJS to a staging server, run the upgrade there first, test everything, then repeat on production. Managed OJS hosting providers typically include staging environments as part of their service.

Step-by-Step Upgrade Process

Step 1: Put OJS in Maintenance Mode

In the OJS configuration file, enable maintenance mode to prevent users from accessing the journal during the upgrade. This prevents data corruption from concurrent access.

Step 2: Download and Extract the New Version

Download the latest OJS release from the official PKP website. Extract the archive to a temporary directory. Do NOT extract it directly over your existing installation yet.

Step 3: Merge Configuration and Custom Files

Copy your existing configuration file and any custom files (custom themes, modified templates, custom locale files) from the old installation to the new version’s directory. Be careful to merge, not overwrite, the new version’s default configuration.

Step 4: Copy the Files Directory

Your submission files, public files, and temporary files live in the files directory. Copy this entire directory from your old installation to the new one. This directory can be large, so allocate sufficient time for the transfer.

Step 5: Run the Upgrade Script

OJS includes a command-line upgrade tool. Navigate to your OJS installation directory and run the upgrade command. This applies database schema changes, migrates data, and updates internal version records. Monitor the output for any errors. If the upgrade fails, restore from your backup and investigate the error before retrying.

Step 6: Clear Caches and Rebuild

After the upgrade completes, clear the template cache, data cache, and CSS cache. Some upgrade issues manifest as visual glitches that are resolved by a simple cache clear.

Step 7: Test, Test, Test

Before disabling maintenance mode, verify:
– The homepage loads correctly
– You can log in as an admin, editor, author, and reviewer
– Submission workflow: create a test submission and move it through review stages
– Search functionality works
– DOIs resolve correctly
– OAI-PMH endpoint responds (check with a simple HTTP request)
– Google Scholar metadata is present on article pages
– All critical plugins are active and functional

Common Upgrade Pitfalls and Fixes

White screen after upgrade: Usually a PHP error. Check your PHP error log. Common causes include incompatible PHP version or a plugin that needs updating.

Database migration errors: These often occur when upgrading across multiple major versions. Consider upgrading incrementally (e.g., 3.2 to 3.3, then 3.3 to 3.4) rather than jumping directly.

Missing submission files: Ensure the files_dir path in the configuration matches the actual files directory location.

Broken URLs or missing pages: Check your rewrite rules (Apache htaccess or Nginx configuration). OJS uses URL rewriting for clean URLs, and an upgrade may require updating these rules.

When to Consider Professional Migration Services

If your journal has custom themes, custom plugins, or a large submission database, a professional migration service can save you significant time and reduce risk. Professional services include staging environment setup, compatibility testing, staged migration with zero-downtime options, and post-migration verification of all indexing endpoints.

Learn more about our OJS upgrade and migration services for a safe, seamless transition.

Frequently Asked Questions

How long does an OJS upgrade take?

A straightforward upgrade from one minor version to the next typically takes 1-2 hours including testing. Major version upgrades or upgrades from very old versions can take 4-8 hours. The database migration step scales with your journal’s data volume.

Can I upgrade OJS without downtime?

Yes, with a staging environment approach: upgrade a clone of your production site, verify everything works, then swap the upgraded version in. DNS or load balancer switchover can reduce visible downtime to seconds. Managed hosting providers handle this automatically.

Will my custom theme still work after upgrading?

Custom themes may need updates to remain compatible with new OJS versions. OJS 3.4 introduced changes to the theming system. Test your theme thoroughly on a staging environment before upgrading production.

What version of PHP does OJS 3.4 require?

OJS 3.4 requires PHP 8.1 or higher. If your server runs PHP 7.4, you must upgrade PHP before upgrading OJS. OJS 3.3 supports PHP 7.4 as a minimum.

What happens to my DOIs during an upgrade?

DOIs are permanent identifiers managed by CrossRef or DataCite and are not affected by an OJS upgrade. As long as your DOI plugin is correctly configured after the upgrade, existing DOIs continue to resolve normally.