Manually Migrate Sites to Pantheon

Manually migrate your site to Pantheon when any of the following apply:

• Large Drupal Site Archive: Site archive exceeds the import file size limit of 500MB.
• Large WordPress Site: WordPress site exceeds 500MB.
• Preserve Git History: You'd like to preserve your site's existing Git commit history.
• WordPress Multisite
• Plugin install unavailable on existing WordPress site: For example, if your existing site is hosted on WordPress.com, you'll be unable to install the Pantheon Migrations plugin.
• Local WordPress Site: If your WordPress site is only on your local machine and not yet live.
• Debug Failed Migration: It can be helpful to migrate your code, database, and files separately if the standard migration procedure failed.

Before You Begin

To ensure a successful migration, complete the following tasks on the source site before you start:

• Read Platform Considerations
• Upgrade to the latest version of WordPress or Drupal core
• Reference your plugins and/or modules against Modules and Plugins with Known Issues
• Make sure your code is compatible with PHP 7.2 or greater. Review your CMS's PHP version requirements. You may need to adjust PHP versions.
• Clear all caches
• Remove unneeded code, database tables, and files
• Configure SSH keys

chmod u+w sites/default/{.,settings.php}
mv sites/default/{settings.php,settings.local.php}
chmod u-w sites/default/{settings.local.php,.}

Create Pantheon Site

1. Go to your Personal Workspace and click the Migrate Existing Site button:

