ADVANCED: Incorrectly migrating a website without properly preparing for the attempt can involve data loss or a website outage event.
Attempting to import an existing Drupal website into Site Factory both requires that you understand how Site Factory structures the websites that it hosts, and that you complete the required preparatory work to ensure a smooth, repeatable migration process, which can provide you a local backup of your work should a rollback of your migration be needed.
Acquia has identified a common list of tasks to consider as part of your initial sprint (Sprint 0) planning for an Site Factory migration. Although the activities described on Checklist for migrating your sites to Site Factory are not a complete list, they can help you to identify the work that is necessary for a successful launch, and also identify the tools that can assist you.
File structure in Site Factory
When you are preparing to migrate a website, it helps to understand how files are organized in a Site Factory installation. Migrating a website into Site Factory involves all three major sections of a Drupal website:
The code in your Factory’s main version control repository contains your Drupal core and contributed module files that are to be used for all websites in your Factory. You must use version control processes to modify this code. Storage and retrieval times are faster here than in the distributed file storage system used in your website-specific files directory, so Acquia recommends that you store website-specific modules in one of the following directories, based on your distribution:
Using a distribution: profiles/[profilename]/modules
Not using a distribution: Current Drupal version: The top-level modules directory; Drupal 7: sites/all/modules/
Acquia discourages the use of the sites/default directory, with the exception of sites/default/files, as files in sites/default will not be included in website backups.
Your website’s files directory should contain the binary file assets (images and videos) your website needs that cannot be easily stored in version control. This files directory, and its contents, reside on a writable, distributed file system shared by all of your Site Factory-hosted websites. Since this file system is external to your shared codebase, access times for files stored in your files directory will be slower than access times for files stored in the shared codebase.
The files directory for your website is located at sites/g/files/[abcde], where [abcde] is a random string.
Public files reside in the sites/g/files/[abcde]/files/ directory.
Per-website theme directory
Your website-specific directories each contain a themes directory. Acquia strongly encourages that you store your per-website themes in this location, as storage and retrieval are far faster than the distributed storage system used in your website-specific files directory. For information about creating a theme repository for each of your websites in Site Factory, see Adding external themes to your site.
If you configure a dedicated theme repository for a website, sites/g/files/[abcde]/themes/site will be a symlink to local storage for that repository.
Configuration management directory
The current Drupal version requires writable directories for importing configuration values, such as user roles and permissions. The default location for the vcs and sync directories (config/default) is not writable on Site Factory, and must be configured by a post-settings-php hook as described in Importing a configuration directory.
Preparing Drush aliases for the import process
The import process uses Drush commands, so creating Drush aliases for your target website allows you to execute Drush commands without needing to sign in to your target website to copy files using SSH.
To configure your aliases to run the correct version of Drush, create a Drush aliases file based on the following example, altering the code to meet your needs:
$aliases['cloud-platform'] = array(
'path-aliases' => array(
// uncomment this line if deploying a D8 codebase
// '%drush-script' => 'drush8',
// uncomment this line if deploying a D7 codebase.
// '%drush-script' => 'drush6',
'%dump-dir' => '/mnt/tmp/',
),
);
$aliases['target'] = array(
'parent' => '@cloud-platform',
'uri' => 'mynewdomain.customername.acsitefactory.com',
'root' => '/var/www/html/AH_SITE_GROUP.AH_SITE_ENVIRONMENT/docroot/',
'remote-host' => 'managed-12345.defaultrealm.hosting.acquia.com',
'remote-user' => 'YOURUSERNAMEHERE',
'path-aliases' => array(
# the following is optional if you want to have a dedicated temp dir
# without many other files in there:
'%dump-dir' => '/mnt/tmp/AH_SITE_GROUP.AH_SITE_ENVIRONMENT/drush-import/',
),
);
The instructions in the website migration process that reference the @target alias assume you have created and implemented this file, and will execute @target commands from your local computer to affect your intended target website.
To verify that your Drush aliases are functioning properly, from a command line window, run the following command:
drush @target status
Examine both the Site path to determine if it matches the path sites/g/files/[abcde] (where [abcde] is a random string), and the File directory path to determine if it matches sites/g/files/[abcde]/f (where [abcde] is a random string).
If both the Site path and the File directory path values match the described strings, your Drush aliases are connecting to your server.
Common sources of problems with this file include the following:
Incorrect values for uri, remote_host, or remote-user
Not committing the sites/g/ directory to the codebase after executing drushacsf-init
ADVANCED: Incorrectly migrating a website without properly preparing for the attempt can involve data loss or a website outage event.
Attempting to import an existing Drupal website into Site Factory both requires that you understand how Site Factory structures the websites that it hosts, and that you complete the required preparatory work to ensure a smooth, repeatable migration process, which can provide you a local backup of your work should a rollback of your migration be needed.
Acquia has identified a common list of tasks to consider as part of your initial sprint (Sprint 0) planning for an Site Factory migration. Although the activities described on Checklist for migrating your sites to Site Factory are not a complete list, they can help you to identify the work that is necessary for a successful launch, and also identify the tools that can assist you.
File structure in Site Factory
When you are preparing to migrate a website, it helps to understand how files are organized in a Site Factory installation. Migrating a website into Site Factory involves all three major sections of a Drupal website:
The code in your Factory’s main version control repository contains your Drupal core and contributed module files that are to be used for all websites in your Factory. You must use version control processes to modify this code. Storage and retrieval times are faster here than in the distributed file storage system used in your website-specific files directory, so Acquia recommends that you store website-specific modules in one of the following directories, based on your distribution:
Using a distribution: profiles/[profilename]/modules
Not using a distribution: Current Drupal version: The top-level modules directory; Drupal 7: sites/all/modules/
Acquia discourages the use of the sites/default directory, with the exception of sites/default/files, as files in sites/default will not be included in website backups.
Your website’s files directory should contain the binary file assets (images and videos) your website needs that cannot be easily stored in version control. This files directory, and its contents, reside on a writable, distributed file system shared by all of your Site Factory-hosted websites. Since this file system is external to your shared codebase, access times for files stored in your files directory will be slower than access times for files stored in the shared codebase.
The files directory for your website is located at sites/g/files/[abcde], where [abcde] is a random string.
Public files reside in the sites/g/files/[abcde]/files/ directory.
Per-website theme directory
Your website-specific directories each contain a themes directory. Acquia strongly encourages that you store your per-website themes in this location, as storage and retrieval are far faster than the distributed storage system used in your website-specific files directory. For information about creating a theme repository for each of your websites in Site Factory, see Adding external themes to your site.
If you configure a dedicated theme repository for a website, sites/g/files/[abcde]/themes/site will be a symlink to local storage for that repository.
Configuration management directory
The current Drupal version requires writable directories for importing configuration values, such as user roles and permissions. The default location for the vcs and sync directories (config/default) is not writable on Site Factory, and must be configured by a post-settings-php hook as described in Importing a configuration directory.
Preparing Drush aliases for the import process
The import process uses Drush commands, so creating Drush aliases for your target website allows you to execute Drush commands without needing to sign in to your target website to copy files using SSH.
To configure your aliases to run the correct version of Drush, create a Drush aliases file based on the following example, altering the code to meet your needs:
$aliases['cloud-platform'] = array(
'path-aliases' => array(
// uncomment this line if deploying a D8 codebase
// '%drush-script' => 'drush8',
// uncomment this line if deploying a D7 codebase.
// '%drush-script' => 'drush6',
'%dump-dir' => '/mnt/tmp/',
),
);
$aliases['target'] = array(
'parent' => '@cloud-platform',
'uri' => 'mynewdomain.customername.acsitefactory.com',
'root' => '/var/www/html/AH_SITE_GROUP.AH_SITE_ENVIRONMENT/docroot/',
'remote-host' => 'managed-12345.defaultrealm.hosting.acquia.com',
'remote-user' => 'YOURUSERNAMEHERE',
'path-aliases' => array(
# the following is optional if you want to have a dedicated temp dir
# without many other files in there:
'%dump-dir' => '/mnt/tmp/AH_SITE_GROUP.AH_SITE_ENVIRONMENT/drush-import/',
),
);
The instructions in the website migration process that reference the @target alias assume you have created and implemented this file, and will execute @target commands from your local computer to affect your intended target website.
To verify that your Drush aliases are functioning properly, from a command line window, run the following command:
drush @target status
Examine both the Site path to determine if it matches the path sites/g/files/[abcde] (where [abcde] is a random string), and the File directory path to determine if it matches sites/g/files/[abcde]/f (where [abcde] is a random string).
If both the Site path and the File directory path values match the described strings, your Drush aliases are connecting to your server.
Common sources of problems with this file include the following:
Incorrect values for uri, remote_host, or remote-user
Not committing the sites/g/ directory to the codebase after executing drushacsf-init
Site Factory