Building your Drupal distribution

Although Acquia maintains the core platform of Acquia Cloud Site Factory, you have the freedom to develop your websites to meet your specific needs, including selecting a Drupal distribution to use for the websites on your platform.

If you have some websites that need to use Drupal 8, and others that need to use Drupal 7, you will need to manage them in separate Acquia Cloud Site Factory stacks. A single stack can use either Drupal 8 or Drupal 7, but not both. For more information, see Using Site Factory stacks.

For Drupal 8, Acquia recommends that you use the Lightning distribution, which allows you to 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 Connector module to your distribution’s code.

Drupal 7-based distribution instructions

For Drupal 7 installation and configuration instructions with Acquia Cloud Site Factory, see Building your Drupal 7 distribution.

Planning for security with your custom Drupal distribution

Although Acquia Cloud Site Factory uses Drupal’s native multi-site functionality for governance and resource efficiency, the distribution of Drupal used by Acquia Cloud Site Factory is ultimately your responsibility. It is important to remember that your Acquia Cloud Site Factory-hosted websites will have separate databases, content, and user account — which means they are all in a single multi-tenant application. When granting Drupal users elevated platform admin or site builder permissions, these permissions may include the ability to execute PHP using Drupal’s user interface, based on your configuration.

Acquia recommends the following security practices:

  • Grant elevated permissions only to trusted developers on your team.
  • When developing your distribution, ensure that the standard user experience does not require elevated permissions.
  • Never enable Drupal’s core PHP module.
  • Follow Drupal best practices for writing secure code.
  • Consider installing the Paranoia module, which provides additional safeguards against the injection of PHP code using Drupal’s user interface.
  • Periodically compare your list of installed modules against the Paranoia module, and perform additional tests against the modules not covered by the Paranoia module. Evaluating your installed modules can ensure that it is not possible to inject PHP code using the user interface.

Installing your distribution

To add a Drupal 8 distribution to your Acquia Cloud Site Factory codebase and prepare it for use, 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.

  2. On your local computer, delete all of the files and subdirectories contained in the docroot directory that you cloned from Acquia Cloud Site Factory. When 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

    Do not run this Git command after you have installed your Drupal distribution in the docroot directory.

  3. Move your custom Drupal distribution into the now empty docroot directory. For installation instructions for Lightning including using Acquia BLT, see Installing Lightning.

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

  4. Add the Acquia Cloud Site Factory Connector module to your codebase as described in Adding the Connector module to your codebase.

  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]

After installing your distribution, you must configure it for use.

Configuring your distribution

To configure your Drupal 8 distribution for use with your websites, you can either use Acquia BLT, or you can use a manual process.

Using Acquia BLT

To configure your distribution with Acquia BLT, perform the following steps as described in the Acquia BLT documentation after setting up Acquia BLT:

  1. From the project’s docroot directory, execute blt acsf:init.

  2. Create a custom Lightning profile. If you are not using Lightning, you can create a profile using the Drupal Console. For more information about installation profiles, see Installation profiles on Acquia Cloud Site Factory.

  3. Add acsf as a dependency for your profile.

  4. Edit the blt/project.yml file. In the project section, modify the profile key to use the newly created custom profile based on the following example, replacing mycustomprofile with the name of your profile:

       machine_name: blted8
       prefix: BLT
       human_name: 'BLTed 8'
          name: mycustomprofile
  5. Save your changes.

  6. Deploy to your Git repository with the blt deploy command, or through your continuous integration configuration.

  7. If you are using continuous integration, push your build artifact to your production or non-production environment.

  8. If your custom distribution includes more than one installation profile, enable any installation profiles that you want site builders to be able to select when creating new websites.

Your new custom Drupal distribution is now configured and available for use.

Manually configuring your distribution

If you are not using Acquia BLT to manage your distribution, complete the following steps to configure your new distribution:

  1. Configure your installation profiles to require the module using the appropriate instruction by adding 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

  2. Run the following Drush command from the docroot directory to initialize your custom distribution:

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


    This command does not bootstrap a Drupal website, so you must run it with the --include argument that points to acsf/acsf_init/acsf_init.

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

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

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

    The following results should be returned by the acsf-init-verify command:

    acsf-init required files ok

  4. Commit and push your custom distribution’s files to Acquia Cloud Site Factory.

  5. Update your Production environment with the custom distribution’s files that you just pushed.

  6. If your custom distribution includes more than one installation profile, enable any installation profiles that you want site builders to be able to select when creating new websites.

Your new custom Drupal distribution is now configured and available for use.


Single sign-on for Drupal 8 websites requires special configuration. For configuration information, see Setting up single sign-on for Drupal 8.

Using the Drupal distribution

Now that your new Drupal distribution is installed and configured, site builders can select the distribution for their use when create new websites. For information regarding how to select your custom profile when creating a new Acquia Cloud Site Factory website, see Managing installation profiles in your Factory.

Contact supportStill need assistance? Contact Acquia Support

Acquia: Think Ahead

53 State Street, 10th Floor
Boston, MA 02109
United States
Phone: 888-922-7842

Map: Google Maps
View other locations