Resources

Finishing your Drupal 9 site

Note

Acquia will remove all features of Acquia Migrate Accelerate from Cloud Platform on April 10, 2024. For all Drupal site owners, an open source version of the Acquia Migrate Accelerate module is available in the community. For more information, see Acquia Migrate: Accelerate - now open source!.

After migrating your Drupal 7 site to Drupal 9 with Acquia Migrate Accelerate, you must perform additional steps to finish your site and promote it to your Development or Staging environment.

Building additional configuration

Build the configuration that could not be migrated, such as Views, or build a new configuration for your Drupal 9 site. Acquia recommends that you build the configuration in the Migration environment so that you can do a final content refresh before promoting it to the Development or Stage environment.

You cannot add content to your Drupal 9 site while it is still on the Migration environment. This is by design, otherwise it would not be possible to refresh the content on your site with the latest content from your D7 source site (either the new content would get overwritten or the IDs would get out of sync). To create a new content type or content, you can make that change on your D7 site, and migrate it to your Drupal 9 site. You can also make the updates after promoting the site to Development or Stage.

Port custom modules / build out the custom theme

You can move your Drupal 9 site to a Cloud IDE to manage custom modules and themes. After you finish working with custom modules and themes, Acquia recommends that you move your site back to the Migration environment to do a final content refresh before promoting it to the Development or Stage environment.

Instructions for moving your site to an IDE:

Cloud IDEs are a development environment in your browser, already set up with handy tools, such as Composer, Drush, and XDebug. These will be useful if there are migration issues surfaced by Acquia Migrate Accelerate that you want to dig into further.

Set up Cloud IDE

  1. Follow the instructions at Getting started with Cloud IDE to create your Cloud IDE.

  2. Click Launch Cloud ID or access the link in the following format to bring up the IDE:

    https://[UUID].ide.ahdev.cloud

  3. From the IDE, perform the Configure the IDE steps, so that the new IDE is connected to your subscription and can perform the tasks as you.

Copy over your Drupal 9 site

To move the Drupal 9 site with AMA to the Cloud IDE:

Note

Acquia does not recommend making changes to the Drupal 9 database in the IDE. Make all database changes on D7 source database, and use Refresh to update the data on your Drupal 9 site.

  1. Follow the steps mentioned in Cloning your Cloud application into your IDE to copy the Drupal 9 codebase, database, and files from your AMA environment. It will have a machine name of odeXX and a branch name of ama-XXXXX. For example, [2] Test Migration, ode11 (vcs: ama-2ba1da).

  2. When prompted for the database to copy, choose the one with the same name as your subscription, not the one named ama-test-XXXXX. This is your site’s Drupal 9 database; the other is the Drupal 7 database.

  3. Once completed, adjust your file to point at Cloud IDE’s database. Open docroot/sites/default/settings.php and add the following at the bottom:

    // Drupal 9 database connection.
    $databases['default']['default'] = [
     'database' => 'drupal',
     'username' => 'drupal',
     'password' => 'drupal',
     'host' => 'localhost',
     'driver' => 'mysql',
    ];
    
  4. At the bottom of your ~/project/docroot/sites/default/settings.php file, you will see the following lines:

    if (file_exists('/var/www/site-php')) {
     if
     (file_exists('/var/www/site-php/testode1/D9-ode1-test-settings.inc')
     ) {
     require('/var/www/site-php/testode1/D9-ode1-test-settings.inc');
     }
    }
    

    Comment out those lines. As that file does not exist (but /var/www/site-php does exist), other stuff such as database connection hash_salt, and config_sync_directory will also be missing, and Drupal won’t start properly.

  5. SSH into your AMA environment and open the file. Insert the name and number of your IDE. In the example, “test” is used for the name of the IDE, and “1” is used for the number of the IDE.

    ssh [email protected]
    cat /var/www/site-php/testode1/D9-ode1-test-settings.inc
    
  6. Locate the line with $drupal_hash_salt = ‘(long, unique string)’;

  7. Copy this into your IDE’s settings.php file:

    $drupal_hash_salt = '(long, unique string)';
    $settings['hash_salt'] = $drupal_hash_salt;
    
  8. Click Open Drupal Site from the IDE to see the changes. If all goes well, you should see the AMA start page, albeit with source database and source files not yet set.

