Upgrading a website from Drupal 7 to Backdrop CMS

Hi! Perhaps you got here because your Drupal 7 website is getting crusty and you are searching for alternatives. I'm going to show how to upgrade a website from Drupal 7 to Backdrop CMS. Why should you trust us? I'm Herb van den Dool, a senior developer and project manager at Freeform Solutions. I've already got a few Drupal 7 (and Drupal 6) upgrades to Backdrop CMS knotched up. Some of those have been complicated websites integrated with CiviCRM and custom modules. At Freeform Solutions we many years of collective experience keeping valuable non-profit websites secure and well-maintained. We take you and your website needs seriously. Feel free to get a hold of us if you want our help.  You may have heard about Backdrop CMS which is a fork of Drupal 7. Perhaps "fork" is too simplistic a term. Upgrading from Drupal 7 to Backdrop is actually often easier than upgrading to Drupal 8. Backdrop is a good choice for non-profits and small businesses who have essential websites but don't always need to be on the cutting edge that is Drupal 8. Backdrop CMS has made a number of improvements to make the hard things that most people use easier. Backdrop also includes the most popular and useful modules in core, which almost everyone uses, such as Views, Pathauto and Token. Backdrop CMS is guided by the philosophy of making it easy for the 80% of users rather than cater to the advanced developer (a conscious change from Drupal 7). If you're unfamiliar with Backdrop you can take it for spin with this demo. For this upgrade I reviewed the upgrade documentation again. I recommend you do so to make sure you've got everything ready for your upgrade. I also suggest making backups of your database, code and files so you can retry things if you get stuck.

Prepping Drupal 7

First we need to make sure that Drupal 7 is updated with all the latest codebase for core and all contributed modules. In this case, I created a simple Drupal 7 site in Lando so it already had all the latest code. I created some dummy data. I used a few of the most popular modules: Token, Pathauto, Entity, Email, Link, Views, Metatag, Date, Field Group, FIle Entity, CAPTCHA, Honeypot. Some of these modules have been added into Backdrop core (Views, CKEditor, Link, Email, Redirect), others are available as contributed modules. And still others are not needed (Ctools, Entity API). I'm using the stock theme with Drupal 7: Bartik. Here's our Drupal 7 site:

It is using the Front Page View, which I've slightly modified.  It has pages, articles and comments, some of which I've generated with Devel module, which can help you generate content quickly.

Create a local dev environment

Let's create a directory "d72bd_demo". Make sure Lando is installed. In that directory we run:

lando init

We use the "current working directory" because we'll be downloading all the code we need from the Backdrop CMS website. We use the backdrop "recipe" provided by Lando. This recipe is just for how Lando sets up the Lando container and settings to be optimized for Backdrop, it's not a complete recipe for a website. We edit the .lando.yml file using Serundeputy's example so that we can have drush working. Drush was forked to work with Backdrop but needs to be added to the Landofile in order to be included in our recipe. Our Landofile should now look like:

name: my-backdrop
recipe: backdrop
  webroot: .
  backdrush: 1.x-1.x

There are lots of other useful settings in the example Landofile but this is all we need for now.

Backdrop CMS core and modules

Let's fetch the latest Backdrop zip and unzip it into the directory.


Starting up our new site

Then we run:

lando start

A lot of magic happens in Lando. It spins up all the infrastructure and gives us some links to open up the site. Easy peasy!

But before visiting, we need to get contrib modules that match the old site. We check our Drupal 7 site's modules page to see what modules we'll need to find for Backdrop. In Backdrop CMS we've got already included in core: Token, Pathauto, Entity, Email, Link, Views, Date, File Entity, CKEditor, Redirect, Views. That's a lot! We'll also download Metatag, Field Group, CAPTCHA, Honeypot, and Paragraphs. We're were using Bartik in Drupal 7 which happens to be included in Backdrop as well, but I recommend that we use the more modern (and default) Basis theme. Bartik is still there for some backwards compatibility. We're now ready to fetch our Drupal 7 database and import it into the new Backdrop site. How you get your Drupal 7 database this depends on your particular hosting. A lot of webhosts provide PHPMyAdmin which can be used to export. Or if you make regular backups you can fetch your latest. In our example website we use the Lando command "lando db-export". After exporting the database from the Drupal 7 site we put it in my Lando site folder and import it using:

