Upgrading Concrete CMS

Edit

Improvements?

Let us know by posting here.

Prior to Upgrading

You should always perform a database backup prior to upgrading a concrete site. If you have custom code in your site, you may wish to backup your files as well (cPanel tutorial).

Once your backup is complete, choose your upgrade method. There are a few ways to upgrade a Concrete CMS site.

Be aware, there is no 'downgrade' process for Concrete CMS.

If you upgrade your site and it breaks, the only way back to your previous working version of Concrete is to restore from a backup made prior to the upgrade process.

Remote Update: Upgrade Completely Through the Dashboard

If you head to Dashboard > System and Settings > Update Concrete, you can download updates from concretecms.org. These will be unzipped into your root updates/ directory, and you will be able to choose when to apply them to your site. Updates to Concrete may not be available as quickly through this interface as they are from the website.

Manual Dashboard Update

Since the method above simply delivers a Concrete directory to your updates directory, you can manually perform the first half of these steps, and use the Dashboard to complete the update process.

  1. Download the latest core from http://www.concretecms.org/download
  2. Unzip the file. Remove all contents except the concrete directory.
  3. At this point you should have a folder named something like concrete5.x.x.x, with only a "concrete" directory inside it.
  4. Move the concrete5.x.x.x folder into your updates/ directory.
  5. Head to Dashboard > System and Settings > Update concrete. The update should be listed, and you can click through to update to the latest version.

In both cases, an update.php file will be written to your application/config directory specifying the specific version you're updating to. The directory will continue to exist within the updates/ directory.

Replacing the original Concrete Directory (Version 8 and above)

If you want to minimize disk space usage and don't need to use the web interface for update Concrete, you can replace the original Concrete directory with a new version, and then upgrade through a particular route.

  1. Download the latest core from www.concretecms.org/download
  2. Unzip the file.
  3. Replace these items in the web root with the ones you downloaded:
    1. the concrete directory (IMPORTANT don't overwrite the existing directory: first you have to delete the old one)
    2. empty the updates directory
    3. delete (if it exists) the application/config/update.php file
    4. the composer.json file if upgrading from a version prior to 8.2.0
    5. the composer.lock file if upgrading from a version prior to 8.2.0
  4. Visit your site in a browser.

That's it! The first time a page of the website is visited, Concrete will automatically run any database migrations that need to be run to bring the site up to date. Since Concrete 8.4.0, the other users will see the site in Maintenance Mode during the upgrade process.

Upgrading via the command line (Version 8 and above)

The version 8 upgrade in particular is a large one. It makes a lot of transformations to the Concrete database, and sometimes these can take awhile. If you find that the Concrete upgrade times out in your browser, or has some kind of error, you can try upgrading via the command line:

  1. Download the latest core from www.concretecms.org/download
  2. Unzip the file.
  3. ssh into your web server and enter the web directory
  4. Enable the Maintenance Mode:
    ./concrete/bin/concrete5 c5:config -g set concrete.maintenance_mode true
  5. Replace the Concrete directory in the web root with the Concrete directory you downloaded.
  6. Perform the upgrade:
    ./concrete/bin/concrete5 c5:update
    The migrations that are applied should be printed out to the console, along with any upgrade notices about what the specific upgrade is doing.
  7. Disable the Maintenance Mode
    ./concrete/bin/concrete5 c5:config -g set concrete.maintenance_mode false

Please remark that, in order to allow the above procedure, when users visit the website while it's in Maintenance Mode, the upgrade process won't occur.

Replacing the original Concrete Directory (5.7.5.10 and earlier)

If you want to minimize disk space usage and don't need to use the web interface for update Concrete, you can replace the original Concrete directory with a new version, and then upgrade through a particular route.

1.1. Login as the super user or someone in the Administrators group. You must do this because upgrading a Concrete site requires that the user attempting to do so have access to the "Upgrade concrete" permission. By default this is people in the Administrators group (or the super user.)

  1. Download the latest core from http://www.concretecms.org/download
  2. Unzip the file.
  3. Replace the Concrete directory in the web root with the Concrete directory you downloaded.
  4. Visit the URL http://www.yoursite.com/ccm/system/upgrade. You should see a message about an upgrade being available. Click through to upgrade your database to the most recent version.

Emergency: Disable Upgrade Permissions Protection

If you have copied the Concrete directory over the old directory, and now wish to upgrade, but forgot to login prior to copying the directory (and you can't login due to the upgrade causing issues since it has not yet run) you can momentarily disable the permissions protection by modifying a configuration value on the web server.

Create a file named concrete.php in the application/config/ directory, or open it if it already exists. If the file is empty, copy this into it:

<?php
return array(
    'updates' => array(
        'enable_permissions_protection' => false
    )
);

If the file isn't empty, just add the enable permissions protection key to the existing array. Once the upgrade is complete, remove this file or the line (to re-enable upgrade permissions protection).