Backdrop CMS: content, config, site launch and back-up

With Backdrop CMS being a fork of Drupal, you could be forgiven for thinking that everything in Backdrop will be similar to everything in Drupal 7. It mostly is - and that makes it a delight to work in if you are familiar with Drupal 7. Views is there after all - and in core, so what could go wrong? Not much really, but it's worth looking at the differences before elation carries us away. This post concerns Backdrop's storage and configuration model and how we work with that when moving a local Backdrop site to a live server. This requires special treatment compared to Drupal 7, in some part because Backdrop is actually an early fork of Drupal 8 (not 7) and adopted some elements of the storage model that was being built into that newer version at the time.

Backdrop's storage system: the database and JSON config files

Managing Backdrop's storage configuration is therefore key to managing Backdrop and involves learning a few new habits, but none of it is rocket science. It requires you to use the Backup and Migrate module (which you probably used when you worked with Drupal 7), but a bit more too (although you will appreciate the low-tech approach taken here that does not use Git for version control). You will also know that Backdrop (as with Drupal 8) uses JSON configuration files in the files/config folder. (Multiple JSON file read-writes can have performance advantages over large SQL dB read-writes.) Here's an overview of the differences before we go for the full how-to:

Drupal 7 and Backdrop configuration outline
Drupal 7 Backdrop
SQL dB Everything Content and user account data
(and some configuration settings)
JSON files in the /files/config folder None Configuration settings

The above is an outline only because some Backdrop configuration settings are still held in the dB. Which of these are held in the dB and which are held in JSON files can be a little arbitrary so the key point is that some of what you are used to seeing only in a Drupal 7 dB could most definitely now be in the JSON files - and perhaps only there. Some of this arbitrariness is signalled by the different action text in various buttons:

A configure drop-down from the Backdrop CMS interfaceAn edit drop-down option from Backdrop CMS interfaceA Save button from the Backdrop CMS interfaceAn Update Style button from the Backdrop CMS interfaceA Save Configuration button from the Backdrop CMS interface
Various Backdrop button and drop-downs with captions that hint at different storage outcomes.

Some of these are explicit about saving a configuration (or a style). Others are non-specific. You don't really need to decode the meaning of this medley of buttons and drop-downs, nor understand what gets saved where; you just need to back it all up without missing something.This hybrid architecture requires you to adopt a two-handed back-up policy for Backdrop websites.

Backing up both components of a Backdrop website

The take-away here is that a single Backup and Migrate zip file will not be enough to rescue your Backdrop site; you will need the JSON files as well.

The Backup and Migrate module (which you probably used when you worked with Drupal 7) enables you to grab the contents of your Backdrop site's database. But given the above, that won't be enough. You will also need to backup the site's JSON files. The take-away here is that a single Backup and Migrate zip file will not be enough to rescue your Backdrop site; you will need the JSON files as well. Here's your checklist:

  • Either copy all the site's JSON configuration files from the /files/config_nonsense-folder-name folder
  • or export a single gz tar file of them using the site's inbuilt Configuration Export system at Admin > Configuration > Configuration management > Full Import/Export > Export. As it says on that page "This form may be used to generate a full export of your entire site's configuration. This configuration file should remain compressed when you upload it to the destination site."
  • Use the Backup and Migrate module, to grab a zip file of the site's database.

Launching a live Backdrop website using data migrated from a local version

Back when you worked with Drupal 7, launching a website was relatively easy. You could install Drupal, enable the Backup and Migrate module and then use that module to restore the site using the backup zip file that you had created on your development machine. (Assuming that you had copied all your local files to the server, then virtually everything would be done - and the new site could go live.)

In Backdrop, you need to do more. Here's what I reckon the essential steps need to be. This is based on your having a working Backdrop site on your local machine and you are ready to install it on your live server.

  1. Back up your local site using the Backup and Migrate module.
  2. Export your local Backdrop's configuration to a single gz file using Backdrop's built-in Configuration Export system at Admin > Configuration > Configuration management > Full Import/Export > Export. Do NOT work directly with the files in your local site's /files/config_nonsense-folder-name folder. You need to export the configuration.
  3. Make sure PHP on the live server can handle uploads of the size of the files in steps 1 and 2 above. You do this either by working with whatever PHP setting options your hosting company's control panel gives you or by directly editing the upload_max_filesize = setting on the live server's PHP.INI if you have access to it.
  4. Upload to the live server the Backdrop system ready to be installed. Include in that upload any third-party modules, themes, layouts and libraries that the local site uses.
  5. Upload to the live server everything in the local site's /files folder except for the /files/config_nonsense-folder-name folder. Do NOT upload that folder or any of the JSON files in that folder's sub-folders. (You need the /files folder, but not the /files/config_nonsense-folder-name folder.)
  6. Install Backdrop on the live server.
  7. Once the installation has completed successfully, delete the file /core/install.php.
  8. Enable every module on the live site that is used by your local Backdrop site.
  9. Enable every theme on the live site that is used by your local Backdrop site.
  10. The installation may create two nodes (such as Your first post! and About). Delete them from within Backdrop's internal content listing.
  11. On the live server, go to Backdrop's built-in Configuration Export system at Admin > Configuration > Configuration management > Full Import/Export > Import (/admin/config/development/configuration/full) and import the gz file that you exported in step 2 above from your local site. (Error messages you get here will stop the import if you missed a module or a theme when enabling everything that you were using on the local site. You may well get error messages that run counter to what you expect, such as a non-core module not being installed. When this happens, try disabling the implicated module, regenerating a new export configuration file and using that for the live server. You can then re-enable the module on the live site later.) If you get no error messages then this import process will have re-created the required JSON files in the live site's /files/config_nonsense-folder-name folder.
  12. On the live server, use Backdrop's Backup and Migrate module to restore the zip file you created in step 1 above.

Remember that this process suits a workflow that does not use version control. If that applies to you, then this approach should work nicely. (Tested on Backdrop version 1.14.2.)