2. Enter your current website URL, choose your site type, and click Continue:

   

   Note: It is possible to upload a site running locally by putting in the local url. For example, (http://localhost).

3. Name your site and select an Workspace (optional), then click Create Site:

   

4. Click the link to manually migrate your site then select Yes to confirm:

   • WordPress
   • Drupal

   

   

5. Click Visit your Pantheon Site Dashboard:

   

Now that you have a new site on Pantheon, you're ready to add the major components from your existing site: custom code, files, and the database.

Import Your Code

Your code is all custom and contributed modules or plugins, themes, and libraries. The codebase should not include the wp-content/uploads (WordPress) / sites/default/files (Drupal) directory, or any other static assets you do not want tracked by version control.

The codebase for each CMS upstream offered by Pantheon can be found on GitHub:

• Drupal 7

• Drupal 8

• WordPress

   Note

  If your existing site is already version controlled and you would like to preserve the commit history, import the code from the command line with Git using the instructions below. If you prefer to avoid the command line entirely, we suggest importing the codebase using an SFTP Client such as Transmit or Cyberduck.

SFTP Client

1. Navigate to Code in the Dev tab of your Site Dashboard. Confirm that Development Mode is set to SFTP.

2. Click Connect with SFTP to access the credentials for connecting to your preferred SFTP client.

3. Click Open SFTP Client to open your default local SFTP client, and enter your password when prompted.

   If you run into issues, please refer to Pantheon's SFTP documentation.

4. Do not overwrite WordPress or Drupal core files on your Pantheon site. Upload your existing site's themes as well as plugins or modules to their locations within the root directory (code or wp-content, as shown below).

   • WordPress
   • Drupal

   Copy the following directories from your existing site to a matching directory in your new site's code/wp-content directory:

   • mu-plugins

   • plugins

   • themes

     As well as any other folders under wp-content that are not wp-content/uploads.

   Copy all files and folders inside the code/sites directory, except code/sites/default/files, from your existing site to a matching directory in your new site's code/sites:

   • libraries

   • modules

   • profile

   • themes

   • vendor

   • sites, excluding sites/default/files.

     Refer to the "Custom and contrib parts of your Drupal project" section of Basic Directory Structure of a Drupal Project for more details.

    Note

   You must prepare the directory and the database if you are using Multisite and want to migrate a sub-site.

   1. Copy the base site to a new directory.

   2. Delete all sites, with the exception of:

      • sites/{sitename}: the site you are migrating
      • sites/all: contains all of your site's modules and themes

   3. Rename sites/{sitename} to sites/default.

5. Return to the Site Dashboard on Pantheon, and you should see quite a few files ready to be committed to version control. Write a commit message such as "Import existing codebase" then click Commit.

Git

1. Navigate to your existing site's code directory in a local terminal. If your existing code is not already version controlled with Git, create a repository and add an initial commit:

   git init
   git add .
   git commit -m "initial commit"

2. From the Dev environment of the Site Dashboard, set the site's Development Mode to Git:

   

3. Copy the SSH URL for the site repository. Do not copy git clone or the site name.

   The URL should look similar to the following:

   ssh://codeserver.dev.{site-id}@codeserver.dev.{site-id}.drush.in:2222/~/repository.git

4. Add your new Pantheon site as a remote destination for your local code repository (replace <ssh_url> with the SSH URL copied in the previous step):

   git remote add pantheon <ssh_url>

5. Select the appropriate version of Git running on your local machine (git --version), then merge the codebase from your new Pantheon site with your existing site's codebase:

   • Git 2.8 and Below
   • Git 2.9 and Above

   git pull --no-rebase --squash -Xtheirs pantheon master

   git pull --no-rebase --squash -Xtheirs pantheon master --allow-unrelated-histories

   The output will resemble:

   Squash commit -- not updating HEAD
   Automatic merge went well; stopped before committing as requested

   If you haven't already configured SSH Keys, authenticate using your Pantheon Dashboard credentials when prompted for a password.

6. Review your current index using git status, then commit all changes.

   git add .
   git commit -m "Adding Pantheon core files"

7. Align your local branch with its remote counterpart on Pantheon:

   • Git 2.8 and Below
   • Git 2.9 and Above

   git pull pantheon master --no-rebase

   git pull pantheon master --no-rebase --allow-unrelated-histories

8. Push your newly merged codebase up to your Pantheon site repository:

   git push pantheon master

9. 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.

Add Your Database

The Database import requires a single .sql dump that contains the site's content and configurations.

1. Create a .sql dump using the mysqldump utility. For example:

   mysqldump db_name > backup-file.sql

2. Enter your username and password when prompted to authenticate the command.

   • You might want to consider using a terminus credential fetch to avoid entering credentials for future automation steps.

3. Run the command below to load the dump file back into the server:

   mysql db_name < backup-file.sql

You can also use the Pantheon Dashboard to add your site's database.

1. Select the Dev environment in the Site Dashboard.

2. Select Database / Files.

3. Click Import and add your archive accordingly (based on file size):

   • Up to 100MBs
   • Up to 500MBs
   • Over 500MBs

   If your archive is under 100MB, upload the file directly:

   1. Navigate to the MySQL database field > click File > Choose File.

   2. Select your local archive file > click Import.

      

      Note: If you recently imported the database and need to re-import, refresh the page and use a new filename for the database file.

   If your archive is less than 500MB, import it from URL:

   1. Navigate to the MySQL database field.

   2. Click URL.

   3. Paste a publicly accessible URL for the .sql.gz file > click Import.

       Note

      Change the end of Dropbox URLs from dl=0 to dl=1 to import your archive correctly.

      

   The following instructions allow you to add database archives larger than 500MBs using the command line MySQL client. You can also use a GUI client like Sequel Ace or Navicat. For more information, see Accessing MySQL Databases.

   1. Navigate to the Pantheon Site Dashboard.

   2. Open the Dev environment.

   3. Click Connection Info.

   4. Copy the Database connection string.

      The Database connection string will look similar to this:

      mysql -u pantheon -p{random-password} -h dbserver.dev.{site-id}.drush.in -P {site-port} pantheon

   5. cd into the directory containing your .sql file in your terminal.

   6. Paste the connection string and append it with: < database.sql.

      Your command will look like:

      mysql -u pantheon -p{random-password} -h dbserver.dev.{site-id}.drush.in -P {site-port} pantheon < database.sql

      If you encounter a connection-related error, the DB server could be in sleep mode. To resolve this, load the site in your browser to wake it up, and try again. For more information, see Troubleshooting MySQL Connections.

      The .sql file is imported to the Dev environment after you run the command.

Migrate Your Files

Files refer to anything within sites/default/files for Drupal or wp-content/uploads for WordPress, which typically includes:

• Uploaded images
• Generated stylesheets
• Aggregated scripts

Files are not under Git version control and are stored separately from the site's code. You must create and archive of your files and export it before you can upload it.

Export Your Files

Export a tar.gz or .zip file of your files directory:

• WordPress
• Drupal

cd wp-content/uploads
tar -czf ~/files.tar.gz .

cd sites/default/files
tar -czf ~/files.tar.gz .

Upload Your Files

You can use the Pantheon Dashboard, SFTP, or Rsync to upload your site's files.

Pantheon Dashboard

1. Go to the Site Dashboard, select the Dev environment, select Database / Files, and click Import to add your archive accordingly (based on file size):

2. Select the Dev environment in the Site Dashboard.

3. Select Database / Files.

4. Click Import and then add your archive (based on file size) by following the steps below.

   • Up to 100MBs
   • Up to 500MBs
   • Over 500MBs

   If your archive is under 100MB, upload the file directly:

   1. Navigate to the Archive of site files field > click File > Choose File.

   2. Select your local archive file > click Import.

   If your archive is less than 500MB, import it from URL:

   1. Navigate to the Archive of site files field > click URL.

   2. Paste a publicly accessible URL for the archive > click Import.

       Note

      You must change the end of Dropbox URLs from dl=0 to dl=1 to import your archive correctly.

   We recommend using the Terminus Rsync Plugin to transfer a large number of files. This allows you to avoid using multiple command line arguments and specific directory structures, which make it easy to introduce mistakes.

   Rsync only transfers the new changes to the directory after the initial rsync runs. This minimizes the time a site is in an unpredictable state (or offline) during the final step of migration, and allows you to bring over only new content rather than re-copying every single file.

   1. Run the following command to sync your current directory to Pantheon:

      terminus rsync . my_site.dev:files

   2. Run the following command if you experience interrupted transfers due to connectivity issues, which can occur when using Rsync manually.

      ENV='dev'
      SITE='SITEID'
      
      read -sp "Your Pantheon Password: " PASSWORD
      if [[ -z "$PASSWORD" ]]; then
      echo "Whoops, need password"
      exit
      fi
      
      while [ 1 ]
      do
      sshpass -p "$PASSWORD" rsync --partial -rlvz --size-only --ipv4 --progress -e 'ssh -p 2222' ./files/* --temp-dir=../tmp/ $ENV.$SITE@appserver.$ENV.$SITE.drush.in:files/
      if [ "$?" = "0" ] ; then
      echo "rsync completed normally"
      exit
      else
      echo "Rsync failure. Backing off and retrying..."
      sleep 180
      fi
      done

      Your files will be uploaded to your Pantheon site's Dev environment. If an error occurs during transfer, the command waits 180 seconds before continuing where it left off.

SFTP

Follow the SFTP instructions in the Large File Transfers with rsync and SFTP documentation.

rsync

Follow the Transfer Files with rsync instructions in the Large File Transfers with rsync and SFTP documentation.

Final Migration Steps

You should now have all three of the major components of your site imported into Pantheon.

1. Clear your caches on the Pantheon Dashboard.

2. Confirm that everything looks and behaves as expected.

3. Run the terminus site:import:complete <site_name> command to complete the import process.

Troubleshooting

fatal: Not possible to fast-forward, aborting.

This error may occur when trying to merge Pantheon's codebase into your existing repository as described earlier on this page in (step 5 of importing your code from the command line:

Not possible to fast-forward, aborting.

Depending on your Git version, you may see the following error instead:

fatal: refusing to merge unrelated histories

If you see this, it is possible your local Git configuration is disallowing non-fast-forward merges:

[pull]
rebase = TRUE
ff = only

In this case, you will want to remove ff = only from your .gitconfig file and try the merge command again.

More Resources

• Frequently Asked Questions

• Troubleshooting tips

• Importing Drush Site Archives with Terminus