PKP/Upgrading

Back to System Admin

There are 3 options for upgrading a PKP system. See below for details.

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

References

• https://pkp.sfu.ca/ojs/UPGRADE
• http://pkp.sfu.ca/wiki/index.php/OJS_Recommended_Patches