Installing a Drupal distribution


  • The Remote Administration service is incompatible with the Drupal tarball installation process. However, Remote Administration is compatible with Drupal Composer-based sites.
  • Composer-based installs are recommended for real applications. For more information, see BLT.
  • The Cloud Platform user interface method is not currently available on Cloud Next infrastructure and should only be used for demo and trial applications on Cloud Classic infrastructure.

To install a Drupal distribution (or Drupal core), use one of the following methods:

A Drupal distribution is a custom edition of Drupal, tuned and extended with custom developed and contributed modules to enable desired features, such as Acquia CMS. You can install many of the best and most popular Drupal distributions on Cloud Platform. For a list, see Choosing a Drupal distribution.

Creating a Drupal website using Composer

Before creating a Drupal website on Cloud Platform, ensure that your development environment fulfills the following prerequisites:

To create a Drupal website on Cloud Platform through Composer:

  1. Clone your Acquia repository into a new folder, such as ProjectName, and create a new branch:

    git clone [email protected]:Sitename.git ProjectName
    cd ProjectName
    git checkout -b MyBranchName
  2. Create a composer.json and composer.lock:

    composer create-project --no-install drupal/recommended-project .


    Ensure that you include the dot at the end.

  3. Modify the composer.json file by replacing web with docroot. Use your preferred editor or run the following command:

    sed -i'.original' 's/web\//docroot\//g' composer.json
  4. Add as another repository to provide access to supplement and provide access to additional packages:

    composer config repositories.1 composer
  5. Configure the location and name of the vendor directory:

    composer config vendor-dir vendor
  6. Select your preferred installation type from the following options:

    • source
    • dist
    • auto
    composer config preferred-install dist
  7. Add the following useful projects:

    composer require drush/drush:^11.0 --no-update
    composer require drupal/stage_file_proxy --no-update
    composer require cweagans/composer-patches --no-update
  8. (Optional) Add the following in the section labeled extra in your composer.json file for future patches. For more information, see Patching with Composer.

    Include these lines if you need to add a patch to core or a module:

    "enable-patching": true,
    "patches": {
       "drupal/[module_name]": {
          "Note regarding the nature of the patch being applied": "[patch_name].patch"
  9. Configure Composer to continue if a patch fails:

    composer config extra.composer-exit-on-patch-failure false
  10. Add the following after the section labeled extra in your composer.json file. These scripts remove .git folders after each update to make sure git tracks all files:

    "scripts": {
       "post-install-cmd": [
          "find docroot vendor -name '.git' | xargs rm -rf",
          "find docroot vendor -name '.github' | xargs rm -rf"
       "post-update-cmd": [
          "find docroot vendor -name '.git' | xargs rm -rf",
          "find docroot vendor -name '.github' | xargs rm -rf"
  11. To install all dependencies, run the following command:

    composer install
  12. To add your database connection, copy default.settings.php to the settings.php file, and modify the settings.php file by following the instructions on the Acquia require line page:

    cp docroot/sites/default/default.settings.php docroot/sites/default/settings.php
  13. Add the following to your settings.php file for configuration management:

    $settings["config_sync_directory"] = $app_root . '/../config/' . basename($site_path);
  14. Add and commit your code:

    git add .
    git commit -m "Initial commit of new Drupal core site."
  15. Push your changes to the Acquia repository. To create a tracking branch on the remote repository, run the following command:

    git push --set-upstream origin MyBranchName
  16. Navigate to your Cloud Platform application and switch the code to your branch on your preferred testing environment.

You can access the site page and follow the Drupal installation steps.

Installing a new Drupal distribution through the Cloud Platform user interface

Acquia does not recommend installing a new Drupal distribution through the Cloud Platform user interface.

  1. Sign in to the Cloud Platform user interface and select the application and environment where you want to install Drupal. You cannot install Drupal in a Production environment.

  2. On the environment’s Overview page, click Install Drupal.

    Cloud Platform install Drupal button


    If Install Drupal is disabled for use, ensure that the following required items are in place for your environment:

    • The Code entity in the environment has a branch or trunk selected—you cannot install to a tag.
    • Live Dev mode must be disabled for your application. Live Dev expects Drupal installation attempts only from the command line.
  3. On the Install distribution page, locate the Drupal distribution that you want to install, and click Install. For multiple distributions, you can click Learn more to get more information about a distribution.

  4. To install a distribution that is not listed (for example, your organization may have its own Drupal distributions, or you may want to install another distribution from, click Install from URL. In the Install Drupal from URL dialog, enter the URL of the distribution.


    For Drupal 7, the URL of the distribution’s download file (must be in .tar.gz format). The URL of the distribution’s Drush .make file.

    Install another Drupal distribution

  5. In the Install Drupal from URL dialog, click Install.

Deploying a new Drupal distribution in an environment takes a few minutes. After the installation process completes, click the environment’s website URL to visit your Drupal website. This runs install.php to complete the Drupal installation. The Drupal install.php script opens in a new browser window. The script creates a standard Drupal database, sets up the administrator username and password, and configures other modules and features relevant to the Drupal distribution you chose.

Cloud Platform installing Drupal

To start modifying your code, make a local copy of the repository using the Git checkout command.

Installing a new Drupal distribution in a Cloud IDE

Cloud IDE also offers a convenient and opinionated way to install Drupal.

To install a Drupal distribution using a Cloud IDE:

  1. Launch your Cloud IDE. If you have not yet created a Cloud IDE, follow the instructions on Getting started with Cloud IDE.

  2. From the IDE Get Started page, click CREATE A NEW APPLICATION.

    Installing Drupal in IDE

    A terminal pane pops up and prompts you to install the Acquia Drupal recommended project or the Acquia Drupal minimal project.

  3. Select your target version by typing the number associated with your distribution selection in the terminal prompt and press Enter. Acquia CLI takes care of automatic installation of Drupal in Cloud IDE’s /home/ide/project directory.

    Install Drupal through ACLI

    After Drupal is installed, you can start developing or push from the IDE terminal to Cloud Platform with acli push:db and acli push:files. As a best practice, your codebase remains to be managed with Git.