Executing a migration into Site Factory¶

Import requirements¶

• Create one target website at a time in your Site Factory environment.
• Prepare your source website for export as described at Preparing a Drupal application for export.
• Check your code, configuration, and database for hard-coded paths to files in the files directory or theme, as these paths will change during the database import process.

Procedure¶

Use the following steps to migrate your website into Site Factory:

1. Initialize and deploy the theme repository. Although you can place your website’s themes in your sites/all/themes directory, Acquia recommends you use a dedicated, external theme repository. If you create an external theme repository, complete the following steps:

   1. Create a dedicated directory for themes, which will contain subdirectories for the website-specific themes. If you move all base themes into the main target repository, you can use the sites/[domain.com]/themes directory.

   2. Add all the files in your theme to a Git repository you have newly initialized with the following commands:

      git init
      git add .
      git commit -m "Example message: commit all themes"
      

   For more information, see Connecting to a theme repository.

2. Initialize and deploy your codebase. Acquia has identified the following best practices for preparing and deploying your website’s codebase to Site Factory:

   • The versions of Drupal core and contributed modules on your source and target websites must be identical.

   • All necessary modules and themes must be reachable for your target website, though their exact locations may differ.

   • Custom modules must be in the shared codebase across all websites, and not in website-specific sites/[domain]/modules directories.

   • Small, custom configuration files can remain in the sites/default directory.

   • Move any customizations to your website’s sites/default/settings.php file into another file or a post-settings.php hook, as the acsf-init command in Site Factory will overwrite the contents of the file and you will lose any customizations you made.

     Note

     For more information about acsf-init’s role in code deploys, see Updating with the acsf-init command.

   After you have prepared your source website’s codebase for migration, follow the instructions at Building your Drupal distribution to import it.

3. Create a complete and recent back up of all portions of your website, including the database, files directory, codebase, and themes.

4. If your website is active, enable maintenance mode before starting your migration. Maintenance mode prevents your website’s users from making changes to the website that may disappear during the migration process.

5. Simultaneously make a local backup of your website’s files directory while copying the files to your target website by executing the following commands:

   mkdir /tmp/local-site-archive
   drush -v rsync @source:%files/ /tmp/local-site-archive/files/
   drush -v rsync /tmp/local-site-archive/files/ @target:%files/
   

   If you already have a local backup, you can copy your files directly from your source website to your target websites by executing the following command:

   drush -v rsync @local-source:%files/ @target:%files/
   

6. When migrating your website from one host to another, you should review your database for differences between your source environment and target environment, paying close attention to any tables including references to file system paths.

   You should perform any needed changes on a local copy of your database, instead of your currently-live source website. To make a local backup of your website’s database, execute the following commands:

   drush -v @target sql-drop
   drush @source sql-dump > /tmp/local-site-archive/archive.sql
   

   Important

   Do not use the -v flag on the sql-dump command as it may corrupt your database export.

   Perform any needed changes (such as Secure Pages settings or file paths) to the database on your local copy of the database, and then upload the database to your target environment with the following command:

   drush -v @target sql-cli < /tmp/local-site-archive/archive.sql
   

7. Enable and configure Site Factory modules by performing the following steps:

   1. Open a command prompt window, and then run the following Drush command, based on your installed version of Drupal:
      • Drupal 9 or later – drush @target pm-enable acsf acsf_duplication acsf_theme acsf_variables
      • Drupal 7 – drush @target pm-enable acsf acsf_duplication acsf_theme acsf_variables acsf_pingdom acsf_openid
   2. Sign in to the Site Factory Management Console as a user with the Platform Admin role.
   3. In the top menu, click Sites.
   4. Identify the target website you want to modify, and then point to the Log In link for the website. Your browser will display the numeric website ID for the Log In link.
   5. Visit [domain].acsitefactory.com/node/[ID], replacing [domain] with your Factory’s default domain name, and [ID] with the numeric website ID you identified in the previous step.
   6. Copy the acsf-connect-factory Drush command listed under ACSF connect factory drush command, which contains the following parameters:
      • --include: Full path to your ACSF module
      • --site-admin-mail: Email address of your Site Factory administrator; the email address for user 1 will be set to this value
      • --site-owner-name: Drupal username of the user who created the website from the Factory user interface; this user can sign in to the Site Factory Management Console
      • --site-owner-mail: Email address of the user who created the website from the Factory user interface
   7. Execute the acsf-connect-factory command from the command line to update your target website with the information you provided.
   8. If your website uses a per-website directory for private files, update the Private file system path as described at Setting the private file directory on Cloud Platform

   After initialization, themes in dedicated repositories connected as described in Initialize and deploy the theme repository should display properly.

8. Sign in to your migrated website as an administrator, and then test the website to ensure the migration succeeded.

9. Disable maintenance mode on your newly-imported website.

Your website is now live on Site Factory. You can add a custom domain name to complete the migration.