PKP/Upgrading
Back to System Admin
There are 3 options for upgrading a PKP system. See below for details.
Contents
- 1 Step 1 - Upgrade Software
- 2 Step 2 - Apply Recommended Patches Before Upgrading The Database
- 3 Step 3 - Perform The Database Upgrade
- 4 Step 4 - Warning
- 5 My Upgrade Procedure
- 5.1 Step 1 - Make backups
- 5.2 Step 2 - Get and extract the software
- 5.3 Step 3 - Deploy the new software
- 5.4 Step 4 - Check for config differences
- 5.5 Step 5 - Do the upgrade
- 5.6 Step 6 - Restore the "public" sub-folders
- 5.7 Step 7 - Fix file ownerships/permissions
- 5.8 Step 8 - Fix the "User Home" link - Only for stand-alone systems at Stellenbosch University
- 6 References
Step 1 - Upgrade Software
Option A - Patch Upgrade
Patch files for older releases of OJS can be downloaded from the OJS web site. To update by patching, download the appropriate patch file for your current version of OJS and run the following command from your OJS directory: $ patch -p1 < PATCH_FILE "PATCH_FILE" should be replaced with the path to the decompressed patch file that was downloaded, e.g. "ojs-2.0_to_2.0.1.patch". Alternatively, OJS 2.0.1 and later provide a command-line tool to automatically download and apply the appropriate patch to upgrade to the latest release. To use this tool run the following command from your OJS directory: $ php tools/upgrade.php patch Note that this will require the GNU patch tool to be installed. GNU patch is included in most *NIX distributions, and is available for Windows and Solaris as a download. Windows users may need to work around a patch bug by converting the line-endings in the patch file from UNIX to DOS; to do this, open the patch file in Notepad and save it again. Patch upgrades will NOT include any binary files that were introduced in the new version, i.e. any GIF images that are needed in the new version but were not included in the old version. To find a list of binaries that should be manually added after applying the patch, search the patch file for lines like: "Binary files (filename here) differ" (not including the quotes). These files can be found in the distribution archive..
Option B - Git Upgrade
See: https://wildlyinaccurate.com/a-hackers-guide-to-git for git help.
If your instance of OJS was checked out from github (see docs/README-GIT), you can update the OJS code using a git client. To update the OJS code from a git check-out, run the following command from your OJS directory: $ git rebase --onto <new-release-tag> <previous-release-tag> This assumes that you have made local changes and committed them on top of the old release tag. The command will take your custom changes and apply them on top of the new release. This may cause merge conflicts which have to be resolved in the usual way, e.g. using a merge tool like kdiff3. "TAG" should be replaced with the git tag corresponding to the new release. OJS release version tags are of the form "ojs-MAJOR_MINOR_REVSION-BUILD". For example, the tag for the initial release of OJS 2.1.0 is "ojs-2_1_0-0". Consult the README of the latest OJS package or the OJS web site for the tag corresponding to the latest available OJS release. Note that attempting to update to an unreleased version (e.g., using the HEAD tag to obtain the bleeding-edge OJS code) is not recommended for anyone other than OJS or third-party developers; using experimental code on a production deployment is strongly discouraged and will not be supported in any way by the OJS team.
Option C - Full Package Upgrade
It is also possible to upgrade by downloading the complete package for the latest release of OJS: - Download and decompress the package from the OJS web site - Make a copy of the config.inc.php provided in the new package - Move or copy the following files and directories from your current OJS installation: - config.inc.php - public/ - Your uploaded files directory ("files_dir" in config.inc.php), if it resides within your OJS directory - Replace the current OJS directory with the new OJS directory, moving the old one to a safe location as a backup - Be sure to review the Configuration Changes section of the release notes in docs/release-notes/README-(version) for all versions between your original version and the new version. You may need to manually add new items to your config.inc.php file.
Step 2 - Apply Recommended Patches Before Upgrading The Database
No matter which method you select to upgrade the software, it is advised to also apply any subsequent patches as well.
Starting with OJS version 2.3.3-2, the Public Knowledge Project development team maintains a publicly-available list of recommended patches for each release. These will add no new functionality and will typically consist of small, easy-to-read patches for specific issues. A Recommended Patches list for your version of OJS can be found on the PKP development wiki: <http://pkp.sfu.ca/wiki/index.php/OJS_Recommended_Patches> Regardless of the method you used to download and apply the official system files, you will also want to review the list of recommended patches specific to your OJS version, and apply as necessary. To apply a recommended patch, open the bug report and download the attached patch file(s). (Note that bug reports can quite often include a number of patches, some relevant to the application (ie. OJS) and version you are running, and some not. Ensure that you download all and only the patches specific to your application and version.) For each patch you download, first attempt a dry-run application of the patch, to ensure that it applies cleanly: $ patch -p1 --dry-run < PATCH_FILE If the patch applies cleanly, then run the following command, which will actually apply the patch: $ patch -p1 < PATCH_FILE "PATCH_FILE" should be replaced with the path to the patch file that was downloaded, e.g. "6276-ojs.patch".
Step 3 - Perform The Database Upgrade
After obtaining the latest OJS code, an additional script must be run to complete the upgrade process by upgrading the OJS database and potentially executing additional upgrade code.
This script can be executed from the command-line or via the OJS web interface.
Option 1. Command-line
If you have the CLI version of PHP installed (e.g., /usr/bin/php), you can upgrade the database as follows: - Edit config.inc.php and change "installed = On" to "installed = Off" - Run the following command from the OJS directory (not including the $): $ php tools/upgrade.php upgrade - Re-edit config.inc.php and change "installed = Off" back to "installed = On"
Option 2. Web
If you do not have the PHP CLI installed, you can also upgrade by running a web-based script. To do so: - Edit config.inc.php and change "installed = On" to "installed = Off" - Open a web browser to your OJS site; you should be redirected to the installation and upgrade page - Select the "Upgrade" link and follow the on-screen instructions - Re-edit config.inc.php and change "installed = Off" back to "installed = On"
Step 4 - Warning
The upgrade, with the latest patches, should now be complete. Please take note of the warnings below.
- Check all settings for updates from the previous version.
- If something goes wrong after an upgrade and patches have been applied, then assume nothing about the previous settings, especially that they have been migrated correctly to the new version!
- It is prudent to check all settings again per journal.
My Upgrade Procedure
Step 1 - Make backups
After logging into the server as the OJS admin user, type the following;
sudo -i
Make a backup folder.
mkdir /root/backup
Copy the old software to the backup folder.
cp -Rv /var/www /root/backup
OR
cp -Rv /var/www/html /root/backup
Make a backup of the database.
mysqldump -A > /root/backup/mysql-db-backup.sql
Step 2 - Get and extract the software
Type the following;
cd /tmp
wget http://web.lib.sun.ac.za/files/ojs/ojs-2.4.8-1.tar.gz
tar -xzvf ojs-2.4.8-1.tar.gz
Step 3 - Deploy the new software
Type the following to clear the web folder;
rm -rfv /var/www/*
OR
rm -rfv /var/www/html/*
Then copy over the new software
cp -Rv /tmp/ojs-2.4.8-1/* /var/www/
OR
cp -Rv /tmp/ojs-2.4.8-1/* /var/www/html/
Step 4 - Check for config differences
Compare the config file in the /root/backup folder with the new one in /var/www OR /var/www/html.
cp /root/backup/www/config.inc.php /tmp/
chmod 0777 /tmp/config.inc.php
Then use "Meld" to update the differences.
Step 5 - Do the upgrade
Follow the procedures above to do the upgrade, using "Step 1 - Option C" and "Step 3 - Option 1".
Step 6 - Restore the "public" sub-folders
Copy the folders over.
cp -Rv /root/backup/www/public/* /var/www/public/
OR
cp -Rv /root/backup/www/html/public/* /var/www/html/public/
Fix file ownership.
chown -R www-data.root /var/www/public/
OR
chown -R www-data.root /var/www/html/public/
Fix file permissions.
chmod -R 0777 /var/www/public
OR
chmod -R 0777 /var/www/html/public
Step 7 - Fix file ownerships/permissions
Type the following;
chown -R www-data.root /var/www
OR
chown -R www-data.root /var/www/html
Then fix file permissions.
chmod 0777 -R /var/www/cache
chmod 0777 -R /var/www/plugins
chmod 0777 -R /var/www/public
chmod 0644 /var/www/config.inc.php
OR
chmod 0777 -R /var/www/html/cache
chmod 0777 -R /var/www/html/plugins
chmod 0777 -R /var/www/html/public
chmod 0644 /var/www/html/config.inc.php
Step 8 - Fix the "User Home" link - Only for stand-alone systems at Stellenbosch University
See: http://wiki.lib.sun.ac.za/index.php/PKP/Bug_Fixes#Fix_.22User_Home.22_error