Skip to main content
Log inGet free account
Last Reviewed: December 12, 2022

Migrate a Composer-based Drupal Site to a Build Tools Site

Migrate a Drupal site created via Pantheon Dashboard (or Terminus) to a Build Tools-based site.

Discuss in Slack
Edit this page on GitHub Report an issue with this doc

This guide shows you how to migrate a Composer-based Drupal site (site created via Pantheon dashboard or Terminus) to a Build Tools-based site.

If this is not your scenario, see Drupal Migration Guides for additional upgrade paths.

Overview

Drupal sites on Pantheon have Integrated Composer built-in to manage site dependencies. A Drupal site with Build Tools also provides site dependency management, as well as an external repository and a Continuous Integration workflow setup.

The goals of this migration are to:

  • Create a new Drupal site in Pantheon using the Terminus Build Tools plugin

  • Import your existing codebase, database, and files into your new site

Will This Guide Work for Your Site?

Confirm that your site meets the following requirements before you continue:

  • Ensure your site has the Pantheon drupal-composer-managed repository in its upstream.

    • Use Terminus to confirm the drupal-composer-managed Upstream

      Run the command terminus site:info $SITE to display the site's basic information and properties.

      The following is an abridged example of the output for a site upstream set to drupal-composer-managed:

      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           897fdf15-992e-4fa1-beab-89e2b5027e03: https://github.com/pantheon-upstreams/drupal-composer-managed.git...
------------------ -------------------------------------------------------------------------------------

      The following values indicate that a site is using a drupal-composer-managed upstream:

      • The Framework is drupal8

      • The Upstream includes https://github.com/pantheon-upstreams/drupal-composer-managed.git

Before You Begin

Clone your existing site to your local environment following the git clone command from the dashboard.

Note

The existing site's commit history will no longer exist after migrating to the new site.

Create a New Terminus Build Tools Drupal Site

  1. Follow the Terminus Build Tools Documentation to create a new Drupal site:

    terminus build:project:create --git=github --team='My Agency Name' d9 my-buildtools-site

  2. Wait for the site to be created and for the first build to complete.

Prepare the Local Environment

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

    • Mac users can use Homebrew to install Git, Composer, and PHP, along with their required dependencies. Note: Terminus 3 should be used for PHP >= 8.0. Restart the shell or terminal environment after entering the following command:

      brew install git composer php

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

  2. Get a local copy of both your new site (from the external repository) and your existing site codebase.

  3. Set the following temporary variables in your terminal session to match your folders location and sites names:

    export SOURCE=/absolute/path/to/source/site/codebase
export DESTINATION=/absolute/path/to/codebase/cloned/from/pantheon
export SOURCE_SITE_NAME=my-source-site
export DESTINATION_SITE_NAME=my-buildtools-site

Copy Existing Configuration

Copy any existing configuration from the source site and update the source path as needed to match your configuration folder:

rsync -avz $SOURCE/config/ $DESTINATION/config/ --delete --delete-after
# From $DESTINATION:
git add config -A
git commit -m "Pull in configuration from source site"

It is possible that the Drupal site might have relocated the configuration path to a different location. You can find your config.yaml files are via:

terminus drush $SOURCE_SITE_NAME.dev -- status --fields=config-sync

In some cases no files are copied through this step. This is not cause for concern.

Add Contributed and Custom Code

This section describes how to replicate your selection of contributed modules and themes, and any custom modules or themes your development team has created in your new project structure.

Contributed Code

The goal of this process is to have Composer manage all the site's contrib modules, contrib themes, core upgrades, and libraries (referred to as contributed code). The only items from the existing site that should remain in the Git repository are custom code, custom themes, and custom modules that are specific to the existing site.

Modules and Themes

Your site should already be managing contributed modules and themes through Composer. Follow the steps below to migrate these items to a new site.

  1. Open the source site composer.json.

  2. Run the composer require command for each module and theme in the $DESTINATION directory:

    composer require drupal/PROJECT_NAME:^VERSION

You can require multiple packages in the same command if desired.

Other Composer Packages

If you added non-Drupal packages to your site via Composer, use the following steps:

  1. Run the command composer require to migrate each package.

  2. Use the following command to display the differences between the versions of composer.json:

    diff -Nup --ignore-all-space $SOURCE/composer.json $DESTINATION/composer.json

Libraries

Libraries can be handled similarly to modules, but the specifics depend on how your library code was included in the source site. If you're using a library's API, you may have to do additional work to ensure that it functions properly.

Do not forget to commit your changes during these steps.

Custom Code

Manually copy custom code from the existing site repository to the Composer-managed directory.

