Move existing Drupal website to Pantheon

In this article, we will describe a path to manually move a Drupal 8 website from any place where is hosted to Pantheon.

Why manually?

There are many reasons you should need this kind of process:

  • You have a large Drupal archive, the archive (sites/*/files, for example) is greater than the guided migration import limit of 500 Mb. 
  • Preserve Git commit history of the project repository.

Before we start, let’s review what you will need:

  • Access to the Pantheon account where the site will be moved to.
  • Upgrade to the latest version of Drupal core.
  • Code compatible with PHP 7.2. If not, be prepared to adjust PHP versions.
  • If the site works with a Drupal Composer Project Templates or similar, you have two options, change the folder structure to serve the site from the docroot. Otherwise, you will need to update settings on Pantheon to specify the nested docroot.

Now we are ready to start

  1. Navigate to your User Dashboard and click the Migrate Existing Site button.
  2. Enter your current website URL, choose your site type (Drupal 8), and click Continue.
  3. Name your site and select an Organization (optional), then click Create Site.
  4. Click the link to manually migrate your site then select Yes to confirm.
  5. On the next page, click on Visit your Pantheon Site Dashboard.

Import Your Code

In our scenario, we will use Git (remember that we want to preserve Git commit history). Therefore, we will need to take care of several things to merge our commit history with the one that is already available on Pantheon.

  1. From the Dev environment of the Site Dashboard, set the site’s Development Mode to Git.
  2. Look for the SSH URL that is available under the dropdown “Clone with git”. For example: ssh://{site-id}{site-id}
  3. Add your new Pantheon site as a remote destination for your local code repository using the SSH URL copied in the previous step: git remote add pantheon ssh://{site-id}{site-id}
  4. Next, you will need to run: git pull --no-rebase --squash -Xtheirs pantheon master --allow-unrelated-histories
  5. Solve any Git conflict. Another important things to resolve, are the composer.json, composer.lock and the .gitignore files. You probably need to combine the one from Pantheon with the one you had on your site. My suggestion is to carefully merge composer.json file and then run: composer update --lock //adjusts the composer.lock file
  6. At the moment, we can’t simply use Composer commands on Pantheon when we perform a build to an environment. We need to add all contrib files to the repo. If we choose to go with this alternative, we need to make sure of removing any .git folder or anything else that could be interpreted as a git submodule. A good way to do this is to do the following:
    • cd modules/contrib
    • find. ( -name ".git" -o -name ".gitignore" -o -name ".gitmodules" -o -name ".gitattributes" ) -exec rm -rf -- {} +
  7. Run any tests to make sure the site works fine.
  8. Add all changes to git:
    • git add .
    • git commit -m "Adding Pantheon core files"
    • git pull pantheon master --no-rebase --allow-unrelated-histories
  9. Push your changes to the Pantheon upstream: git push pantheon master
  10. Go to the Code tab of your Dev environment on the Site Dashboard. You should see your site’s pre-existing commit history and the most recent commit adding Pantheon’s core files.

Import the database

  1. Create a .sql dump using the mysqldump utility. To reduce the size for a faster transfer, we recommend you compress the resulting archive with gzip:
  2. From the Site Dashboard, select the Dev environment
  3. Select Database / Files.
  4. From your terminal, cd into the directory containing your .sql file. Paste the connection string and append it with < database.sql: mysql -u pantheon -p{random-password} -h{site-id} -P {site-port} pantheon < database.sql

Import the files

I’m pretty sure that the website you need to move to has more than 500Mb, if that is the case, you can only use the third alternative through Terminus command.

  1. Install Terminus
  2. Create a machine token and authenticate from your computer
  3. (recommended) Install rsync plugin for Terminus
  4. Follow some recommendations to customize the rsync command parameter, for example: rsync -rLvz --size-only --checksum --ipv4 --progress -e 'ssh -p 2222' ./files/. --temp-dir=~/tmp/ {pantheon env site}.{pantheon site name}@appserver.{pantheon env site}.{pantheon site name}

Other considerations

Timeouts: if the site has long batch processes or functions that take more time than usual to complete, you will need to refactor or find another alternative. Check this section for more information.


Got questions?

Feel free to leave any questions. You can also reach the Slack Pantheon to get help.


Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.