lando db-import db.sql.gz

Copy over files

We need the old files for the new site so they will be available for the upgrade. We copy over everything from sites/default/files on the old site into files on the new. Note the new directory structure. In Backdrop media files are by default in the root directory under /files. We only need to use the sites/ structure if we have a multi-site which we do not. If we had any file paths referenced in our text fields we may also need to make a symlink between sites/default/files and files. You can look up how to do it on the Backdrop guide linked at the top of this article.

Update the database

We try https://my-backdrop.lndo.site/core/update.php but we don't have access to update since we're not logged in. We won't be able to log in with all the updates waiting so we need to manually edit settings.php file temporarily allow us to update.

$settings['update_free_access'] = TRUE;

We try the update link again and it now allows us to update core and all the contrib modules we've added.

We revert our change to the settings file. Backdrop will keep warning us anyway if you forget this step.


Success! we're now able to login. We then clear cache by clicking on the Flush all caches under Home in the top menu. But the images are still not showing up so we go to Admin > Configuration > Media > File System to change the location of the files from sites/default/files to files. That's better.

The theme looks antique! It's still using the very old Bartik theme. But don't despair, we can quickly change the appearance to the new theme Basis.


So that looks better.


If our Views haven't appeared

If our Views aren't coming through it's probably because they exist in code but not in the Drupal 7 database. If it's a core View we can make a slight tweak to it before exporting the database in order for it to get transferred over. But if we forget then we can also use the Default Views Config module. It will convert the export format that we get when we export a View in Drupal 7 at a path like admin/structure/views/view/frontpage/export and then converts it to JSON format which can be imported into Backdrop config.

Filters still need to be configured

Go to Filters and configure them. The filteres aren't configured to have CKEditor enabled by default after an upgrade because there were multiple different ways that editors could be set up in Drupal 7 and it would be a lot of work to try to account for all of the different types.  



Instead of block management page like in Drupal 7, Backdrop has layouts, which is similar to Panels in Drupal 7. We get a default layout and an admin layout, but since we upgraded we'll have to create our own home page layout. We go to Admin > Structure > Layouts and add a layout, calling it Home. We use the Boxton, single column template. We set a path to "home". (In layouts we can either have a fixed path or use a wild card so it applies to all nodes, users, terms, etc). To make it a bit fancier we'll add a Hero block on the layout's Manage blocks page. A hero is a full-width block with a background image and some text as an overlay.

In order for our new layout to be used as the home page we go to Configuration > Site information > Default home page to change the path to this new layout, "home".

Show our content promoted to front page

So now we want our content which is promoted to the front page to show up like on the old site. So we'll update the Front page View so that it's also displayed in a block.

When adding the block it will inherit the settings from the page. This should serve us well so let's save. Then we go back to the home page layout and add the block to the Content section.

Not the prettiest but works for our purposes.

Our layout is showing a title above the hero block. We don't need it on the home page. So let's get rid of it. We go back to home layout, edit the Page title, and change it to No title. Save the layout.

That looks better!

It's still not perfect, but this serves the purposes of showing the basics of an upgrade. To go further we could play around with the colours in the theme's settings.

We would probably also create a child theme of Basis, add styles to our style sheet, and update templates where needed. In this case it would be nice to style the user picture and author info above the article text. The layout is not great. That's it for now! In future articles I may get around to also providing a video walkthrough. If you've tried to upgrade and find yourself stuck, feel free to contact us to see how we can help.