Inside the 3rd UNITE: OJS Upgradation & System Management
(Xpertno Research Center—UNITE Series News Report)
During the second segment of the 3rd Universal Network for International Training and Education (UNITE), Nasir Razzaq (KA: Raja Nasir) conducted an in-depth technical session on OJS system upgradation, configuration management, and safe migration practices. This part of the training focused on helping journal managers understand how to upgrade their OJS installations without losing data, breaking the system, or causing indexing failures—a common challenge for many academic journals.
A Quick Recap
The session opened with an explanation of why upgrading OJS is more sensitive and complex than a fresh installation. Raja stressed that upgrading requires careful handling of configuration files, database structures, plugins, themes, and file directories, because even a minor mistake can make the entire journal inaccessible.
He emphasized the importance of backing up the full system—including files, config settings, database, and custom themes—before attempting any upgrade.
According to Raja, many journals collapse simply because they try upgrading without proper backups or they overwrite essential settings.
Why Upgrading Is More Complex Than Installation
Raja clarified that a first-time installation is simple because the system begins with fresh files and an empty database. Upgrading, however, has risks:
- Old plugins may not be compatible with the new version
- PHP version changes can break the system
- config.inc.php settings get overwritten if copied incorrectly
- Custom themes may stop working
- File permissions often need to be reset.
- Database migrations must run successfully
He pointed out that journals often panic when an upgrade partially completes but fails midway—a situation that only backups can save.
The Upgrade Procedure
Raja explained the upgrade sequence in detail so that participants understood its importance, not just how to do it.
1. Backup Everything Before You Start
Raja began by emphasizing the first and most important rule: always create a complete backup before starting. He explained that a proper backup includes the entire OJS directory, the secure “files” folder, the full MySQL or MariaDB database export, and any custom themes or images added manually. He said,
"Upgrade failures usually occur when administrators attempt the process without backup, leaving them with no way to recover if the upgrade breaks or stops halfway."
2. Download the Latest OJS Version
Raja recommended downloading only the official version from the PKP website because modified or zipped third-party copies often contain broken vendor files. After downloading the latest version, upload it to the server and extract all files.
3. Replace Files Carefully
Once the new version is extracted, Raja explained how to replace the system files carefully without damaging the existing journal structure. He instructed participants to delete all old application files except the secure “files” folder, the “public” folder, and the existing config.inc.php file (which is kept temporarily for copying essential settings).
The new OJS version should then be uploaded and extracted properly, ensuring that the “files” and “public” directories are never overwritten, as doing so results in immediate data loss.
Raja also emphasized the importance of taking separate backups of the “plugins” and “templates” folders by downloading them as zip files. He explained that when upgrading from an older version to a newer one, OJS sometimes introduces changes that cause plugin or template incompatibilities, and having these backups allows administrators to restore or compare specific files whenever an error appears during migration. He further recommended backing up the custom “styles” folder if the journal uses a customized theme, since certain themes may not exist or may behave differently in the new version.
He He noted that careless file replacement—especially overwriting the uploads directory or removing essential plugin/theme assets—was one of the most common reasons journals crash during the upgrade process.
4. Restore Key Settings from Old config.inc.php
In the next step, Raja discussed the importance of restoring critical settings from the old config.inc.php file to the new config.inc.php. He explained that only a few specific lines need to be copied, and copying unnecessary or outdated lines can break the upgraded system. Raja guided participants through each required setting one by one, clarifying where they appear in the file and why they matter during migration.
The required settings included the following:
app_key
Raja explained that the app_key is introduced in newer OJS versions (such as 3.5.0-1). Older versions do not contain this line, so users should not attempt to create or copy it manually. In the new configuration file, the app_key appears near the beginning (around line 29), and administrators must leave it untouched because the system generates it automatically during the upgrade process.
installed = Off
He reminded participants that the installed option should remain off (usually around line 33) before running the upgrader. Set it to “on” after upgrading.
base_url
The journal’s existing base_url should be copied exactly from the old file to the new one. This ensures that OJS continues to point to the correct domain or subdomain after migration.
allowed_hosts
In the general settings block (between lines 90–100 in most versions), users must locate the allowed_hosts field and copy the old value into the new configuration file. Raja explained that missing or incorrect host entries often result in security blocks or failed logins.
Database configuration
The next section requires copying the database driver, database name, username, and password exactly as they appear in the old configuration file. Any mistake in these lines causes database connection errors and prevents OJS from loading after the upgrade.
File directories
Under the file settings section, users must copy the paths for files_dir and public_files_dir from the old configuration file. These paths instruct OJS where to find uploaded manuscripts, images, and other content. If they are wrong, submissions may disappear or become inaccessible.
Email/SMTP settings (if used)
Raja added that if the journal uses SMTP for outgoing emails, those lines should also be copied from the old configuration file. Journals that do not use SMTP can skip this section entirely.
Any custom settings from the old system
If administrators had manually adjusted any additional settings in their previous installation, those custom values should also be transferred into the new file. However, Raja cautioned them to avoid copying deprecated or version-specific settings that no longer exist in newer releases.
He also highlighted the debugging setting, located after line 500 in most versions.
He recommended turning on the error display temporarily during the upgrade process because it helps identify issues quickly if the migration fails.
Raja warned that if any of these values are misplaced, skipped, or incorrectly copied, the upgraded system may show blank pages, missing submissions, login failures, or inaccessible content. He reminded participants that this is one of the most sensitive stages of upgrading and requires slow, careful attention.
Raja also advised participants to review their plugins before starting the upgrade, especially when moving from an older OJS version to the latest release. He explained that certain plugins—particularly the older DOI plugin and any outdated or unused extensions—should be disabled before upgrading.
He further explained that unnecessary plugins, deprecated tools, or custom modifications should also be turned off temporarily to avoid conflicts, as plugin incompatibility is one of the most common reasons OJS upgrades fail. Once the upgrade is complete, administrators can reactivate essential plugins or install updated versions from the AIO repository.
5. Run the Upgrader
When the updated version is opened in the browser, OJS automatically prompts for an upgrade. Raja instructed participants to:
- run the upgrade in one go
- avoid refreshing the page
- ensure PHP time limits are high enough
- check the upgrade log for warnings or failures
If the server times out, the upgrade may fail; however, the backup allows for a rollback.
6. Check Themes, Plugins, and Navigation After Upgrade
He advised participants to re-enable or reinstall plugins, examine if custom themes require updates, confirm that navigation menus, roles, and settings are intact, and verify indexing plugins such as Google Scholar. Some plugins are deprecated after major upgrades and may need to be replaced.
Raja reassured participants that upgrading is not difficult if the process is followed correctly:
“The upgrade only fails when you skip backups or copy files randomly. If you follow a clean method, OJS upgrades smoothly. Always read PKP release notes before upgrading any version.”