CINXE.COM
How to Upgrade
<!DOCTYPE html> <html lang="en-US"> <title>How to Upgrade</title> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta property="og:title" content="How to Upgrade" /> <meta property="og:site_name" content="PKP Docs"> <meta name="description" content="How to upgrade Open Journal Systems (OJS) and other PKP software, including a step-by-step tutorial."> <meta property="og:description" content="How to upgrade Open Journal Systems (OJS) and other PKP software, including a step-by-step tutorial."> <meta property="og:url" content="https://docs.pkp.sfu.ca/dev/upgrade-guide/en/"> <link type="text/css" href="/css/book.css" rel="stylesheet" media="all"> <script defer src="/assets/js/smooth-scroll.polyfills.min.js"></script> <script defer src="/assets/js/fontawesome.min.js"></script> <body class="body--withSidebar"> <div class="bookHeader"> <button id="sidebarControl" class="bookHeader__sidebarControl"> <span class="fa fa-bars" aria-hidden="true"></span> <span class="fa fa-times" aria-hidden="true"></span> <span class="-screenReader">Toggle Menu</span> </button> <a class="bookHeader__logo" href="/"> <img src="/img/logo-on-white.png" alt="PKP Docs" class="bookHeader__logoImage"> </a> <div class="bookHeaderTools"> </div> </div> <div class="book"> <a href="#sidebar" class="-screenReader"> Jump to table of contents </a> <div class="book__page"> <div class="book__content"> <div class="book__improve"> <a href="https://github.com/pkp/pkp-docs/edit/main/dev/upgrade-guide/en/index.md"> Edit this page </a> or <a href="https://pkp.sfu.ca/documentation-feedback/"> make a suggestion </a> </div> <h1 id="introduction-how-to-upgrade"> Introduction: How to Upgrade </h1> <p>This guide will help you upgrade Open Journal Systems (OJS). It describes the knowledge and tools you will need to upgrade your software, and provides a step-by-step tutorial you can follow.</p> <p>The instructions below describe how to upgrade OJS when it is running on a LAMP (Linux, Apache, MySQL, PHP) stack. However, these steps can be adapted to upgrade other PKP software (OMP, OPS) as well as perform upgrades in different server environments.</p> <blockquote class="notice"> <p>Want to know when new versions are released and what’s new? Read the <a href="https://forum.pkp.sfu.ca/c/announcements/10">announcements forum</a>.</p> </blockquote> <h2 id="contributors"> Contributors <a href="#contributors" class="book_heading_anchor" title="Link to Contributors section">#</a> </h2> <p>Authors: Marc Bria, Clinton Graham, Kaitlin Newson, Andrea Pritt. Dulip Withanage</p> <h2 id="required-knowledge-and-tools"> Required Knowledge and Tools <a href="#required-knowledge-and-tools" class="book_heading_anchor" title="Link to Required Knowledge and Tools section">#</a> </h2> <blockquote class="warning"> <p><strong>Do not proceed</strong> if you do not have experience with the items listed below. A mistake during upgrade can lead to unrecoverable errors.</p> </blockquote> <p>In order to use this guide, you will need experience with basic system administration tools, as well as an understanding of the tech stack in your server configuration. You should have:</p> <ul> <li>Basic GNU/Linux administration skills</li> <li>Server credentials, including database credentials</li> <li>Knowledge of your server stack (this guide assumes a LAMP stack)</li> <li>The ability to access your server’s terminal (SSH)</li> <li>An identified OJS release package to upgrade to (downloaded in step 5)</li> </ul> <h3 id="preparing-to-upgrade"> Preparing to Upgrade <a href="#preparing-to-upgrade" class="book_heading_anchor" title="Link to Preparing to Upgrade section">#</a> </h3> <p>Before starting your upgrade, you can review <code class="language-plaintext highlighter-rouge">docs/release-notes</code> and the <a href="/dev/release-notebooks/">release notebook</a> for your upgrade version to learn about important changes introduced in each version. The <code class="language-plaintext highlighter-rouge">config.TEMPLATE.inc.php</code> includes a description for most configuration parameters.</p> <p>Note that an upgrade may take from a few minutes up to several hours depending on the size of your site.</p> <h3 id="a-note-on-versions"> A Note on Versions <a href="#a-note-on-versions" class="book_heading_anchor" title="Link to A Note on Versions section">#</a> </h3> <p>All PKP applications use a variant of <a href="https://semver.org">Semantic Versioning</a> described as <code class="language-plaintext highlighter-rouge">major.minor.revision-build</code>. Each point of the version number describes the kind of changes you can expect.</p> <table> <thead> <tr> <th>Type</th> <th>Example</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td>major</td> <td><code class="language-plaintext highlighter-rouge">3.x.x-x</code></td> <td>Comprehensive breaking changes that may effect plugins, server configuration and all parts of the software.</td> </tr> <tr> <td>minor</td> <td><code class="language-plaintext highlighter-rouge">3.3.x-x</code></td> <td>Breaking changes that may effect plugins and server configuration.</td> </tr> <tr> <td>revision</td> <td><code class="language-plaintext highlighter-rouge">3.3.3-x</code></td> <td>New features may be added but breaking changes are kept to a minimum.</td> </tr> <tr> <td>build</td> <td><code class="language-plaintext highlighter-rouge">3.3.3-3</code></td> <td>No breaking changes or database migrations.</td> </tr> </tbody> </table> <p>In order to understand the upgrade process, you should first determine the size of the upgrade “jump”. A jump from version <code class="language-plaintext highlighter-rouge">3.3.0-6</code> to <code class="language-plaintext highlighter-rouge">3.3.0-7</code> can likely be done with minimal down time. However, a jump from version <code class="language-plaintext highlighter-rouge">2.4</code> to <code class="language-plaintext highlighter-rouge">3.2</code> will be a long, complex process with a higher risk of introducing problems.</p> <p>You should always perform upgrades in a test environment first, even when upgrading from one build to another.</p> <h3 id="upgrading-from-2x"> Upgrading from 2.x <a href="#upgrading-from-2x" class="book_heading_anchor" title="Link to Upgrading from 2.x section">#</a> </h3> <p>It is not always possible to upgrade from 2.x to any version of 3.x. When performing upgrades from a 2.x version, you should first upgrade to in-between versions. The table below describes the necessary steps.</p> <table> <thead> <tr> <th>From</th> <th>To</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td><code class="language-plaintext highlighter-rouge">< 2.4.8</code></td> <td><code class="language-plaintext highlighter-rouge">2.4.8-x</code></td> <td>Before upgrading to 3.x, make sure you are upgraded to the latest <code class="language-plaintext highlighter-rouge">2.4.8-x</code> build.</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">2.4.8-x</code></td> <td><code class="language-plaintext highlighter-rouge">3.2.1-x</code></td> <td>You can not upgrade to 3.3.x or later from 2.x</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">3.2.1-x</code></td> <td><code class="language-plaintext highlighter-rouge">3.3 >=</code></td> <td>Upgrade from <code class="language-plaintext highlighter-rouge">3.2.1-x</code> to any version 3.3 or later.</td> </tr> </tbody> </table> <h2 id="upgrade-tutorial"> Upgrade Tutorial <a href="#upgrade-tutorial" class="book_heading_anchor" title="Link to Upgrade Tutorial section">#</a> </h2> <p>The following tutorial provides a recommended step-by-step process to safely upgrade OJS. However, each installation is different and your server environment might differ substantially. In all cases, you should review and understand the commands before executing them.</p> <p>During the tutorial, you will see commands for <a href="https://www.debian.org/">Debian</a> or <a href="https://www.redhat.com/en/technologies/linux-platforms/enterprise-linux">RHEL</a> Linux systems. You should only run the command appropriate to your server.</p> <h3 id="1-set-environment-variables"> 1. Set Environment Variables <a href="#1-set-environment-variables" class="book_heading_anchor" title="Link to 1. Set Environment Variables section">#</a> </h3> <p>The tutorial below uses the following variables to simplify the terminal commands.</p> <table> <thead> <tr> <th>VARIABLE</th> <th>Default</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td>WEB_USER</td> <td><code class="language-plaintext highlighter-rouge">www-data</code></td> <td>Webserver user</td> </tr> <tr> <td>WEB_GROUP</td> <td><code class="language-plaintext highlighter-rouge">www-data</code></td> <td>Webserver user’s group</td> </tr> <tr> <td>OJS_ROOT_PATH</td> <td><code class="language-plaintext highlighter-rouge">/var/www</code></td> <td>OJS root folder</td> </tr> <tr> <td>OJS_WEB_PATH</td> <td><code class="language-plaintext highlighter-rouge">/var/www/html</code></td> <td>OJS web root folder</td> </tr> <tr> <td>OJS_DB_HOST</td> <td><code class="language-plaintext highlighter-rouge">db</code></td> <td>Database host’s name</td> </tr> <tr> <td>OJS_DB_USER</td> <td><code class="language-plaintext highlighter-rouge">ojs</code></td> <td>Database user</td> </tr> <tr> <td>OJS_DB_PASSWORD</td> <td><code class="language-plaintext highlighter-rouge">ojsPwd</code></td> <td>Database password</td> </tr> <tr> <td>OJS_DB_NAME</td> <td><code class="language-plaintext highlighter-rouge">ojs</code></td> <td>Database name</td> </tr> <tr> <td>OJS_BACKUP_PATH</td> <td><code class="language-plaintext highlighter-rouge">/srv/backup/ojs</code></td> <td>Folder to store your backups</td> </tr> <tr> <td>OJS_VERSION</td> <td><code class="language-plaintext highlighter-rouge">ojs-3.3.0-8</code></td> <td>Version as in the ojs filename</td> </tr> <tr> <td>DATE</td> <td><code class="language-plaintext highlighter-rouge">YYYYMMDD-HH:MM:SS</code></td> <td>The current system date and time</td> </tr> </tbody> </table> <p>Rewrite the command below to set up these variables with the correct values for your installation.</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$ WEB_USER</span><span class="o">=</span><span class="s2">"www-data"</span> <span class="o">&&</span> <span class="se">\</span> <span class="nv">WEB_GROUP</span><span class="o">=</span><span class="s2">"www-data"</span> <span class="o">&&</span> <span class="se">\</span> <span class="nv">OJS_ROOT_PATH</span><span class="o">=</span><span class="s2">"/var/www"</span> <span class="o">&&</span> <span class="se">\</span> <span class="nv">OJS_WEB_PATH</span><span class="o">=</span><span class="s2">"/var/www/html"</span> <span class="o">&&</span> <span class="se">\</span> <span class="nv">OJS_DB_HOST</span><span class="o">=</span><span class="s2">"db"</span> <span class="o">&&</span> <span class="se">\</span> <span class="nv">OJS_DB_USER</span><span class="o">=</span><span class="s2">"ojs"</span> <span class="o">&&</span> <span class="se">\</span> <span class="nv">OJS_DB_PASSWORD</span><span class="o">=</span><span class="s2">"ojsPwd"</span> <span class="o">&&</span> <span class="se">\</span> <span class="nv">OJS_DB_NAME</span><span class="o">=</span><span class="s2">"ojs"</span> <span class="o">&&</span> <span class="se">\</span> <span class="nv">OJS_BACKUP_PATH</span><span class="o">=</span><span class="s2">"/srv/backup/ojs"</span> <span class="o">&&</span> <span class="se">\</span> <span class="nv">OJS_VERSION</span><span class="o">=</span><span class="s2">"ojs-3.3.0-8"</span> <span class="o">&&</span> <span class="se">\</span> <span class="nv">OJS_PUBLIC_PATH</span><span class="o">=</span><span class="s2">"</span><span class="nv">$OJS_WEB_PATH</span><span class="s2">/public"</span> <span class="o">&&</span> <span class="se">\</span> <span class="nv">OJS_PRIVATE_PATH</span><span class="o">=</span><span class="s2">"</span><span class="nv">$OJS_ROOT_PATH</span><span class="s2">/files"</span> <span class="o">&&</span> <span class="se">\</span> <span class="nv">DATE</span><span class="o">=</span><span class="si">$(</span><span class="nb">date</span> <span class="s2">"+%Y%m%d-%H:%M:%S"</span><span class="si">)</span> </code></pre></div></div> <h3 id="2-disable-the-execution-of-background-tasks"> 2. Disable the execution of background tasks <a href="#2-disable-the-execution-of-background-tasks" class="book_heading_anchor" title="Link to 2. Disable the execution of background tasks section">#</a> </h3> <h4 id="shutdown-the-execution-of-scheduled-tasks"> Shutdown the execution of scheduled tasks <a href="#shutdown-the-execution-of-scheduled-tasks" class="book_heading_anchor" title="Link to Shutdown the execution of scheduled tasks section">#</a> </h4> <p>If you’re using a <code class="language-plaintext highlighter-rouge">CRON</code>-like application to execute the <code class="language-plaintext highlighter-rouge">php tools/runScheduledTasks.php</code> periodically, please disable it or the specific tasks. If you’re using the <code class="language-plaintext highlighter-rouge">Acron</code> plugin, then disable the plugin.</p> <p>After disabling, it’s better to ensure that all tasks had a time to be completed, you can inspect the database, more specifically the <code class="language-plaintext highlighter-rouge">scheduled_tasks</code> table, and ensure that the <code class="language-plaintext highlighter-rouge">last_run</code> field of all entries points to a date slightly in the past (a couple of hours should suffice to execute everything).</p> <h4 id="shutdown-the-worker-gracefully-only-applicable-for-ojs-34"> Shutdown the worker gracefully (only applicable for OJS +3.4) <a href="#shutdown-the-worker-gracefully-only-applicable-for-ojs-34" class="book_heading_anchor" title="Link to Shutdown the worker gracefully (only applicable for OJS +3.4) section">#</a> </h4> <p>OJS 3.4 introduced Laravel jobs to process long running tasks, and you might also setup a separated task (worker) to execute these jobs out of the request cycle of the application, as explained in the <a href="/admin-guide/en/deploy-jobs">admin-guide</a>. If you’re using the worker, it’s needed to stop it gracefully before starting the upgrade.</p> <p>The worker can be gracefully interrupted by sending a <code class="language-plaintext highlighter-rouge">SIGTERM</code> signal to the PHP process, notice that OJS 3.4.0-5 has introduced a <a href="/admin-guide/en/deploy-jobs"><code class="language-plaintext highlighter-rouge">restart</code> command to the worker</a>, which does basically the same. If you’re using a <code class="language-plaintext highlighter-rouge">supervisor</code>-like application to manage the worker, which is recommended, then please refer to its documentation regarding interrupting the applications gracefully.</p> <h3 id="3-enter-maintenance-mode"> 3. Enter Maintenance Mode <a href="#3-enter-maintenance-mode" class="book_heading_anchor" title="Link to 3. Enter Maintenance Mode section">#</a> </h3> <p>Before beginning the migration, you should put the site into maintenance mode to ensure that visitors do not see error messages and there are no changes to the database or files while backups are being made. Maintenance mode should prevent all requests from being sent to the application.</p> <blockquote class="notice"> <p>OJS does not support a maintenance mode yet, but we <a href="https://github.com/pkp/pkp-lib/issues/3263">plan to support it</a>.</p> </blockquote> <p>Modify your Apache <code class="language-plaintext highlighter-rouge">VirtualHost</code> directive or place an <code class="language-plaintext highlighter-rouge">.htaccess</code> file in the <code class="language-plaintext highlighter-rouge">OJS_WEB_PATH</code> with the following content.</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>order deny,allow deny from all ErrorDocument 403 <span class="s2">"This site is undergoing maintenance and should return shortly. Thank you for your patience."</span> </code></pre></div></div> <p>Reload the apache server to apply the changes:</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="o">(</span>Debian<span class="o">)</span><span class="nv">$ </span>service apache2 reload <span class="o">(</span>RHEL<span class="o">)</span><span class="nv">$ </span>systemctl restart httpd </code></pre></div></div> <h3 id="4-create-backups"> 4. Create Backups <a href="#4-create-backups" class="book_heading_anchor" title="Link to 4. Create Backups section">#</a> </h3> <blockquote class="warning"> <p><strong>Do not skip this step.</strong> An upgrade can fail for many reasons. Without a backup you may permanently lose data.</p> </blockquote> <p>The steps below will backup the following folders and files.</p> <table> <thead> <tr> <th>Common Path</th> <th>Description</th> <th>VARIABLE</th> </tr> </thead> <tbody> <tr> <td><code class="language-plaintext highlighter-rouge">/var/www/html/public</code></td> <td>Public files</td> <td><code class="language-plaintext highlighter-rouge">OJS_PUBLIC_PATH</code></td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">/var/www/files</code></td> <td>Private files</td> <td><code class="language-plaintext highlighter-rouge">OJS_PRIVATE_PATH</code></td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">/var/www/html/config.inc.php</code></td> <td><code class="language-plaintext highlighter-rouge">config.inc.php</code></td> <td> </td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">/var/www/html/.htaccess</code></td> <td><code class="language-plaintext highlighter-rouge">.htaccess</code> or vhost (if any)</td> <td> </td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">/var/www/html/plugins</code></td> <td>plugins</td> <td> </td> </tr> <tr> <td>locale files, custom code, etc.</td> <td>local customizations</td> <td> </td> </tr> </tbody> </table> <p>Backup the database.</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$ </span>mysqldump <span class="nt">--host</span><span class="o">=</span><span class="s2">"</span><span class="nv">$OJS_DB_HOST</span><span class="s2">"</span> <span class="nt">-u</span> <span class="nv">$OJS_DB_USER</span> <span class="nt">-p</span><span class="nv">$OJS_DB_PASSWORD</span> <span class="nv">$OJS_DB_NAME</span> <span class="nt">--result-file</span><span class="o">=</span><span class="s2">"</span><span class="nv">$OJS_BACKUP_PATH</span><span class="s2">/backupDB-</span><span class="nv">$DATE</span><span class="s2">.sql"</span> </code></pre></div></div> <blockquote class="tip"> <p>Character encodings are a common source of database problems during upgrades. <br /> Read more in the <a href="/admin-guide/en/troubleshooting#character-encoding">Admin Guide</a>.</p> </blockquote> <p>Backup the private file directory.</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$ </span><span class="nb">tar </span>cvzf <span class="s2">"</span><span class="nv">$OJS_BACKUP_PATH</span><span class="s2">/private-</span><span class="nv">$DATE</span><span class="s2">.tgz"</span> <span class="s2">"</span><span class="nv">$OJS_PRIVATE_PATH</span><span class="s2">"</span> </code></pre></div></div> <p>Backup the public files directory.</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$ </span><span class="nb">tar </span>cvzf <span class="s2">"</span><span class="nv">$OJS_BACKUP_PATH</span><span class="s2">/ojsfiles-</span><span class="nv">$DATE</span><span class="s2">.tgz"</span> <span class="s2">"</span><span class="nv">$OJS_WEB_PATH</span><span class="s2">"</span> </code></pre></div></div> <p>Backup any other customizations you have made to the software, such as custom plugins or locale files.</p> <h3 id="5-create-sandbox"> 5. Create Sandbox <a href="#5-create-sandbox" class="book_heading_anchor" title="Link to 5. Create Sandbox section">#</a> </h3> <p>Use your backup to create a sandbox environment and test the upgrade in that sandbox first. The steps below can be used in your sandbox environment to perform an upgrade.</p> <p>Once the test is complete, you can run any automated or manual tests you have configured to ensure the upgrade did not introduce regressions.</p> <p><strong>Only perform the next steps on your live, production environment if you have already completed a test upgrade in your sandbox environment.</strong></p> <h3 id="6-download-release-package"> 6. Download Release Package <a href="#6-download-release-package" class="book_heading_anchor" title="Link to 6. Download Release Package section">#</a> </h3> <p>Download the correct release package.</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$ </span><span class="nb">cd</span> <span class="s2">"</span><span class="nv">$OJS_ROOT_PATH</span><span class="s2">"</span> <span class="nv">$ </span>wget <span class="s2">"https://pkp.sfu.ca/ojs/download/</span><span class="nv">$OJS_VERSION</span><span class="s2">.tar.gz"</span> </code></pre></div></div> <h3 id="7-check-system-requirements"> 7. Check System Requirements <a href="#7-check-system-requirements" class="book_heading_anchor" title="Link to 7. Check System Requirements section">#</a> </h3> <p>Check the <a href="https://pkp.sfu.ca/ojs/README">README</a> file from the downloaded <code class="language-plaintext highlighter-rouge">tar.gz</code> and be sure your system meets the following requirements.</p> <ul> <li>Apache version</li> <li>MySQL or PostgreSQL version</li> <li>PHP version</li> <li>Server libraries and module requirements</li> </ul> <p>In addition, you will want to perform the following checks.</p> <ul> <li>Adjust your PHP timeouts and memory limits to ensure the upgrade process can complete successfully.</li> <li>Check the server libraries and module requirements for any plugins you’ve added (these can often be found in the plugin’s README file).</li> </ul> <h3 id="8-install-release-package"> 8. Install Release Package <a href="#8-install-release-package" class="book_heading_anchor" title="Link to 8. Install Release Package section">#</a> </h3> <p>Backup the application files.</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$ </span><span class="nb">mv</span> <span class="s2">"</span><span class="nv">$OJS_WEB_PATH</span><span class="s2">"</span> <span class="s2">"</span><span class="nv">$OJS_BACKUP_PATH</span><span class="s2">"</span> </code></pre></div></div> <p>Extract the release package.</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$ </span><span class="nb">mkdir</span> <span class="s2">"</span><span class="nv">$OJS_WEB_PATH</span><span class="s2">"</span> <span class="nv">$ </span><span class="nb">tar</span> <span class="nt">--strip-components</span><span class="o">=</span>1 <span class="nt">-xvzf</span> <span class="s2">"</span><span class="nv">$OJS_VERSION</span><span class="s2">.tar.gz"</span> <span class="nt">-C</span> <span class="s2">"</span><span class="nv">$OJS_WEB_PATH</span><span class="s2">"</span> </code></pre></div></div> <p>Restore the <code class="language-plaintext highlighter-rouge">config.inc.php</code> file.</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$ </span><span class="nb">cp</span> <span class="s2">"</span><span class="nv">$OJS_BACKUP_PATH</span><span class="s2">/html/config.inc.php"</span> <span class="s2">"</span><span class="nv">$OJS_WEB_PATH</span><span class="s2">"</span> </code></pre></div></div> <p>Run the following command to compare your configuration file with the template of the new release. Add or remove any configuration options as necessary.</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$ </span>diff <span class="s2">"</span><span class="nv">$OJS_WEB_PATH</span><span class="s2">/config.inc.php"</span> <span class="s2">"</span><span class="nv">$OJS_WEB_PATH</span><span class="s2">/config.TEMPLATE.inc.php"</span> </code></pre></div></div> <p>Restore the <code class="language-plaintext highlighter-rouge">.htaccess</code> file if it exists.</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$ </span><span class="nb">cp</span> <span class="s2">"</span><span class="nv">$OJS_BACKUP_PATH</span><span class="s2">/.htaccess"</span> <span class="s2">"</span><span class="nv">$OJS_WEB_PATH</span><span class="s2">"</span> </code></pre></div></div> <p>Restore the public files.</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$ </span><span class="nb">cp</span> <span class="nt">-r</span> <span class="s2">"</span><span class="nv">$OJS_BACKUP_PATH</span><span class="s2">/html/public/*"</span> <span class="s2">"</span><span class="nv">$OJS_PUBLIC_PATH</span><span class="s2">"</span> </code></pre></div></div> <p>Set the permissions of new files as required by your server configuration.</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="o">(</span>Debian<span class="o">)</span><span class="nv">$ </span><span class="nb">sudo chown</span> <span class="nt">-R</span> <span class="nv">$WEB_USER</span>:<span class="nv">$WEB_GROUP</span> <span class="s2">"</span><span class="nv">$OJS_PUBLIC_PATH</span><span class="s2">"</span> <span class="s2">"</span><span class="nv">$OJS_WEB_PATH</span><span class="s2">/cache/"</span> <span class="o">(</span>RHEL<span class="o">)</span><span class="nv">$ </span><span class="nb">sudo chown</span> <span class="nt">-R</span> apache:apache <span class="s2">"</span><span class="nv">$OJS_PUBLIC_PATH</span><span class="s2">"</span> <span class="s2">"</span><span class="nv">$OJS_WEB_PATH</span><span class="s2">/cache/"</span> </code></pre></div></div> <p>Set the permissions for the plugin directories as required.</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="o">(</span>Debian<span class="o">)</span><span class="nv">$ </span><span class="nb">sudo chown</span> <span class="nt">-R</span> <span class="nv">$WEB_USER</span>:<span class="nv">$WEB_GROUP</span> <span class="s2">"</span><span class="nv">$OJS_WEB_PATH</span><span class="s2">/plugins/"</span> <span class="o">(</span>RHEL<span class="o">)</span><span class="nv">$ </span><span class="nb">sudo chown</span> <span class="nt">-R</span> apache:apache <span class="s2">"</span><span class="nv">$OJS_WEB_PATH</span><span class="s2">/plugins/"</span> </code></pre></div></div> <p>If the server is running under <a href="https://en.wikipedia.org/wiki/Security-Enhanced_Linux">SElinux</a>, reset the file contexts.</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="o">(</span>RHEL<span class="o">)</span><span class="nv">$ </span><span class="nb">sudo </span>restorecon <span class="nt">-R</span> <span class="s2">"</span><span class="nv">$OJS_WEB_PATH</span><span class="s2">/"</span> </code></pre></div></div> <h3 id="9-run-the-upgrade"> 9. Run the Upgrade <a href="#9-run-the-upgrade" class="book_heading_anchor" title="Link to 9. Run the Upgrade section">#</a> </h3> <p>Confirm the version numbers match your expectations.</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$ </span>php tools/upgrade.php check </code></pre></div></div> <p>In the screenshot below, we can see that we are currently running <code class="language-plaintext highlighter-rouge">3.2.1-4</code> and will be upgrading to <code class="language-plaintext highlighter-rouge">3.3.0-6</code>.</p> <p><img src="/dev/upgrade-guide/en/assets/upgrade-check.png" alt="An example of running the PHP upgrade check in the command-line." /></p> <p>Finally, when you are ready, run the upgrade script, which may take several hours to complete. We recommend you specify an explicit amount of memory on the command line, as server defaults may be too low. If the upgrade process runs out of memory it will fail and you will need to restore from backup and begin again. You may also wish to <a href="#log-the-output">log the output</a>.</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$ </span>php <span class="nt">-d</span> <span class="nv">memory_limit</span><span class="o">=</span>2048M tools/upgrade.php upgrade </code></pre></div></div> <p>If the upgrade is successful, you will see the message below informing you that the upgrade was successful.</p> <p><img src="/dev/upgrade-guide/en/assets/successful-upgrade.png" alt="An example of the "Successfully upgraded" message in the command-line." /></p> <h4 id="log-the-output"> Log the Output <a href="#log-the-output" class="book_heading_anchor" title="Link to Log the Output section">#</a> </h4> <p>The upgrade script will print a lot of information to the terminal. We recommend sending the output to a log file. This will help you troubleshoot if the upgrade fails.</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$ </span><span class="nb">nohup </span>php tools/upgrade.php upgrade <span class="o">></span> <span class="nv">$OJS_ROOT_PATH</span>/upgrade.log & </code></pre></div></div> <p>Check the progress of the upgrade.</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$ </span><span class="nb">tail</span> <span class="nt">-f</span> <span class="nv">$OJS_ROOT_PATH</span>/upgrade.log </code></pre></div></div> <h3 id="10-remove-maintenance-mode"> 10. Remove Maintenance Mode <a href="#10-remove-maintenance-mode" class="book_heading_anchor" title="Link to 10. Remove Maintenance Mode section">#</a> </h3> <p>When the upgrade is complete, remove the maintenance mode previously configured by modifying your Apache <code class="language-plaintext highlighter-rouge">VirtualHost</code> directive or updating your <code class="language-plaintext highlighter-rouge">.htaccess</code> file.</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$ </span><span class="nb">cd</span> <span class="s2">"</span><span class="nv">$OJS_WEB_PATH</span><span class="s2">/"</span> <span class="nv">$ </span><span class="nb">mv</span> .htaccess .htaccess.disabled </code></pre></div></div> <p>If your PHP timeouts and/or memory limit were adjusted, restore their original values.</p> <p>Reload the apache server to apply the changes.</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="o">(</span>Debian<span class="o">)</span><span class="nv">$ </span>service apache2 reload <span class="o">(</span>RHEL<span class="o">)</span><span class="nv">$ </span>systemctl restart httpd </code></pre></div></div> <h3 id="11-test-the-upgrade"> 11. Test the Upgrade <a href="#11-test-the-upgrade" class="book_heading_anchor" title="Link to 11. Test the Upgrade section">#</a> </h3> <p>It’s important to test the site after an upgrade. Any core functions for your journals should be tested, as well as custom plugins or themes once they have been reinstalled.</p> <p>The following is a short checklist that covers common use cases.</p> <ol> <li>Reader interface <ul> <li>The homepage loads</li> <li>The theme loads correctly</li> <li>Published articles can be downloaded</li> <li>Letters and text characters are displaying correctly</li> <li>No timeouts or long delays</li> <li>No broken links</li> <li>Articles appear correctly in the search</li> </ul> </li> <li>Database <ul> <li>Charset and collation on database, tables and fields</li> <li>Database engine is innoDB for database and all tables (MariaDB/MySQL only)</li> </ul> </li> <li>Register a new user account and login <ul> <li>Register an author</li> <li>Get a registration email</li> <li>Login with the new user</li> </ul> </li> <li>Complete the editorial workflow <ul> <li>As a Journal Manager: <ul> <li>Create a new testing journal</li> <li>Register your new user as an author in the testing journal</li> </ul> </li> <li>As an Author: <ul> <li>Login as author and submit an article to a test journal</li> <li>Confirm you are able to upload a document</li> </ul> </li> <li>As an Editor: <ul> <li>Assign the article to a section</li> <li>Accept article without revision</li> <li>Create a new issue and assign the article to it</li> <li>Publish the issue</li> <li>Download the published article</li> <li>Unpublish the article and remove the issue</li> </ul> </li> </ul> </li> <li>User management <ul> <li>As a Journal manager: <ul> <li>Assign new roles to the new user</li> <li>Change new user’s profile data and password</li> <li>Remove the new user by merging it to your admin account</li> </ul> </li> </ul> </li> <li>Additional testing of common tasks</li> </ol> <h3 id="12-restore-custom-plugins"> 12. Restore Custom Plugins <a href="#12-restore-custom-plugins" class="book_heading_anchor" title="Link to 12. Restore Custom Plugins section">#</a> </h3> <p>Use the Plugin Gallery to restore any custom plugins that were installed.</p> <p>If you have installed custom plugins which are not in the Plugin Gallery, check with the plugin distributor for an update which is compatible with your upgraded version.</p> <h3 id="13-reenable-the-execution-of-background-tasks"> 13. Reenable the execution of background tasks <a href="#13-reenable-the-execution-of-background-tasks" class="book_heading_anchor" title="Link to 13. Reenable the execution of background tasks section">#</a> </h3> <p>Basically undo the steps of the item 2, by reenabling the scheduled tasks and the job worker (if you were making use of it).</p> <h3 id="14-cleanup-backup-files"> 14. Cleanup Backup Files <a href="#14-cleanup-backup-files" class="book_heading_anchor" title="Link to 14. Cleanup Backup Files section">#</a> </h3> <p>You may wish to retain your backup files, but if you don’t, you can remove them.</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$ </span><span class="nb">sudo rm</span> <span class="nt">-fR</span> <span class="s2">"</span><span class="nv">$OJS_BACKUP_PATH</span><span class="s2">/*"</span> </code></pre></div></div> <h3 id="15-celebrate"> 15. Celebrate <a href="#15-celebrate" class="book_heading_anchor" title="Link to 15. Celebrate section">#</a> </h3> <p><strong>Your OJS instance has been successfully upgraded. Congratulations!</strong></p> <h2 id="troubleshooting"> Troubleshooting <a href="#troubleshooting" class="book_heading_anchor" title="Link to Troubleshooting section">#</a> </h2> <p>Consult the following resources if you encounter any problems.</p> <ul> <li><a href="https://forum.pkp.sfu.ca/">PKP Forum</a> - Questions and answers in the support forum</li> <li><a href="/faq/en/">FAQ</a> - The <a href="/faq/en/errors-troubleshooting">Errors and Troubleshooting</a> section may be helpful</li> <li><a href="/admin-guide/">Admin Guide - Troubleshooting</a> - See the <a href="/admin-guide/en/troubleshooting">Troubleshooting</a> section</li> <li><a href="https://github.com/pkp/pkp-lib/issues">GitHub Issues</a> - Review known issues reported against versions of the software</li> </ul> <hr> <p>Copyright: Simon Fraser University holds the copyright for work produced by the Public Knowledge Project and has placed its documentation under a <a href="https://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.</p> <p><a href="https://creativecommons.org/licenses/by/4.0/"><img src="https://licensebuttons.net/l/by/4.0/88x31.png" alt="Creative Commons Attribution 4.0 International" title="Creative Commons Attribution 4.0 International" /></a></p> <div class="book__footer"> <div class="book__improve"> <a href="https://github.com/pkp/pkp-docs/edit/main/dev/upgrade-guide/en/index.md"> Edit this page </a> or <a href="https://pkp.sfu.ca/documentation-feedback/"> make a suggestion </a> </div> </div> </div> </div> <div class="book__sidebarScreen"></div> <div id="sidebar" class="book__sidebar"> <div class="book__summary"> <div class="book_page_toc"> <h2>Table of Contents</h2> <ul> <li><a href="#contributors">Contributors</a></li> <li><a href="#required-knowledge-and-tools">Required Knowledge and Tools</a> <ul> <li><a href="#preparing-to-upgrade">Preparing to Upgrade</a></li> <li><a href="#a-note-on-versions">A Note on Versions</a></li> <li><a href="#upgrading-from-2x">Upgrading from 2.x</a></li> </ul> </li> <li><a href="#upgrade-tutorial">Upgrade Tutorial</a> <ul> <li><a href="#1-set-environment-variables">1. Set Environment Variables</a></li> <li><a href="#2-disable-the-execution-of-background-tasks">2. Disable the execution of background tasks</a></li> <li><a href="#3-enter-maintenance-mode">3. Enter Maintenance Mode</a></li> <li><a href="#4-create-backups">4. Create Backups</a></li> <li><a href="#5-create-sandbox">5. Create Sandbox</a></li> <li><a href="#6-download-release-package">6. Download Release Package</a></li> <li><a href="#7-check-system-requirements">7. Check System Requirements</a></li> <li><a href="#8-install-release-package">8. Install Release Package</a></li> <li><a href="#9-run-the-upgrade">9. Run the Upgrade</a></li> <li><a href="#10-remove-maintenance-mode">10. Remove Maintenance Mode</a></li> <li><a href="#11-test-the-upgrade">11. Test the Upgrade</a></li> <li><a href="#12-restore-custom-plugins">12. Restore Custom Plugins</a></li> <li><a href="#13-reenable-the-execution-of-background-tasks">13. Reenable the execution of background tasks</a></li> <li><a href="#14-cleanup-backup-files">14. Cleanup Backup Files</a></li> <li><a href="#15-celebrate">15. Celebrate</a></li> </ul> </li> <li><a href="#troubleshooting">Troubleshooting</a></li> </ul> </div> </div> <div class="book__backToHub"> <span class="fa fa-long-arrow-alt-left" aria-hidden="true"></span> <p>Back to <a href="/">all documentation</a>.</p> </div> <div class="book__spacer"></div> </div> </div> <div class="book__footerWrapper"> <div class="siteFooter"> <nav class="siteFooter__container"> <div class="siteFooter__top"> <div class="siteFooter__nav"> <div class="siteFooter__navHeader"> Contact Us </div> <p>Have a question or suggestion about PKP’s documentation and user guides? <a href="https://pkp.sfu.ca/documentation-feedback/">Use our documentation contact form</a>.</p> <p>If your message is not about documentation, please use the general <a href="https://pkp.sfu.ca/contact-us/">contact form</a>.</p> </div> <div class="siteFooter__nav"> <div class="siteFooter__navHeader"> Community </div> <p><a href="https://pkp.sfu.ca/documentation-interest-group/">Documentation Interest Group</a></p> <p><a href="/contributing/en/">Contributing Documentation</a></p> <p><a href="/translating-guide/">Translating Guide</a></p> <p><a href="https://forum.pkp.sfu.ca">Community Forum</a></p> </div> <div class="siteFooter__nav"> <div class="siteFooter__navHeader"> About </div> <p><a href="https://pkp.sfu.ca">Public Knowledge Project</a></p> <p><a href="https://pkpservices.sfu.ca/">PKP|Publishing Services</a></p> </div> <div class="siteFooter__logo"> <a href="https://pkp.sfu.ca"> <img src="/img/logo-on-grey.png" alt="Public Knowledge Project"> </a> <p>The Public Knowledge Project is a Core Facility of Simon Fraser University</p> <p>888 University Drive, Burnaby, B.C., Canada V5A 1S6</p> <p>We respectfully acknowledge that SFU occupies the unceded traditional territories of the Coast Salish peoples of the Musqueam, Squamish, and Tsleil-Waututh Nations.</p> </div> </div> <div class="siteFooter__bottom"> <p class="footer-copyright"><span class="terms-text"><a href="https://www.sfu.ca/contact/terms-conditions.html" target="_blank">TERMS & CONDITIONS</a> © SIMON FRASER UNIVERSITY.</span><span class="copyright-text"><img src="/img/creativecommons.svg" alt="Creative Commons logo" /><img src="/img/attribution.svg" alt="Attribution icon" /><a href="https://creativecommons.org/licenses/by/2.0/" target="_blank">CC-BY 2.0</a></span><span class="footer-copyright-separator"> | </span><span class="ab-link">Website by <a target="_blank" href="https://www.affinitybridge.com">Affinity Bridge</a></span></p> </div> </div> </div> </div> <script type="text/javascript">/** * Toggle the sidebar open/closed */ (function() { var sidebar = document.getElementById('sidebar'); var sidebarControl = document.getElementById('sidebarControl'); var isOpen = false; var sidebarOpenClass = ' -sidebarIsOpen'; if (!sidebar || !sidebarControl) { return; } // Toggle sidebar function toggle() { if (isOpen) { document.body.className = document.body.className.replace(new RegExp(sidebarOpenClass, 'g'), ''); } else { document.body.className = document.body.className + sidebarOpenClass; } isOpen = !isOpen; } sidebarControl.addEventListener('click', toggle); })(); </script> <script type="text/javascript">/** * Initialize smooth scrolling to anchor links * * See: https://github.com/cferdinandi/smooth-scroll */ (function() { function init() { if (typeof SmoothScroll === 'undefined') { setTimeout(init, 500); } else { var scroll = new SmoothScroll('a[href*="#"]', {easing: 'easeInOutCubic', offset:80}); } } init(); })(); </script> <!-- Global site tag (gtag.js) - Google Analytics --> <script async src="https://www.googletagmanager.com/gtag/js?id=UA-130558797-1"></script> <script> window.dataLayer = window.dataLayer || []; function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'UA-130558797-1'); </script> <!-- Hotjar Tracking Code for docs.pkp.sfu.ca --> <script> (function(h,o,t,j,a,r){ h.hj=h.hj||function(){(h.hj.q=h.hj.q||[]).push(arguments)}; h._hjSettings={hjid:2436159,hjsv:6}; a=o.getElementsByTagName('head')[0]; r=o.createElement('script');r.async=1; r.src=t+h._hjSettings.hjid+j+h._hjSettings.hjsv; a.appendChild(r); })(window,document,'https://static.hotjar.com/c/hotjar-','.js?sv='); </script> <!-- Piwik/Matomo --> <script type="text/javascript"> var _paq = _paq || []; _paq.push(["setDocumentTitle", document.domain + "/" + document.title]); _paq.push(["setCookieDomain", "*.docs.pkp.sfu.ca"]); _paq.push(["setDomains", ["*.docs.pkp.sfu.ca"]]); _paq.push(["trackPageView"]); _paq.push(["enableLinkTracking"]); (function() { var u = (("https:" == document.location.protocol) ? "https" : "http") + "://" + "matomo.publicknowledgeproject.org/pkp/"; _paq.push(["setTrackerUrl", u + "piwik.php"]); _paq.push(["setSiteId", "40"]); var d = document, g = d.createElement("script"), s = d.getElementsByTagName("script")[0]; g.type = "text/javascript"; g.defer = true; g.async = true; g.src = u + "piwik.js"; s.parentNode.insertBefore(g, s); })(); </script> <!-- End Piwik Code --> </body> </html>