Site Factory

Staging a Factory to a non-production environment

As part of maintaining your 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 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, Site Factory scrubs user account and configuration information from any staged websites.

Important

  • In 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.

  • Manually creating users on your non-production environment can lead to user ID mismatches that cause website staging processes to fail. For more information, see Repairing user ID mismatches when staging a Factory.

  • Domains directly added to non-production environments are removed.

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

The website copy process can take a long time to complete, so 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.

  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.

    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 checkboxes to customize your staging deployment:

    • Stage all users checkbox: 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 management console and all stacks on the target environment checkbox: Delete all existing websites on all stacks in the non-production environment and replace them with new copies from the production environment.

      Important

      Selecting this checkbox when staging a factory with multiple stacks will overwrite all data for all websites on all stacks. This data cannot be recovered.

      • When staging, multi-stack customers can wipe one or more stacks instead of wiping the complete non-production factory.

      • When staging and selecting Wipe management console and all stacks on the target environment or Wipe all data on <stack_name>, a confirmation message is displayed that this process is irreversible and all data on target site factory will be lost.

    • Send a status email for each site checkbox: Receive a status email with the success or failure of each website as it is staged.

  5. (Optional) Choose whether to skip site files. Skipping files during staging reduces file storage and the staging operation time. Checking this box causes all files to be skipped during staging. To skip certain files, see Skipping certain files when staging a factory.

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

If your Site Factory Management Console displays task log warnings about the data synchronization process encountering an error, see Repairing user ID mismatches when staging a Factory.

Verify the status of a staging deployment

To verify the status of a staging deployment:

  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:

  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:

    • Cloud Platform

      1. Sign in to Cloud Platform.

      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.

    • 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 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 time: Mon Feb 24 13:28:38 2014 (13:28:38 GMT on February 24, 2014)

      • Unix timestamp: @1393248518 (13:28:38 GMT on February 24, 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.

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

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

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.

Troubleshooting staging deployments

If your staging process completes quickly, and your task log includes a SynchronizationDirector message like the following example, re-stage your non-production environment after selecting the Wipe target environment checkbox:

The target Site Factory is not in a working condition and an incremental
staging was requested which is not allowed in this situation.

If staging your non-production environment again doesn’t resolve the problem, contact Acquia Support.

Next step

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