Upgrading Bolt CMS to v3.x.

09 January 2017

Since PivotX went out of support I've been running the Bolt CMS for my website at Dreamhost (referral link).  A couple of weeks back you may have noticed some trouble my site was having, due to my running into significant difficulty encountered when upgrading from the v2.x release series to the v3.x release series.  Some stuff went sideways, and I had to restore from backup at least once before I managed to get the upgrade procedure straightened out with the help of some of the developers in the Bolt IRC channel on Freenode.  If it wasn't for help from rossriley it would have taken significantly longer to un-fuck my website.

Here's the procedure that I used to get my site upgraded to the latest release of Bolt.

First, make sure your Bolt install was upgraded to the latest v2.x release - v2.2.24.

Second, BACK EVERYTHING UP.  REALLY.  If something goes sideways you'll need that backup to restore your site to normal functioning so you can try again later.  This saved my ass.

Third, because I'm using shared hosting on Dreamhost I have to use the latest flat structure release of the software because I can't reconfigure Apache on the Dreamhost server my site's hosted to point to a different base directory.

What screwed everything up is the extensions I have plugged into my website, because Bolt implements things like RSS and sitemaps with plug-ins and not natively, so you can get only what you need when you need it.  The extensions I use on my website are Monthly and Yearly Archives, SEO, RSS Feed, and Sitemap.  When you upgrade your site to the v3.x series, uninstall all of your extensions.  All of them.  Otherwise the upgrade process will blow up in your face with an exception that looks something like this:

Fatal error: Uncaught exception 'Bolt\Filesystem\Exception\IncludeFileException' with message 'Undefined variable: app' in /home/username/drwho.virtadpt.net/vendor/bolt/filesystem/src/Adapter/Local.php:117

Just about every extension you're likely to need has been upgraded for the v3.x series, so don't worry about putting them back.  Now back up the following configuration files:

  • app/config/config.yml
  • app/config/contenttypes.yml
  • app/config/menu.yml
  • app/config/taxonomy.yml
  • app/config/extensions/
  • app/database/

I changed to the base of my website's directory structure and used the following command to do this, which made putting them back later much easier: tar cvfj ~/website_config_files.tar.bz2 app/config/config.yml  app/config/contenttypes.yml app/config/menu.yml app/config/taxonomy.yml app/config/extensions/ app/database/

Again, I downloaded the latest flat structure release of Bolt to my home directory at Dreamhost: https://bolt.cm/distribution/bolt-latest-flat-structure.tar.gz

Change to the webroot of your website and decompress that file:

  • cd ~/drwho.virtadpt.net
  • tar xvfz ~/bolt-latest-flat-structure.tar.gz --strip-components=1

Run the setup utility (remember when PHP didn't have those?): php app/nut setup:sync

Now put the backed up configuration files back the way they were before the upgrade: tar xvfj ~/website_config_files.tar.bz2

Clear the rendered HTML cache: php app/nut cache:clear

Update the database schema to the v3.x series: php app/nut database:update

That should about do it.  If you go to your website, you should see the frontpage per usual.  Try logging into your site.  If you were logged in before (i.e., if you forgot to log out before upgrading the software, like I did) you'll run into some difficulty because the session token needs to expire but if you keep plugging away (and possibly clearing your browser cookies once or twice) eventually you'll log in without any problems.  Re-install all of the extensions you need for your site, one at a time (no sense in tempting fate, after all).

The good news is that you shouldn't have to go through all this rigamarole later when installing point releases of Bolt (for example, when upgrading from v3.2.4 to v3.2.5).