Backdrop promises to offer an easier upgrade process than making the jump to Drupal 9+ but it’s not without its pitfalls.

Fortunately the upgrade process is not heinously difficult.

This guide serves as an overview and breaks down the migration process described in the official documentation.

1. Test for Theme Compatibility

The biggest change between Drupal 7 and Backdrop has to do with how content is displayed to the user. Any custom themes you may have may not be compatible with how Backdrop displays site data. This change allows for Backdrop to do fantastic things out of the box but it accomplishes it by adding a killer feature that Drupal 7 doesn’t have — layouts.

Check out the official theme conversion documentation for more details if your theme is not compatible with Backdrop’s theme system.

2. Test for Module Compatibility

Drupal modules will not work out of the box with Backdrop. Test each module you rely on to make sure that either the functionality it provides hasn’t either been included in Backdrop core or works as intended on the new version.

Many modules need only slight tweaks in order to work with Backdrop, but in the event you rely on some API features that have been altered you can find examples for how to use nearly any function and API call through Backdrop’s examples module.

The developer forum is also very friendly if you find yourself stuck anywhere along the way.

The Backdrop documentation also offers more detailed information regarding module conversion.

3. Create a Copy of Your Drupal 7 Site

Once you have made sure your themes and modules are compatible with Backdrop then Backdrop can handle migrating your database over pretty easily. To be as safe with your data as possible we’ll duplicate your Drupal site and migrate the duplicate over just in case something goes wrong somewhere along the way.

Create a New Database and Admin Account

You’ll need to create a new empty database, username, and password for Backdrop to use.

Usually this can be also be done in the server’s settings panel.

Clone the Old Database

Copy your old database into the new one that you just created for Backdrop. Use your new user with admin privileges.

You can accomplish this using a single command in the terminal.

mysqldump orig_drupal_db -u drupal_db_user --password=mYDrupalDBP@ssw0rd | mysql -u new_backdrop_user -p new_backdrop_db

You will be asked to verify the new password and boom — a duplicated database.

Clone the Old Drupal Site

Copy every file to the new Backdrop location. This ensures that your Drupal 7 site will still work after this update should you need to reference or fall back to it in the future.

Use cp with the -r flag to deep copy the site contents.

cp -r ./old_drupal_location ./new_backdrop_location

Update Database Credentials

In order to get the new copied Drupal site to access the new database you’ll need to use the new credentials you made. Do not run update.php. You’ll need to add the new database username and password to the settings.php file.

The default location for the site’s configuration file will be in:

new_backdrop_location/sites/default/settings.php

247 $databases = array (
248   'default' =>
249   array (
250     'default' =>
251     array (
252       'database' => 'new_backdrop_db',
253       'username' => 'new_backdrop_user',
254       'password' => 'newBackdropDBP@ssw0rd',
255       'host' => 'localhost',
256       'port' => '',
257       'driver' => 'mysql',
258       'prefix' => '',
259     ),
260   ),
261 );

Look for the above lines and update them with the new user and database credentials you created earlier.

4. Turn It Off

Login to your now duplicated Drupal 7 site using your old Drupal administration credentials. https://mynewbackdropsite.com/user

Make sure any installed modules are compatible with Backdrop and turn off any modules that aren’t.

Make sure the theme is set to Bartik.

Set site to Maintenance mode and kiss Drupal goodbye.

5. Replace Core Files

Add all files from the Backdrop repository replacing the core, themes, and modules folders with backdrop’s core, themes, and modules folders etc. Take care not to replace the sites folder in the update process.

Do not run update.php until the end of step 8.

6. Add Modules, Layouts, and Themes to Their Respective Folders

Any modules and themes that you want to use should now be moved to the new_backdrop_location/modules and new_backdrop_location/themes folder.

Backdrop changes the location of your contributed modules and themes directories to the site root instead of inside the sites folder. This means that going forward all core files will be located within the core directory.

7. Move files Location

Move any user files from new_backdrop_location/sites/default/files to new_backdrop_location/files

Create a soft link from new_backdrop_location/sites/default/files to new_backdrop_location/files

ln -s new_backdrop_location/sites/default/files new_backdrop_location/files

8. Update Backdrop’s Configuration File

Backdrop stores its configuration in a different location than Drupal.

new_backdrop_location/settings.php

  7 /**
  8  * Database configuration:
  9  *
 10  * Most sites can configure their database by entering the connection string
 11  * below. If using master/slave databases or multiple connections, see the
 12  * advanced database documentation at
 13  * https://api.backdropcms.org/database-configuration
 14  */
 15 $database = 'mysql://user:pass@localhost/database_name';
 16 $database_prefix = '';

Change Line 15 to include the correct database credentials.

While you’re in this file change update_free_access on Line 59 to TRUE.

 48 /**
 49  * Access control for update.php script.
 50  *
 51  * If you are updating your Backdrop installation using the update.php script
 52  * but are not logged in using either an account with the "Administer software
 53  * updates" permission or the site maintenance account (the account that was
 54  * created during installation), you will need to modify the access check
 55  * statement below. Change the FALSE to a TRUE to disable the access check.
 56  * After finishing the upgrade, be sure to open this file again and change the
 57  * TRUE back to a FALSE!
 58  */
 59 $settings['update_free_access'] = TRUE;

This will allow the update to proceed without needing to be logged in.

Save your changes to the configuration file and visit the update page:

http://mynewbackdropsite.com/core/update.php

Proceed with all the updates and before long you will be purring along with Backdrop.

9. Secure Your Site

After the update script finishes you’ll need to set update_free_access in the backdrop settings.php file back to FALSE.

Finally, enable your custom themes, layouts, and modules before turning off maintenance mode.

10. Fix CRON

If you have cron set up on your server you’ll need to update the location the cron job visits. The correct location will be listed at https://mynewbackdropsite.com/admin/config/system/cron

Because all of Backdrop’s core files exist in the core folder, you’ll need to remember to include /core in the cron.php and update.php paths.

For instance the cron path is https://mynewbackdropsite.com/core/cron.php?cron_key=abc123...

Conclusion

While Backdrop is very similar to Drupal 7, some key changes have been made to provide for the long term stability of the platform. By removing some of the cruft of Drupal 7 a few pain points in the update process may appear — particularly when using custom modules and themes. Overall though, the Backdrop foundation seeks to update the system while also maintaining as much compatibility with existing server infrastructure as possible.

The developers of Backdrop continue to add documentation to the site but sometimes you just need to talk to someone knowledgeable about the system. The forums are a great place to ask project specific questions and to get help with things that you may be stuck on.

If you like Backdrop you can also attend community meetings to get involved with the development process or contribute to the code base.