This guide is intended to help explain how to upgrade the concrete5 core to a new version without relying on our handy built-in dashboard interface.

Important: back up your database!

Before getting started, make sure you back up your database with a tool like phpMyAdmin or command-line mysql. Backing up your site through the concrete5 Dashboard often only works for very small sites (this process times out in many hosting environments). phpMyAdmin or command line sql offer more reliable methods of generating a database dump file.

Why would I want to upgrade manually?

Good question! If your site can't connect to concrete5.org to download a new version of the core, you'll need to upgrade manually. If your site is working properly, this won't be a terribly scary process if you're comfortable uploading files to your server, extracting and moving them.

If your site is broken and think upgrading might fix it, keep in mind that you may run into additional troubleshooting challenges unique to your site or database.

Download a new version of concrete5

Our Downloads Page offers several versions of the core.

What version should I download?

In general, it's best to keep your site up-to-date with the latest version. However, certain versions of concrete5 require you to upgrade to a specific version first before you can jump all the way to the latest core. For instance, concrete5.4.2.1 and earlier require you to upgrade to concrete5.4.2.2 before you can upgrade to version 5.5.x.

If your site is running an older version of the core, please refer to this how-to: Update Very Old Sites.

Method 1, Step 1: Put the new core in the Updates Directory

This approach essentially emulates how concrete5 would typically download and extract the new core (provided that your site was able connect to us). This is generally the easiest approach to manually upgrading a site. Another advantage is that it typically doesn't result in much downtime while you get everything set up, allowing the site to use the old core until the moment you hit the "Upgrade" button from the Dashboard.

Upload the new concrete5 zip archive to your server and extract it into your updates/ override folder. Assuming I'm setting up concrete5.5.2.1, the correct path would look like this:

(your_site_root)/updates/concrete5.5.2.1/

Now you're ready to apply the update, as described below.

Method 1, Step 2: Upgrade from Dashboard

Now that your core is in place in the updates/ directory, visit Dashboard > System & Settings > Backup & Restore > Update concrete5. If your new core is in the right spot, it will show up as available to be installed. Follow the directions on the screen. If all goes well, you'll have a working site running the new version of concrete5 that you downloaded. Remember to clear your site cache to make sure everything's working!

Note: The end result is that your site's old core still resides in concrete/, but we've added a new line to config/site.php that tells the site to essentially ignore it, and use the new core in the updates/ directory instead. Here's what that line might look like:

define('DIRNAME_APP_UPDATED', 'concrete5.5.2.1');

Note that the value of this constant matches the directory name of the new core that we placed in updates/.

Method 2, Step 1: Replace the core "in-place"

This approach remains useful for upgrading sites with special circumstances. For instance, if a site's Dashboard was broken or otherwise unreachable, we might give this method a shot (while of course being very careful to make sure we have a backup of the site's database in case things don't work out as planned).

In this approach, we essentially replace the "old" core concrete directory with one from the new version, then run the upgrade script manually. Keep in mind that while you've moved or renamed the concrete/ folder, your site won't find it... and won't be able to render pages and will likely display errors. Be aware there may be a little downtime involved with this approach. It helps to get your "new" core directory up on the site, staged and ready to move into place so that your site's not down for long.

First, upload the new version of concrete5 to your server as a zip archive. Extract it to some out-of-the-way folder. Copy the concrete/ directory into the root of your site with a new name-- for instance concrete-new/

Then move the old concrete/ directory out of the way. You can also re-name it to something obvious like concrete-old. Either way, don't just delete it-- if something goes wrong, you may want to put it back in place.

The last part of this method is to rename concrete-new/ to concrete/. Once you've done so, you're ready to apply the update, as described below.

Method 2, Step 2: Run the upgrade script manually

Since you've replaced the core, you've now got a site that may not work 100% correctly. It may barely work at all. This is because the core files and database are mis-matched-- you've updated the core files, but the database is still set up to run on the older version. Because of this, you may not be able to access the Dashboard upgrade page. Thankfully, there's a way around this challenge. concrete5 includes a dashboard tools script that allows you to run the script from a hidden Single Page.

Visit this page to run the script:

http://www.your-concrete5-site.com/index.php/tools/required/upgrade

If all goes well, you'll see a success message and your site will now be running on the new version of concrete5 that you downloaded.

A Note on the Upgrade Script

The upgrade script, run manually, checks the updates/ override directory as well as the current core. Keep in mind that you can actually use this approach to update a site to a new core placed updates/ directory as well-- it's not limited to what's currently located in your_site_root/concrete/.

Final Steps

No matter which method you've used to upgrade your site, it's always a good idea to clear your cache. This makes sure your site's pages are being fully rendered using the current core.

It's also a good idea to update your add-ons to make sure you're using the latest versions. This is especially important if you've made a big leap, like from one generational version to the next.

What if something goes wrong. How can I get help?

Make sure your concrete5 core version and the version specified in the database agree.

Our Installation Forum is a great place to start. If your site is broken and it's a mission-critial type of situation, you may want to look into hiring a consultant by posting a description of your problems and asking for bids on our Jobs Board.