Manually Migrate

Migrate a Drupal 8 Site to Drupal 9 on Pantheon

Contributors: Sarah German, Greg Anderson.

Discuss in our Forum Discuss in Slack

In this doc, you'll create a new Drupal 9 site and migrate the code from an existing Drupal 8 site to it.

Will This Guide Work for Your Site?

You might encounter significant issues if the site does not match these requirements.

Before you continue, confirm that your site meets the following:

  • The site has the Pantheon drops-8 repo in its Upstream.

  • The site does not use a nested docroot.

  • The site does not use Pantheon Search.

  • The site does not use another package and library manager like Ludwig.

Prepare the Local Environment

  1. Review our documentation on Git, Composer, and Terminus, and have them installed and configured on your local computer. Pantheon requires Composer 2 at minimum.

    • Mac users can use Homebrew to install Git, Composer, and PHP 7.4, along with their required dependencies. Restart the shell or terminal environment after entering the following command:

      brew install git composer php@7.4

    • Windows users can install Composer and Git, and may need to install XAMPP or similar to satisfy some dependencies.

  2. Install the Terminus Site Clone plugin.

  3. Clone your current Pantheon site repository to a working directory on your local computer.

  4. This guide uses several commands that depend on the site name in the local command line environment.

    To make this easier, set the temporary variable $SITE in your terminal session to match the site name. Read the steps further in this doc to see which sites should be aliased (it may be more than one), then replace anita-drupal in this example:

    export SITE=anita-drupal && echo "New alias set as $SITE"

This doc uses the following aliases:

  • Alias: D8_SITE
    • Site Name: best-drupal8-site-ever
  • Alias: D9_SITE
    • Site Name: best-drupal9-site-ever

Create a New Drupal 9 Site and Migrate the Drupal 8 Code

  1. Create a new Drupal 9 site following the instructions in the Create a New Drupal 9 Site section.

  2. From the local Drupal 9 site's directory, use Terminus to retrieve the D8 site's Git URL:

    terminus connection:info $D8_SITE.dev --field=git_url

  3. Add the Drupal 8 site as a remote repository called existing-8. Use the URL retrieved in the previous step:

    git remote add existing-8 ssh://codeserver.dev.xxxx@codeserver.dev.xxxx.drush.in:2222/~/repository.git
git fetch existing-8

  4. Copy over exported configuration from the original site. From your D9 site, run the following commands:

    git checkout existing-8/master -- sites/default/config
git mv sites/default/config/* config/
git commit -m "Add site configuration."

  5. Compare your current pantheon.yml file with the new D9 pantheon.upstream.yml:

    git diff existing-8/master:pantheon.yml pantheon.upstream.yml

  6. If you have customizations in your D8 site's pantheon.yml that you want to keep for D9 (e.g., a Quicksilver script or site-specific protected web paths), copy pantheon.yml over:

    git checkout existing-8/master -- pantheon.yml
git commit -m "Update pantheon.yml."

  7. Copy over any Quicksilver scripts referenced in pantheon.yml:

    git checkout existing-8/master -- private/scripts
git commit -m "Add Quicksilver scripts."

  8. List contrib modules and themes on your D8 site:

    terminus drush $D8_SITE.dev -- pm:projectinfo --status=enabled --fields=name,version --format=table

  9. Then use Composer on your D9 site to add these there:

    composer require drupal/ctools:^3.4 drupal/redirect:^1.6 drupal/token:^1.7
git add composer.*
git commit -m "Add contrib projects."

  10. Copy over any custom modules or themes from your D8 site:

    git checkout existing-8/master -- modules/custom themes/custom
git mv themes/* web/themes
git mv modules/* web/modules
git commit -m "Add custom projects."

  11. Check settings.php for any customizations to copy over:

    # Fetch your D8 settings file.
git show existing-8/master:sites/default/settings.php > web/sites/default/original-settings.php
# Check for any customizations (if this returns nothing, you can move on to the next step).
# Copy what you need over to web/sites/default/settings.php, and commit as needed.
diff -Nup web/sites/default/settings.php web/sites/default/original-settings.php
# Remove the original copy.
rm web/sites/default/original-settings.php

  12. Copy your files and database from your D8 site to the D9 site:

    terminus site:clone $D8_SITE.live $D9_SITE.dev --no-code --no-destination-backup --no-source-backup

  13. Push the D9 codebase from your local machine up to Pantheon:

    terminus connection:set $D9_SITE.dev git
git push origin master

  14. Run database updates:

    terminus drush $D9_SITE.dev -- updatedb

  15. Review the site, then proceed to launch using the Pantheon Relauch documentation.