Upgrading from OJS 2.x / 3.2 to OJS 3.3 LTS: Step-by-Step
Detailed technical playbook for transitioning legacy OJS 2.x and OJS 3.2 journals to OJS 3.3 LTS. Covers database preparation, PHP environment adjustments, and CLI migration execution.
Real Problem
Thousands of university journals remain stranded on unsupported OJS 2.x installations running end-of-life PHP 5.6 or 7.0 because their technical teams fear breaking historical issue structures.
Practical Solution
Follow this proven multi-stage migration pipeline: audit legacy plugins, sanitize database schemas, execute the interim upgrade to 3.3 LTS via CLI, and rebuild the article galley hierarchy.
The Historic Shift from OJS 2.x to OJS 3.x
Open Journal Systems 2.x was architected in the early 2000s, utilizing monolithic page structures, framesets, and heavy table-based layouts. OJS 3 represented a ground-up revolution: introducing a responsive editorial backend, separation of public reader views from editorial workflows, and flexible submission stages.
For institutions that delayed upgrading, moving from OJS 2.4.8 to OJS 3.3 LTS represents a monumental leap in user experience, mobile responsiveness, and cybersecurity.
Stage 1: Pre-Upgrade Database Hygiene
Legacy OJS 2.x databases often contain thousands of orphaned rows caused by past incomplete deletions. If an article galley references an article_id that no longer exists in the articles table, the OJS 3 foreign key generator will abort during the upgrade.
Run cleanup queries prior to upgrading:
DELETE FROM article_galleys WHERE article_id NOT IN (SELECT article_id FROM articles);
DELETE FROM review_assignments WHERE submission_id NOT IN (SELECT article_id FROM articles);
DELETE FROM edit_decisions WHERE article_id NOT IN (SELECT article_id FROM articles);
Stage 2: Setting Up the Codebase and Files
Download the official OJS 3.3 LTS tarball and extract it into your web root:
wget https://pkp.sfu.ca/ojs/download/ojs-3.3.0-19.tar.gz
tar -xzvf ojs-3.3.0-19.tar.gz -C /var/www/ojs33/
Copy over your legacy public files directory:
cp -r /var/www/ojs2/public/* /var/www/ojs33/public/
Update config.inc.php with the database credentials and files_dir path. Set installed = Off.
Stage 3: Executing the CLI Upgrade
Run the upgrade command from your terminal:
cd /var/www/ojs33
php tools/upgrade.php check
php tools/upgrade.php upgrade
During the migration, OJS will:
1. Reorganize submissions into the new submissions and publications architecture.
2. Convert article metadata into localized publication_settings rows.
3. Migrate user accounts into modern role-based permission stages.
4. Restructure files into the new genre-based file storage hierarchy.
Stage 4: Post-Migration Rebuilding
Once the terminal reports Successfully upgraded to version 3.3.0.x, set installed = On in config.inc.php.
Navigate to the administration dashboard, clear all data and template caches, and update your site theme. Re-enable the Crossref and DOAJ export plugins to ensure ongoing DOI deposit workflows resume seamlessly.
Step-by-Step Action Plan
Pre-Upgrade Archival Snapshot
Create cold backups of the legacy OJS files folder, MySQL database, and config.inc.php.
Provision Intermediate PHP 7.4/8.0 Host
Configure a bridge server running PHP 7.4 or 8.0, as OJS 3.3 upgrade scripts require modern PHP syntax.
Clean Orphaned Database Records
Purge dangling records in article_galleys and review_assignments that lack corresponding parent submission IDs.
Run the OJS 3.3 Upgrade Script
Execute php tools/upgrade.php upgrade and monitor the migration through each stage.
Re-enable & Upgrade Plugins
Update QuickSubmit, Crossref, and custom theme plugins to their verified OJS 3.3 release packages.
Questions People Usually Ask
Why is OJS 3.3 considered the premier Long-Term Support (LTS) release?
OJS 3.3 LTS is recognized as the most battle-tested and stable release in PKP history. It has received years of security patches and provides maximum compatibility with third-party plugins.
What happens to custom OJS 2.x themes during the upgrade?
OJS 2.x themes are completely incompatible with OJS 3.x due to the replacement of old Smarty 2 markup with modern HTML5/Bootstrap-based templates. Journals must adopt an OJS 3-compatible theme such as Default, Health Sciences, or a bespoke child theme.
Can an OJS 2.4.8 database be upgraded directly to OJS 3.3 in one step?
Yes! PKP includes migration scripts in OJS 3.3 to upgrade directly from OJS 2.4.8, provided database collation errors and orphaned records are cleaned prior to execution.
Still Running Legacy OJS 2 or 3.2?
AcademiaTech specializes in modernizing legacy OJS systems, migrating decades of archives to modern, responsive, and secure OJS 3.3 LTS platforms.