index.md

CiviCRM follows the Drupal community's decisions around which versions of Drupal receive support. Drupal 8 is no longer supported, but Drupal 7 and Drupal 9 are supported. Drupal 10's release date is targetted for August 2022 (as of April 2022), and the CiviCRM community anticipate providing support for it around the time of its release.

This guide covers standard installation of CiviCRM on an existing Drupal 8 or 9 site. It assumes that you previously completed these tasks:

1. [Install Drupal 8 or 9](https://www.drupal.org/docs/8/install), and...
1. [Review the CiviCRM requirements](../general/requirements.md)
If you plan to develop patches for CiviCRM on Drupal 8 or 9, then please read the [Developer Guide](https://docs.civicrm.org/dev/en/latest) for information about [Buildkit](https://docs.civicrm.org/dev/en/latest/tools/buildkit/) and [civibuild](https://docs.civicrm.org/dev/en/latest/tools/civibuild/).
Composer requires shell access to the D8/D9 site. It defines a command `composer`.

Many D8/D9 sites are initialized via `composer`, which means that `composer` is already available.  This
can be confirmed in the shell by running `composer --version`:

```
$ composer --version
Composer version 1.10.13 2020-09-09 11:46:34
```

It is possible that your system does not have `composer` -- for example, if you used a tar-based installation of D8,
then you may never have needed `composer` before.

If `composer` is missing, then you must [download and install it](https://getcomposer.org/download/) first.
Additionally, you probably need to [set composer's memory limit](https://getcomposer.org/doc/articles/troubleshooting.md#memory-limit-errors)
high enough for D8/D9.

Once you have `composer`, you need to navigate to the composer-root. You can recognize it by the following:

* It has the files `composer.json` and `composer.lock`.
* It has a subfolder `vendor/`.
* It usually has a subfolder `web/` (the web-root); alternatively, it may *be* the web-root.

A typical file-hierarchy might look like:

```
/var/www/drupal.example.org/                Composer-root
/var/www/drupal.example.org/composer.json   Composer-configuration
/var/www/drupal.example.org/composer.lock   Composer-configuration
/var/www/drupal.example.org/web/            Web-root (usually)
/var/www/drupal.example.org/vendor/         Downloaded packages
```

To work with `composer` and D8/D9, you must open a shell and navigate to the composer-root, e.g.

```
cd /var/www/drupal.example.org
```

**Note:** Drupal 9 and CiviCRM combinations require use of Composer 2.x.x
cd /var/www/drupal.example.org
composer config extra.enable-patching true
composer config minimum-stability dev
composer require civicrm/civicrm-{core,packages,drupal-8}:'~5.42'
A handful of packages used by CiviCRM require extra patch-files.

This is possible with the popular [cweagans/composer-patches](https://github.com/cweagans/composer-patches)
plugin. However, you must [opt-in to enable it](https://github.com/cweagans/composer-patches#allowing-patches-to-be-applied-from-dependencies).
For any package in `composer`, there may be several available versions.  Some have an official, well-defined name
or number (e.g.  `v1.2.3`), and these are called "stable" versions.  Other versions have an interim name or number
(e.g. `v1.2.alpha1` or `dev-master`) indicating that additional testing is appropriate.

As a general rule, a new `composer` deployment will (and should) only use "stable" versions.  CiviCRM, too, is
generally built around "stable" dependencies.  However, in some exceptional cases, CiviCRM requires an interim
release of some libraries.

`composer.json` has two options which affect this: [minimum-stability](https://getcomposer.org/doc/04-schema.md#minimum-stability) sets an
absolute baseline, and [prefer-stable](https://getcomposer.org/doc/04-schema.md#prefer-stable) expresses a general preference.
Setting `minimum-stability` to `dev` enables to installation to proceed when there are exceptional cases. Setting
`prefer-stable` to `true` means that `composer` will use stable releases whenever it can.
When you first install or upgrade to CiviCRM 5.31+, `composer` will prompt for permission to run CiviCRM compilation tasks. We recommend that you select `[a]lways`.

If you wish to suppress the prompt, see [Composer Compile Plugin: Managing the root package (for site-builders)](https://github.com/civicrm/composer-compile-plugin/blob/master/doc/site-build.md).
| Package | Description |
| -- | -- |
| `civicrm/civicrm-core` | The primary CiviCRM codebase |
| `civicrm/civicrm-drupal-8` | The integration module for CiviCRM and D8/D9 |
| `civicrm/civicrm-packages` | A collection of third-party/legacy packages used by CiviCRM |
| `civicrm/civicrm-asset-plugin` | A tool which automatically copies JS+CSS assets from CiviCRM to D8's `web/` folder - required by `civicrm/civicrm-drupal-8`|
The primary CiviCRM packages (`civicrm-core`, `civicrm-drupal-8`, `civicrm-packages`) have *synchronized*
versions. If one package is installed with v5.35, then the others should also be v5.35.

The following expression references the three packages and applies the same version-constraint to each:

```
civicrm/civicrm-{core,packages,drupal-8}:'~5.42'
```

The expression `~5.42` is a version-constraint.  It means that composer will install *approximately* v`5.42`.  It may install a newer patch-release (e.g.  `5.42.1`) or a newer minor-release (e.g.  `5.43.0`).  However, it will avoid major-releases (e.g. `6.0.0`).

Many `composer` tutorials rely on `composer` to automatically choose package-versions.
This is not recommended for CiviCRM and Drupal 8/9. Instead, package versioning should be explicit to ensure that:

1. CiviCRM versions remain synchronized.
2. CiviCRM stable releases are preferred over developmental releases.

   <!-- honestly, that second thing is weird to me. If people get dev releases unintentionally, then they've
    probably misconfigured/misunderstood their `composer.json`.  but given how consultancies blend upstream/public
    pkgs and inhouse/private pkgs, and given how inhouse pkgs tend to have lax versioning, I can see how there'd
    be pressure on D8 site-builders to make the configuration promiscuous -->
You will also have to repeat these steps **every** time you upgrade CiviCRM.
wget https://download.civicrm.org/civicrm-5.35.0-l10n.tar.gz
tar -zxvf civicrm-5.35.0-l10n.tar.gz
cd civicrm/
cp -R l10n/ ../vendor/civicrm/civicrm-core/
cp -R sql/ ../vendor/civicrm/civicrm-core/
cd ..
rm -rf civicrm/
??? warning "Installation options are very limited"

    Currently there is no interactive installer for CiviCRM on Drupal 8/9, so the installer uses a firm set of defaults, e.g.

    * *English Language Data*: It only installs data for US English. It cannot install data for other languages.
    * *Shared Database*: It only uses the shared CMS database. It cannot use [a separate MySQL database for CiviCRM](../general/requirements.md#mysql-connection).
    * *No Sample Data*: It only installs an empty, baseline dataset. It cannot install sample data.

    If you need to configure any of these options, then use the command-line installer.

??? warning "Write permissions"
    It is critical that your web-server user is able to write to the `web/sites/default/` directory in order to create `civicrm.settings.php` and that you have an appropriate value for execution time(s) and memory limit(s) as any interruption to the installer can (and will) result in an unusable install and require remedial steps to correct or a full reinstall! By default on Drupal 8.8+ this directory path is not writable by default, before installing you should ensure you grant write access to your web server user. With, e.g: `sudo chmod u+w web/sites/default`.

    For multisite installations you'll also need to ensure your web server user has write access to additional sites e.g: `sudo chmod u+w web/sites/site2.example.org`.

1. Login to your Drupal site with *administrator* permissions.
2. Navigate to **Manage >> Extend** or point your web browser to the following URL:

    `https://example.org/admin/modules/`

3. Find "CiviCRM Core" and enable it (you can optionally enable "CiviCRM Theme" to set a theme just for CiviCRM.)
4. At the bottom, click "Install". (Note: This may take a few moments to execute.)
CiviCRM has a command-line administration tool, `cv`, which can perform installation. For details, see [command-line installer](../general/cli-cv.md).
* **access all custom data** : If you plan on collecting "custom" data from visitors in standalone forms or as they make a contribution - enable this permission.
* **access CiviMail subscribe/unsubscribe pages** : If you are planning on using CiviMail, enable this permission to allow anonymous users to subscribe and unsubscribe from mailing lists via the web.
* **access uploaded files** : If you plan on allowing visitors to upload or view photos or other files - enable this permission.
* **make online contributions** : If you plan on soliciting online contributions from visitors, enable this permission for the "anonymous" role.
* **profile listings and forms** : If you plan on collecting name and address or other information from visitors, enable this permission for the "anonymous" role.
* **view event info** and **register for events** : If you plan to use CiviEvent and want to allow un-authenticated visitors to view event information and register for events online - enable these permissions for the "anonymous" role.
* **view event participants** : Enable this permission to allow anonymous users to access participant listing pages for events.
$databases = array (
  'default' =>
  array (
    'default' =>
    array (
      'database' => 'drupal',
      'username' => 'dbuser',
      'password' => 'dbpassword',
      'host' => 'db435.examplehost.com',
      'port' => '',
      'driver' => 'mysql',
      'prefix' => '',
      'pdo' => array(
          PDO::MYSQL_ATTR_SSL_CA => TRUE,
          PDO::MYSQL_ATTR_SSL_VERIFY_SERVER_CERT => FALSE,
      ),
    ),
  ),
);
'pdo' => array(
    // A certificate authority bundle.
    // If you are using a self-signed server certificate in a development
    // or testing environment, then this would be the same as the server
    // certificate.
    PDO::MYSQL_ATTR_SSL_CA => '/path/to/ca.crt',
),
'pdo' => array(
    PDO::MYSQL_ATTR_SSL_VERIFY_SERVER_CERT => FALSE,
    PDO::MYSQL_ATTR_SSL_KEY => '/path/to/your.key',
    PDO::MYSQL_ATTR_SSL_CERT => '/path/to/your.crt',
),
'pdo' => array(
    // The SSL_CA can be the same as your.crt if self-signed, but note
    // that it would also have to be a certificate authority for the
    // server certificate. Self-signed would only be for local
    // development testing.
    PDO::MYSQL_ATTR_SSL_CA => '/path/to/ca.crt',
    PDO::MYSQL_ATTR_SSL_KEY => '/path/to/your.key',
    PDO::MYSQL_ATTR_SSL_CERT => '/path/to/your.crt',
),