Composer builds allow Remote Admin (RA) clients to efficiently include various scripts and patches, including post-update builds. Both Drupal 8 and Drupal 7 websites may be built using
composer.json, but Drupal 7 websites may have additional dependency requirements, as not all modules and distributions include proper Composer packages.
Acquia Automation will update websites that are based on Composer builds whose repositories conform to the proper architecture and include a fully-functioning
composer.json file that builds a Drupal website.
Remote Administration will provide updates in the scope of service — third-party vendor libraries and other scripts that may be included using the
composer.json file are not in the scope of RA support.
After Acquia Automation detects that security updates are required on the Production environment, it proceeds in the following fashion:
- Acquia Automation scans for the existence of a
composer.lockfile. If such a file exists, it will be scanned for the presence of Drupal. If Drupal is found, it proceeds as follows. Otherwise, it proceeds with the Drush update process.
- Acquia Automation runs
composer update drupal/modulename --with-dependenciesfor all modules that require a security update and which match the RA scope. This updates the modules and their dependencies. All modules are updated unless they are properly pinned to a minor version.
- Specified files and paths are preserved.
- Included patches are applied.
- Included scripts are run if initiated by a post-update command. Development and support of such scripts remains the responsibility of the client.
The following items are required for the website's basic architecture:
composer.jsonfile must be located at the repository root.
vendordirectory is located in the repository's root. This folder must be under version control, and the proper autoloading must be set up to redirect Drupal to the new vendor location (see Drupal Scaffold).
- All Drupal code is in the
- Composer update replaces the entire
coredirectory when performing updates. All non-Drupal files added to any directory must either be excluded using
drupal-scaffoldor able to be recreated through patches in
composer.json file is built from several components, and must meet the following requirements:
- Be placed at the top level of the repository. This file overrides the
- Include all code necessary to run the website.
- Be able to be installed without package conflicts.
The creation, maintenance, and resolution of any package conflicts in the
composer.json file is the responsibility of the client. Acquia can assist in troubleshooting according to normal Support scope.
Composer uses semantic versioning. The caret (
^ ) indicates all versions greater than what is specified, in the same major release. For example,
^8.2 indicates all Drupal core versions greater than 8.2, but less than 9.0.
The following sections explain the various sections of the
composer.json file. These requirements are based on a Drupal 8 build using
composer.json. Drupal 7 requirements are specified where they are known.
The following sections must be present in the
composer.json file in order to build a website.
Including the package itself:
- Composer installers
Composer Installers is required to install Drupal-specific packages to the correct
and the specified Drupal installer paths:
- Drupal scaffold
The following code ensures that the Drupal docroot structure is preserved during updates and allows the exclusion of files that may be customized (such as
.htaccess). Be sure that the
drupal-composer/drupal-scaffoldline is before the
drupal/coreline in the file.
- Drupal core and modules
composer.jsonfile must specify all required Drupal core, distributions and modules, unless a module is included as a dependency of another module or distribution.
or when a distribution such as Lightning includes core as a dependency:
The following sections are recommended additions to the
- Minimum Stability:
- Prefer Stable:
The following list of items are optional additions to the
composer.json file, and may be useful to your installation in some situations.
- Locking or pinning a module
RA automation runs
composer update drupal/modulename --with-dependencies, not
composer require. As a result, if a required item specifies the minor or patch version, RA automation will not update the module. This is equivalent to locking a module.
requirelocks the Token module to a specific version that cannot be updated by RA automation:
While the caret is used to specify all versions greater than the specified version, but not exceeding the next major version, locking requires the exact version number to be specified. For this reason, the caret is not used in this example.
Maintaining the locked status of modules is the responsibility of the client.
- Patching contributed code
Patches can be added and will be automatically run by Composer when they are required for a specified module. They may be added locally (ensure the directory exists) or linked remotely. If you have extensive patches, we recommend splitting them into core and module subdirectories. For detailed instructions, see cweagans/composer-patches instructions.
- Add patches
Patches can be specified in the
extrasection of the
composer.json. The patch can be local or remote.
"Friendly Ajax": "patches/core_patches/friendly-ajaxExpired-typeError_0.patch"
"simplesamlphp dependency should use next significant release operator.": "https://www.drupal.org/files/issues/2760995-2.patch"
- Ignore Patches
If your version of a module should not have a patch applied — for instance, a patch has been applied by a distribution — you can ignore the patch in the
"This patch has known conflicts with our Quick Edit integration": "https://www.drupal.org/files/issues/2664682-49.patch"
- Excluding modified files
If you have modified included files, or created non-Drupal folders or files in your docroot, you can exclude them using
- Adding custom library files
To add a library that is not added by a module-specific
composer.json, add the file or repository as a discrete package:
- Add as a package in the
- Add a
- Add as a package in the
Composer-based builds typically recommend that directories which will be built by Composer are not committed to the repository. Unless you are using the Acquia Cloud pipelines feature (which is not currently compatible with Remote Administration updates) you cannot build a branch on Acquia Cloud. As a result, you must commit all code required to run a Drupal website, including the following:
Be sure that the top-level
.gitignore file is not ignoring these folders.
Acquia RA provides an example
composer.json template that can be modified on a per-installation basis. You can copy this file, modify it for your application, and then commit it to your code repository above the docroot.