Manually Migrate
Migrate a Drupal 8 Site to Drupal 9 on Pantheon
Contributors: Sarah German, Greg Anderson.
Discuss in our Forum Discuss in SlackIn 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.
Use Terminus to Confirm the drops-8 Upstream
Run
terminus site:info $SITE
to find the site'sFramework
. The result should bedrupal8
andUpstream
value should includegit://github.com/pantheon-systems/drops-8.git
.This example shows a shortened version of the output:
terminus site:info $SITE ------------------ ------------------------------------------------------------------------------------- ID abdc3ea1-fe0b-1234-9c9f-3cxeAA123f88 Name anita-drupal Label AnitaDrupal Created 2019-12-02 18:28:14 Framework drupal8 ... Upstream 8a129104-9d37-4082-aaf8-e6f31154644e: git://github.com/pantheon-systems/drops-8.git ... ------------------ -------------------------------------------------------------------------------------
The site does not use a nested docroot.
The process outlined in this guide will not work if the site repository has a
/web
folder at its root.See Serving Sites from the Web Subdirectory for information about nested docroots.
The site does not use Pantheon Search.
The site does not use another package and library manager like Ludwig.
Prepare the Local Environment
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.
Install the Terminus Site Clone plugin.
Clone your current Pantheon site repository to a working directory on your local computer.
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 replaceanita-drupal
in this example:export SITE=anita-drupal && echo "New alias set as $SITE"
How to Use Terminus to Find the Site Name
Use
terminus site:list
for a list of sites you have access to:terminus site:list --------------------------- --------------------- ------------- ------------------- ---------------- -------------------- --------------------- ------------- ------------ Name ID Plan Framework Region Owner Created Memberships Is Frozen? --------------------------- --------------------- ------------- ------------------- ---------------- -------------------- --------------------- ------------- ------------ anita-drupal abdc80ce-286c-1234- Sandbox drupal8 Canada 3374708c-987e-1234 2020-12-15 19:40:42 d3ecc20c-395a false anita-wordpres abdc9954-fab2-1234- Sandbox wordpress United States c96ddb25-336a-1234 2020-09-02 07:18:51 d3ecc20c-395a false
The site name is listed under
Name
. In this example,anita-drupal
.
This doc uses the following aliases:
- Alias:
D8_SITE
- Site Name:
best-drupal8-site-ever
- Site Name:
- Alias:
D9_SITE
- Site Name:
best-drupal9-site-ever
- Site Name:
Create a New Drupal 9 Site and Migrate the Drupal 8 Code
Create a new Drupal 9 site following the instructions in the Create a New Drupal 9 Site section.
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
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
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."
Compare your current
pantheon.yml
file with the new D9pantheon.upstream.yml
:git diff existing-8/master:pantheon.yml pantheon.upstream.yml
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), copypantheon.yml
over:git checkout existing-8/master -- pantheon.yml git commit -m "Update pantheon.yml."
Copy over any Quicksilver scripts referenced in
pantheon.yml
:git checkout existing-8/master -- private/scripts git commit -m "Add Quicksilver scripts."
List contrib modules and themes on your D8 site:
terminus drush $D8_SITE.dev -- pm:projectinfo --status=enabled --fields=name,version --format=table
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."
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."
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
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
Push the D9 codebase from your local machine up to Pantheon:
terminus connection:set $D9_SITE.dev git git push origin master
Run database updates:
terminus drush $D9_SITE.dev -- updatedb
Review the site, then proceed to launch using the Pantheon Relauch documentation.