Step 3: Upgrade the Drupal site

Upgrading from Drupal to Backdrop is exactly the same process as upgrading from Drupal 6 to Drupal 7. In short: Delete the old code, drop in the new code, and run the update script.

As with all major upgrades, we recommend having a second copy of your site so that the old version and the new version can be compared side-by-side. The instructions below outline that process.

1. Have a copy of your old Drupal 7 site that is web accessible (for example: https://drupal-example.com)
2. Set up a new Backdrop codebase that is also web accessible (for example: https://backdrop-example.com)
   • Download Backdrop and extract the code.
   • Create a new (empty) database
   • Do NOT install Backdrop.
3. Download all contributed modules, themes, and layouts for your Backdrop site, and place them in the appropriate directories.
   • Note: all modules, themes, and layouts must be in place before running the update, or crucial updates may be missed.
   • Note that D7 modules that depend on Entity API (such as Rules, Ubercart and others) have a special upgrade process (which you should have done some preparation for during the Preparation phase). Check the README of the modules and the README for Entity Plus.
4. Update your custom Drupal modules, and place the Backdrop versions in the modules directory for your backdrop site.
   • Note: At least 80% of the code in your custom Drupal modules should be compatible with Backdrop CMS. Major API differences include the configuration management system, and the Layouts system. Most other changes are minor. Learn more about converting Drupal 7 modules for Backdrop.
5. Copy the Drupal 7 files directory into your Backdrop codebase.
   • There are two possible ways to handle this:
     • Recommended: Move the files from where Drupal put them, to where you would prefer to have them
       1. Copy the files directory from Drupal 7 (usually drupal/sites/default/files) into the Backdrop site (usually backdrop/files)
       2. Create a default directory within backdrop/sites.
       3. Create a symlink in your filesystem from sites/default/files to files .
       4. After the upgrade, update the "Public file system path setting at admin/config/media/file-system to files.
     • Alternative: Place the files in the same location they were in Drupal
       1. Create a default directory within backdrop/sites.
       2. Copy the files directory from Drupal 7 (usually drupal/sites/default/files) into the Backdrop site (backdrop/sites/default/files)
6. Import the Drupal 7 database backup (backdrop-ready.sql) into the database you created in step 2.
7. Update the Backdrop settings.php file according to step 2 from the Installing Backdrop page.
   • Connect the new Backdrop site to the old Drupal 7 database.
   • Review (and possibly update) where configuration files should be stored.
   • Set $update_free_access to TRUE.
   • (optional) Define the Layout Template to use for block placement during the upgrade.
   • Do NOT run the installer. The next step will create the necessary configuration files as well as update the database.
8. Open up a browser, and visit https://backdrop-example.com/core/update.php to proceed with the update. (Replace example.com here with your domain or local site alias)
   • Note: You will need to be both logged in, and have sufficient privileges to run the update. If this is not the case, you can change $settings['update_free_access'] = TRUE; in your settings.php file.
   • Note: Your site will not function normally, until after the update has been run; we recommend you run the update script before visiting any other page on your site.
9. There will be over one hundred pending updates, but don't worry; in most cases, it will only take a few seconds to complete.
10. Once done, click around your Backdrop site to confirm everything is working as expected.

You're done! Now test everything

Congratulations, your old Drupal 7 site is now shiny and new, and running on Backdrop CMS! In order to return your site to its previous working condition, however, there are just a few more steps.

1. Check that your theme of choice is properly enabled. If you are using a different theme in Backdrop than you did in Drupal, the new theme should be enabled now.
   • If the site was using a custom theme in Drupal 7 and the new version was not present during the upgrade, the theme will need to be ported to Backdrop, placed in the codebase, and the update should be run again.
   • If the site was using a contrib theme for Drupal 7 and the new version was not present during the upgrade, this will need to be downloaded, ported if necessary, and the update should be run again.
   • Note: Theme's don't usually have updates, but it's a best practice to have the Backdrop version of the theme be present during the final update, because modules and/or other system components may depend on the theme or theme settings during the upgrade.
2. Check blocks & layouts.
   • Double-check block positioning.
     • During the upgrade, Backdrop will attempt to match the regions your blocks were placed into from the Drupal 7 theme.
       • The machine names of the regions must match between the Drupal 7 theme, and the Backdrop Layout Template used during the upgrade (the layout template can be defined in settings.php).
   • Note: for this reason, it will be helpful to keep the Backdrop layout region names the same as the Drupal 7 theme regions.
   • If you were using a layout solution other than Blocks for Drupal 7, your old layouts will need to be recreated for Backdrop CMS.
3. Check views.
   • Double check your views. Backdrop will attempt to upgrade your views, but there are some D7 views components that do not have comparable equivalents in Backdrop (those may show as having broken/missing handlers, and need to be updated).
4. Check contrib projects.
   • Though all contrib projects should contain upgrade paths from Drupal 7 to Backdrop, it is possible that your site contains a use-case that has not yet been thoroughly tested. Test everything, and report any issues in the appropriate issue queue.