Information for: DEVELOPERS   PARTNERS

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 requiring Drupal 8, and others requiring Drupal 7, you must 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 you use the Acquia Lightning distribution, which supports the creation of multiple installation profiles within your custom Drupal distribution.

To ensure your websites using a custom distribution can communicate with Acquia Cloud Site Factory and the Site Factory Management Console, you must install the Acquia Connector module in 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 multisite features for governance and resource efficiency, the distribution of Drupal used by Acquia Cloud Site Factory is ultimately your responsibility. You must remember your Acquia Cloud Site Factory-hosted websites will have separate databases, content, and user account—they are all in a single multi-tenant application. When granting Drupal users elevated platform admin or site builder permissions, these permissions may include permission to run PHP code 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 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 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 users cannot inject PHP code using the user interface.

Installing your distribution

To install a Drupal 8 distribution in 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 website’s code repository to your local machine.

  2. On your local machine, delete all files and subdirectories in the docroot directory you cloned from Acquia Cloud Site Factory. When removing its contents, don’t 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 the previous 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 Acquia Lightning.

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

  4. Install the Acquia Cloud Site Factory Connector module to your codebase as described in Updating with the acsf-init command.

  5. Ensure 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 set the correct permissions on Unix-like operating systems, use a command like the following example:

    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 configuring Acquia BLT:

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

  2. Create a custom Acquia Lightning profile. If you do not use 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, edit the profile key to use the newly created custom profile based on the following example, replacing mycustomprofile with the name of your profile:

    project:
       machine_name: blted8
       prefix: BLT
       human_name: 'BLTed 8'
       profile:
          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 use 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 you want available to website builders when creating new websites.

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

Manually configuring your distribution

If you do not use 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
    

    Note

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

    The previous Drush command creates several directories, and then copies files 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 everything is in order before you commit the custom distribution to the repository:

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

    The command should return the following result:

    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 you want available to website builders when creating new websites.

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

Note

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

Using the Drupal distribution

After installing and configuring your new Drupal distribution, website builders can select the distribution for their use when creating new websites. For more information about selecting your custom profile when creating a new Acquia Cloud Site Factory website, see Managing installation profiles in your Factory.