Modules and Themes

  1. Run the following commands to move modules:

    mkdir -p $DESTINATION/web/modules/custom
cp -r $SOURCE/web/modules/custom $DESTINATION/web/modules/custom
# From $DESTINATION:
git add web/modules/
git commit -m "Copy custom modules"

  2. Run the following commands to move themes:

    mkdir -p $DESTINATION/web/themes/custom
cp -r $SOURCE/web/themes/custom $DESTINATION/web/themes/custom
# From $DESTINATION:
git add web/themes/
git commit -m "Copy custom themes"

Use the above commands to move custom code (if any) to your new site.

settings.php

Your existing site may have customizations to settings.php or other configuration files. Given that both sites ($SOURCE and $DESTINATION) have been created from the same upstream, it is ok to replace the $DESTINATION settings.php with the one coming from the $SOURCE site:

cp $SOURCE/web/sites/default/settings.php $DESTINATION/web/sites/default/settings.php
# Review changes and commit as needed

The resulting settings.php should not have a $databases array.

Additional Composer Configuration

Any additional Composer configuration that you have added to your site should be ported over to the new composer.json file. This can include configurations related to repositories, minimum-stability, or extra sections.

  1. Use the diff command to get the information you need to copy:

    diff -Nup --ignore-all-space $SOURCE/composer.json $DESTINATION/composer.json

  2. Commit your changes as needed.

Push to the External Repository Master Branch

  1. Push to the master branch in the external repository:

    git push origin master

  2. Confirm that the Continuous Integration workflow succeeds in committing your code changes to the Pantheon site.

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.

  2. Compress the resulting archive with gzip to reduce the size for a faster transfer:

    mysqldump -uUSERNAME -pPASSWORD DATABASENAME > ~/db.sql
gzip ~/db.sql
    • Replace USERNAME with a MySQL user with permissions to access your site's database.
    • Replace PASSWORD with the MySQL user's password. To force a password prompt, move -p to the end of the command and leave it blank. This prevents your MySQL password from being visible on your terminal.
    • Replace DATABASE with the name of your site database within MySQL.
    • ~/db.sql defines the output target to a file named db.sql in your user's home directory. Adjust to match your desired location.

The resulting file will be named db.sql.gz You can use either the Pantheon Dashboard or a MySQL client 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):

    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.

      Import MySQL database from file

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

Back Up the tokens.json file

  1. Connect to your site using SFTP command or credentials from your dashboard and get a backup of the following file:

    files/private/.build-secrets/tokens.json

  2. Use the SFTP get command to download the file to your local directory (this is only for SFTP command line use):

    echo "get files/private/.build-secrets/tokens.json" | $(terminus connection:info $DESTINATION_SITE_NAME.dev --format=string --field=sftp_command)

Upload Your Files

Files refer to everything stored inside sites/default/files. This usually consists of uploaded images, generated stylesheets, aggregated scripts, etc. Files are not under Git version control and are stored separately from the site's code.

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

Follow the steps below to export a tar.gz or .zip file of your directory files.

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

    Navigate to your Drupal site's root directory to run this command, which will create an archive file in your user's home directory:

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

  2. Select the Dev environment in the Site Dashboard.

  3. Select Database / Files.

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

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

    1. Click File in the MySQL database field > Choose File.

    2. Select your local archive file and click Import.

      Import MySQL database from file

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

Restore tokens.json file

  1. Connect to your site using SFTP command or credentials from your dashboard to restore the backup of the tokens.json file:

    files/private/.build-secrets/tokens.json

  2. Use the SFTP put command to upload the file from your local directory (only if using the SFTP command line):

    Note

    You must run this from the directory where the tokens.json backup was downloaded.

    echo "put files/private/.build-secrets/tokens.json" | $(terminus connection:info $DESTINATION_SITE_NAME.dev --format=string --field=sftp_command)

    You should now have all three of the major components of your site imported into your new site and CI should be working.

  3. Clear the caches on the Pantheon Dashboard.

Troubleshooting

Provided Host Name Not Valid

Update your settings.php file with a trusted host setting, if you receive the following error message:

The provided host name is not valid for this server

Refer to the Trusted Host Setting documentation for more information.

Working With Dependency Versions

Version compatibility issues can occur when packages pulled by Composer are updated along with their dependencies. If this happens, you will need to manually alter the version constraints on a given package in the require or require-dev section of composer.json to update the packages. Refer to the updating dependencies section of the Composer documentation for more information.

Troubleshoot package updates by running composer update. This updates composer.lock to the latest available packages. Package updates are constrained by version requirements in composer.json.

More Resources