Information for: DEVELOPERS   PARTNERS   SUPPORT

Finishing your Drupal 9 site

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 D9 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 D9 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 D9 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 D9 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 D9 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:

Acquia 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 navigate to https://[UUID].ide.ahdev.cloud to bring up the IDE.
  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 D9 site

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

Note

Acquia does not recommend making changes to the D9 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 your Drupal 9 site’s database to import new data

Your new Drupal 9 site should be considered read-only from the perspective of content changes. The Refresh capability of Acquia Migrate Accelerate allows you to down-sync the latest content changes from production so that you are always migrating against the latest data.

Navigate to Acquia Cloud Platform and click Refresh on the Acquia Migrate Accelerate Cloud environment to view the new content.

Once this is done, the Refresh tab on the Migrations Dashboard shows new records to import. Select them, click Import, and your content changes will make their way over to your new site.

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