Getting stuck upgrading Bolt and what to do about it.

08 May 2017

bolt cms howto meta problems upgrade

UPDATE - 20170512 - More SQL surgery.

So, as you've no doubt noticed I've been running the Bolt CMS to power my website for a while now.  I've also mentioned once or twice that I've found it to be something of a finicky beast and doing anything major to it can be something of an adventure.  I tried to upgrade my site last week (tonight, by the datestamp on this post) and had to restore from backup yet again because something went sideways.  That something was the upgrade process going wrong and throwing an exception because of something in the cache directory, where Bolt temporarily stores HTML files rendered from templates used to make pages that your web browser displays.

As it turned out, the upgrade process was choking on the old cache directories created and used by v2.x of the Bolt CMS.  Here is the upgrade process that I used:

  • BACK UP YOUR SITE.
  • Log into your web hosting provider's server via SSH.
  • Download the latest version of the flat file structure build of Bolt.
  • If you didn't back up your website, BACK UP YOUR WEB SITE.
  • cd ~/my.website.here
  • If you didn't back up your website and things go pear-shaped, it's your fault.  Don't say I didn't warn you.
  • Uncompress the new version of Bolt you just downloaded: tar xvfz ~/bolt-latest-flat-structure.tar.gz --strip-components=1
  • Try running the upgrade: php app/nut setup:sync
  • If it throws an exception on you, erase the entire on-disk cache.  Don't worry, it'll be rebuilt as people visit your site: rm -rf app/cache/*
  • Try running the upgrade again: php app/nut setup:sync
  • It should complete successfully.  If it doesn't you may need to do the following two things before re-running the upgrade command again:
    • mkdir -p app/cache/production/data/
    • chmod -R 0775 app/cache/
    • If you still have problems, jump into the Bolt CMS Slack chat and politely ask good questions: https://boltcms.slack.com/
  • If the command finishes normally, try opening the frontpage of your website.  It should be up and running.
  • If you can see the frontpage of your website, try logging in.  You should be able to.
  • Try making a test post with a new entry.  Be sure to test saving the post partway through.  You do save your work every few minutes, don't you?
  • Success.

Special thanks to Bob and thisiseduardo in the Bolt CMS Slack chat for their assistance and hand-holding while I stumbled around trying to make this hapen.

I also had to do some database surgery, which may or may not be applicable if you didn't upgrade Bolt from the v2.x series.  We're not sure.  In the database table bolt_entries, the image and video columns needed to be reconfigured so that they default to NULL instead of None.  I accomplished this task with my hosting provider's private phpMyAdmin panel, clicking on the rows, and changing the appropriate drop-down but if you're feeling adventurous you can do the same thing with raw SQL commands if you log into the database from the command line.  Here are the commands that phpMyAdmin ran on my behalf:

ALTER TABLE `bolt_entries` CHANGE `image` `image` LONGTEXT CHARACTER SET utf8 COLLATE utf8_unicode_ci
    NULL DEFAULT NULL;

ALTER TABLE `bolt_entries` CHANGE `video` `video` LONGTEXT CHARACTER SET utf8 COLLATE utf8_unicode_ci
    NULL DEFAULT NULL;

ALTER TABLE `bolt_pages` CHANGE `image` `image` LONGTEXT CHARACTER SET utf8 COLLATE utf8_unicode_ci
    NULL DEFAULT NULL;

back to top