Using your own Drupal distribution

Managing your PaaS subscription

As a PaaS subscription customer you can use the Drupal 8 or Drupal 7 distribution of your choice for the websites in each of your Site Factory stacks. You can also create multiple installation profiles within your custom Drupal distribution. To ensure that your websites that use a custom distribution can communicate with Acquia Cloud Site Factory and the Site Factory Management Console, you must add the Acquia Cloud Site Factory Connector module to your distribution's code.

Using a Drupal custom distribution

Your custom Drupal distribution can be based on either Drupal 8 or Drupal 7. A single Acquia Cloud Site Factory stack can use either Drupal 8 or Drupal 7, but not both; if you have some websites that need to use Drupal 8 and some that need to use Drupal 7, you will need to manage them in separate Acquia Cloud Site Factory stacks. For more information, see Using Site Factory stacks.

Be sure to use the correct version of the Acquia Cloud Site Factory Connector module for your version of Drupal:

Setting up a custom distribution

To use a custom distribution with your Acquia Cloud Site Factory websites, complete the following steps:

  1. Add your SSH key to Acquia Cloud, and then clone the code repository for the website that you want to use to your local computer. For information about this process, see Preparing for the PaaS workflow.
  2. On your local computer, delete all of the files and subdirectories contained by the docroot that you cloned from Acquia Cloud Site Factory. While removing its contents, be sure to not delete the actual docroot directory.

    You can run the following Git command from the docroot directory to remove the files:

    git rm -r * .htaccess .gitignore

    Don't run this Git command after you have installed your Drupal distribution in the docroot.

  3. Move your custom Drupal distribution into the now empty docroot directory.

    After you do this, the docroot should contain the distribution's index.php file, along with all other files and subdirectories.

  4. Download the Acquia Cloud Site Factory Connector module from drupal.org and extract its contents into your distribution.

    You can use the following Drush command to do this:

    drush dl acsf
  5. Ensure that each of the following files can be read, written to, and executed by its owner, its group, and by other users:

    • hooks/common/pre-web-activate/000-acquia-deployment.php
    • hooks/common/post-db-copy/000-acquia_required_scrub.php

    To do this on Unix-like operating systems, use a command similar to the following:

    chmod 0755 [file names]
  6. Configure your installation profiles to require the module using the appropriate instruction, based on your installed version of Drupal:
    • Drupal 8 - Add the following line to your profile's installation profile file at profiles/[profilename]/[profilename].info.yml, where [profilename] is the name of your profile:

      - acsf
    • Drupal 7 - Add the following line to one of your profiles' .info files:

      dependencies[] = acsf
  7. Run the following Drush command from the docroot directory to initialize your custom distribution:

    drush --include=/path/to/acsf/acsf_init acsf-init

    The Drush command creates several directories and then copies files that Acquia Cloud Site Factory requires for its tasks, including locating the correct database credentials.

  8. Run the following Drush command from the docroot directory to check that everything is in order before you commit the custom distribution to the repository:

    drush --include=/path/to/acsf/acsf_init acsf-init-verify

    You should see this output from the acsf-init-verify command:

    acsf-init required files ok
  9. Commit and push your custom distribution's files to Acquia Cloud Site Factory. For the specific procedure to guide you through this process, see Preparing for the code deployment.
  10. Update your Prod environment with the custom distribution's files that you just pushed. For the specific procedure to guide you through this process, see Deploying your code.
  11. If your custom distribution includes more than one installation profile, enable any installation profiles that you want site builders to be able to choose when they create new websites. For the specific procedure to guide you through this process, see Enabling installation profiles.

Acquia Cloud Site Factory now uses your custom Drupal distribution for any new websites that you create, and your site builders can select any enabled installation profile when they create a new website.

Modifying settings.php for local development

The Acquia Cloud Site Factory Connector module checks to ensure that the settings.php file includes only the required settings for Acquia Cloud Site Factory. If you are doing local development of a custom Drupal distribution for Acquia Cloud Site Factory, you may need to make changes to settings.php that are inconsistent with the requirements enforced by the Acquia Cloud Site Factory Connector module.

The acsf-init command has an option that you can use to avoid this conflict. If you are running a Drupal website that includes the Acquia Cloud Site Factory Connector module outside of Acquia Cloud Site Factory, you can run acsf-init with the --skip-default-settings parameter to skip the settings.php check, using a command similar to the following:

drush --include=/path/to/acsf/acsf_init acsf-init --skip-default-settings

This enables you to locally deploy and test a version of settings.php with settings needed for local development, while still ensuring that your production websites use the version of settings.php required by Acquia Cloud Site Factory.

Updating the module

Whenever the Acquia Cloud Site Factory Connector module is updated to a newer version, complete the following steps to update the module in your Drupal distribution:

  1. Download and extract the updated Acquia Cloud Site Factory Connector module from drupal.org into your distribution.
  2. Update your distribution by running the following Drush command:

    drush --include=path/to/acsf/acsf_init acsf-init
  3. Commit and push your custom distribution's files to Acquia Cloud Site Factory. For the specific procedure to guide you through this process, see Preparing for the code deployment.
  4. Update your Prod environment with the custom distribution's files that you just pushed. For the specific procedure to guide you through this process, see Deploying your code.

Common problems with acsf-init

If you do not execute the acsf-init command after a Acquia Cloud Site Factory platform release, or execute it incorrectly, you may encounter one or more of the following errors:

Error Description
Verification failed: Verify that acsf-init has run If a hotfix fails, ensure that your user has permission to overwrite the settings.php file, and then execute the command as described in Updating the module.
The file settings.php is out of date
Command acsf-init needs a higher bootstrap level to run The acsf-init command was executed from a directory without Git checkout or write permissions. Execute the command from a directory with these permissions to resolve the problem.
Settings.php included in .gitignore If the acsf-init command fails, even when executed from the correct directory and by a user with correct permissions, verify that your website's settings.php is not included in your .gitignore file, which will cause acsf-init to fail. Remove settings.php from your .gitignore file to resolve the problem.

Contact supportStill need assistance? Contact Acquia Support