Information for: DEVELOPERS   PARTNERS

Staging a Factory to a non-production environment

As part of maintaining your Acquia Cloud Site Factory platform, you will develop new features and functionality that you want to test against a representative sample of your websites. To test your feature branches before making them available to your website visitors, you should stage your factory, which copies your websites from your production environment to the non-production environment that you select. The staging process also sends the multisite management information that is required by Acquia Cloud Site Factory to those non-production environments.

The Factory staging process copies both the multisite management information and the selected websites from the production environment, optionally deleting everything previously in the non-production environment. After completing the copy process, Acquia Cloud Site Factory scrubs user account and configuration information from any staged websites.

Important

In Acquia Cloud Site Factory, new websites should first be created in your production environment, and then staged to your non-production environments for thorough testing before deploying them to production.

Steps in staging a factory

To stage your Factory, you must complete the following steps in the overall process:

  1. Sign in to your Site Factory Management Console using an account with either the developer or release engineer role
  2. Copy production data to non-production environments
  3. Verify the status of a staging deployment
  4. Deploy new code to the non-production environment
  5. Verify execution of post-staging-update hook scripts

After copying your data, verifying it, and deploying code, review the instructions for signing in to a staged and scrubbed website.

Copy production data to non-production environments

Because the website copy process can take a long time to complete, when copying websites to a non-production environment, you should not select all of your websites for testing. Instead, stage a representative sample of your production websites to ensure that the updated code functions correctly. To do so, complete the following steps after signing in to your Site Factory Management Console:

  1. In the admin menu, click Administration, and then click the Deploy staging environment link.

  2. If your subscription contains multiple non-production environments, select the non-production environment to which you want to stage websites.

    Select an environment

  3. Select one or more websites that you want to copy to your non-production environment. To do this, in the Choose sites to deploy field, start entering a site name, and then click the correct website from the displayed list.

    Enter website name

    Note

    If you select a primary or secondary website contained in a site collection, the copy process will stage all of the websites in the site collection.

  4. Select one or more of the following check boxes to customize your staging deployment:

    • Stage all users check box – Copy all user accounts (without scrubbing the user account list) to the non-production environment. All existing user accounts in the non-production environment will be updated.
    • Wipe target environment check box – Delete all existing websites in the non-production environment, and replace them with new copies from the production environment.
    • Send a status email for each site check box – Receive a status email with the success or failure of each website as it is staged.
  5. Click Deploy.

After beginning the deployment, you should monitor the progress of the deployment to monitor for errors, and to determine when your staging environment is ready for use.

Verify the status of a staging deployment

To verify the status of a staging deployment, complete the following steps:

  1. Sign in to your production environment’s Site Factory Management Console using an account with either the developer or release engineer role.
  2. In the admin menu, click Administration, and then click the Staging deployment status link.
  3. Under Filter tasks, review the staging progress bar to determine if your deployment completed successfully or contained failures.

After verifying that data copied successfully to your non-production environment, you should deploy new code to the non-production environment.

Deploy new code to the non-production environment

To deploy your release branch to the websites you staged to the non-production environment to ensure that there are not any errors or branch integration issues, complete the following steps:

  1. Visit the Site update page on your non-production environment’s Factory server. Complete the following steps, depending on where you are currently signed in:

    • Acquia Cloud
      1. Sign in to Acquia Cloud.
      2. Go to Cloud > Workflow, and then click the Update code link for the Dev or Stage environment. If you are not already signed in, you will be redirected to a sign-in page. Sign in using an account that has been assigned the release engineer role.
    • Acquia Cloud Site Factory
      1. Sign in to your non-production environment’s Site Factory Management Console using an account with the release engineer role.
      2. In the admin menu, click Administration, and then click the Update code link.
  2. In the Start time section, select from the following options to control when Acquia Cloud Site Factory will start the code update process:

    • Immediately – Starts the code update process when you click Update.
    • At a specific time – Starts the code update process at a specific time. In the Time field that appears, enter a time using the strtotime format, which can include specific or relative values that include the following examples:
      • Date and timeMon Feb 24 13:28:38 2014 (13:28:38 GMT on 24 February 2014)
      • Unix timestamp@1393248518 (13:28:38 GMT on 24 February 2014)
  3. In the Site update action section, in the Choose a path to deploy list, click the release branch that you want to test.

  4. After you select your release branch, select the action that describes the type of code update you want to deploy from the following options:

    • Code only – Causes the update to set only the version control system (VCS) code path, which it does for all of the websites at the same time. This can reduce the time required to complete the process.

      Select this option only if you meet both of the following conditions:

      • The release branch does not contain any update hooks.
      • Your code does not require a cache clear or a registry rebuild.
    • Code and databases (normal usage) – Causes the update to sync the environment’s VCS path names, manage the websites’ custom domain names, and complete the following steps for each website, from one to the next:

      1. Inspects the website to ensure that it does not have any known issues
      2. Enables maintenance mode for the website
      3. Puts the code on the website
      4. Runs updates
      5. Clears the website’s cache
      6. Disables maintenance mode
    • Code and databases, and rebuild registries – Causes the update to complete all of the actions from the Code and databases option, while also rebuilding the registries.

      Note

      To use this option, you must add Registry Rebuild to the docroot/sites/all/drush folder in your code repository. If you have not added Registry Rebuild to this folder (even if you have added it to a folder in specific websites’ repositories), the code update will use the Code and databases option and add a warning to the logs.

      Select this option if you have moved files around in your code repository since the last time you sent code to the environment (for example, moving an installed module from /sites/all/modules to /sites/all/modules/custom).

  5. Click Update.

Acquia Cloud Site Factory begins the update process for the staged websites. If you encounter errors during the update, examine the At a glance section on the Site update status page. For more information about resolving update errors, see Resolving codebase update errors.

After you have successfully deployed the release branch on your non-production environment, you can test your updated, staged websites that contain your changes to the codebase.

If you need to deploy an updated release branch, use the previous steps for deployment and testing.

Signing in to a staged and scrubbed website

Acquia Cloud Site Factory starts the staging process by copying the selected websites and the Site Factory Management Console to the environment you selected. Although the staging process copies the files and databases associated with each selected website, it scrubs the websites of personal data, including the email addresses of user accounts, for all users without either the developer or release engineer roles.

As a result, to sign in to either a staged website or the Site Factory Management Console on the Dev or Test environment, you may not be able to use your usual email address. By default, the scrubbing script replaces your email address username with userXXXXX (where XXXXX is your user account number). You can either sign in using this scrubbed username, or you can follow the procedures described in Protecting accounts during staging or Protecting hosted website accounts during staging to keep your email address from being scrubbed.

For both a list of information scrubbed by default from staged websites and instructions for creating a separate scrub script to remove custom website information that you do not want to copy to staging, see Scrubbing sensitive data from staged sites.

Verify execution of post-staging-update hook scripts

Acquia Cloud Site Factory offers a post-staging-update hook to synchronize data structure changes and module changes from your production environment to your newly-staged non-production environment. If you have created any post-staging-update hooks, you should verify the hook script executed successfully on all newly-staged websites.

Next step

After you have completed your testing on your staged websites, you can deploy your code changes to your production websites.