Debugging a migration or writing a custom migration

You must bring over the data from the Drupal 7 source site when you want to:

  • Debug a pre-existing migration. For example, step through it with xdebug to figure out why it is crashing.

  • Develop a new migration. For example, for a custom Drupal 7 module.

Note

Perform the steps outlined in the Port custom modules/build out the custom theme section, and then perform the additional steps in the following sections. You can skip these steps if you are porting a module or a custom theme.

Copy over your D7 files

To get past this step and get AMA working, you must down-sync the D7 files/db copy from the AMA environment to the Cloud IDE environment.

The copy of D7 files is located in the /home/[subscription]/[env]/ama_source directory on the AMA site. To copy it over, log in to the IDE and type:

$ cd ~
$ scp -r
[email protected]:/home/test/ode1/ama_source

Edit ~/project/docroot/sites/default/settings.php and update the settings at the bottom to point to the new directory:

$settings['migrate_source_base_path'] = '/home/ide/ama_source';
$settings['migrate_source_private_file_path'] = '/home/ide/ama_source
files-private';

Copy over your D7 database

You need to effectively import the latest database backup into Cloud IDE’s drupal2 database.

  1. Go to your AMA environment’s database backup page.

  2. Click Download on the most recent backup of the ama-dest-XXX database (Drupal 7).

  3. Copy the manual download link and go to your Cloud IDE.

  4. Type the following, including the quotes:

    $ cd ~/ama_source
    $ wget -O d7db.sql.gz 'PASTE_URL_HERE'
    $ gunzip d7db.sql.gz$ mysql -udrupal -pdrupal drupal2 < d7db.sql
    
  5. Disable the write protection in the IDE by running the chmod 644 docroot/sites/default/settings.php command.

  6. Add a second $databases entry for the D7 database in ~/project/docroot/sites/default/settings.php.

    // Note: array key MUST be 'migrate' and database MUST be 'drupal2'!
    $databases['migrate']['default'] = [
    'database' => 'drupal2',
    'username' => 'drupal',
    'password' => 'drupal',
    'host' => 'localhost',
    'driver' => 'mysql',
    ];
    

    On successful completion of the steps, the Drupal start page shows files/db steps crossed out and the Import your content active field active. It also takes you to the AMA dashboard.

  7. Before moving your site back to the Migration environment, re-enable the write protection by running the chmod 444 docroot/sites/default/settings.php command.

Refresh the database of your Drupal 9 site to import new data

Your new Drupal 9 site is read-only from the perspective of content changes. With the refresh functionality in Acquia Migrate Accelerate, you can down-sync the latest content changes from production so that you only migrate against the latest data.

To use the refresh functionality:

  1. Sign in to the Cloud Platform user interface.

  2. For the Acquia Migrate Accelerate environment, click Refresh to view the new content.

    On completion of the refresh process, the Refresh tab in the Migration Dashboard displays the new records that need to be imported.

  3. Select the records and click Import.

    The system migrates the new content changes to the new site.

Warning

While the preceding process works in Cloud Classic environments, Cloud Next environments have a known issue. For more information, see File copy operation takes longer in Cloud Next compared to Cloud Classic.

Promote to the Development or Stage environment

After finishing the migration and doing a final content refresh, you must promote your site to the Development or Staging environment. Navigate to Cloud Platform and click the Promote button associated with the Migration environment.

Note

Do not bypass the Promote button to move your site to Development or Stage.

You will be prompted to select the environment to which you’d like to promote. You cannot promote to another CD Environment, to an IDE, or directly to Production.

After you promote your site to Development or Stage, you will need to uninstall the Acquia Migrate Accelerate module before you’ll be able to make any content changes to your new site. Your site will remain Read Only until the module is uninstalled.