Information for: DEVELOPERS   PARTNERS   SUPPORT

Looking for something?

Building your Drupal distribution

Although Acquia maintains the core platform of 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 running different major versions of Drupal, and others requiring Drupal 7, you must manage them in separate Site Factory stacks. A single stack can only operate one major version of Drupal at a time. For more information, see Using Site Factory Stacks.

To ensure your websites using a custom distribution can communicate with 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 Site Factory, see Building your Drupal 7 distribution.

Planning for security with your custom Drupal distribution

Although Site Factory uses Drupal’s native multisite features for governance and resource efficiency, the distribution of Drupal used by Site Factory is ultimately your responsibility. You must remember your 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 9 or later distribution in your Site Factory codebase and prepare it for use:

  1. Add your SSH key to Cloud Platform, 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 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.

    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 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 9 or later distribution for use with your websites, you can either use BLT, or you can use a manual process.

Using BLT

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

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

  2. Create a profile using the Drupal Console. For more information about installation profiles, see Installation profiles on 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 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 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 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 applications running Drupal 9 or later 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 Site Factory website, see Managing installation profiles in your Factory.

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