Skip to content
Snippets Groups Projects
Commit fc7b90a3 authored by justinfreeman (Agileware)'s avatar justinfreeman (Agileware) :star2:
Browse files

Merge branch 'drupal-consolidation' into 'master' 

Consolidate the Drupal 7, Drupal 9 page into a single Drupal page and re-organise Drupal content.

See merge request !46
parents 7bb92148 bb1e5f59
No related branches found
No related tags found
1 merge request!46Consolidate the Drupal 7, Drupal 9 page into a single Drupal page and re-organise Drupal content.
Hide whitespace changes
Inline Side-by-side
docs/drupal9/index.md → docs/drupal/index.md
+ 115
− 18
View file @ fc7b90a3
......@@ -2,19 +2,14 @@
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 targeted for December 2022 (as of August 2022), and the CiviCRM community anticipates providing support for it around the time of its release.
This guide covers standard installation of CiviCRM on an existing Drupal 9 site. It assumes that you previously completed these tasks:
This guide covers standard installation of CiviCRM on an existing Drupal site. Before starting, you must have completed these tasks:
1. Install Drupal 9, and...
1. [Review the CiviCRM requirements](../general/requirements.md)
1. [Installed Drupal](https://www.drupal.org/docs/installing-drupal) and...
1. [Reviewed the CiviCRM requirements](../general/requirements.md)
??? tldr "Alternative: Civibuild for developers"
## Get the code for Drupal 9 {:#drupal9-download}
If you plan to develop patches for CiviCRM on Drupal 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/).
<a name="downloading"></a><!-- old anchor -->
## Get the code {:#download}
Drupal 9 (D9) sites are typically administered with [Composer](https://www.getcomposer.org). Composer is a *dependency management* tool which can add, upgrade, and remove software *packages* for your site.
Drupal 9 sites are typically administered with [Composer](https://www.getcomposer.org). Composer is a *dependency management* tool which can add, upgrade, and remove software *packages* for your site.
CiviCRM is published as a suite of related packages. Our goal is to use Composer to add CiviCRM's packages to the D9 site.
......@@ -148,7 +143,7 @@ Optionally you can also require the [`cv`](https://github.com/civicrm/cv) comman
-->
## Get the translations {:#i18n}
### Get the translations for Drupal 9 {:#drupal9-i18n}
!!! warning "I18n & L10n on Drupal 9"
If installing with the GUI it is currently only possible to install CiviCRM in English (US) on Drupal 9. Adding the language files involves breaking with Composer best practices by writing the contents of the `civicrm-l10n` tarball into `vendor/civicrm/civicrm-core` or configuring the `civicrm.l10n` directory path after you install and placing the contents of the `civicrm-l10n` tarball into the configured directory.
......@@ -184,7 +179,7 @@ The warnings above notwithstanding to install CiviCRM on Drupal 9 requires the f
Now we move onto [Installing CiviCRM - Command line install](#installing-commandline)
<a name="installing"></a><a name="installing-gui"></a><a name="installing-commandline"></a>
## Run the installer {:#installer}
### Run the installer for Drupal 9 {:#drupal9-installer}
The installer verifies requirements, prepares the database, and initializes the configuration file. You may run the installer through the web interface (*which is simpler*) or the command-line interface (*which has more options*).
......@@ -217,6 +212,112 @@ The installer verifies requirements, prepares the database, and initializes the
CiviCRM has a command-line administration tool, `cv`, which can perform installation. For details, see [command-line installer](../general/cli-cv.md).
## Get the code for Drupal 7 {:#drupal7-download}
The [CiviCRM download page](https://civicrm.org/download) provides a pre-built archive for use with Drupal 7. A
typical archive file is ~20mb and looks like `civicrm-X.Y.Z-drupal.tar.gz`. It contains a folder named `civicrm/`.
In Drupal 7, there is a folder for storing add-on modules: `DRUPAL_ROOT/sites/all/modules`.
Our goal is to download the archive and extract into this folder. Here are a few example ways to download and extract:
??? example "Download via web-browser"
This method does not require shell access on the server. You may adapt based your server's arrangement.
* On the [CiviCRM download page](https://civicrm.org/download), click the link for CiviCRM / Drupal 7. Save the file locally.
* Extract the archive locally. For example, in a Linux workstation, one might say:
```bash
cd ~/Downloads
tar xvzf civicrm-X.Y.Z-drupal.tar.gz
```
* Observe the new folder `civicrm/`.
* Using your favor file-transfer system (SSH/SFTP, `rsync`, `git`, `mv`, etc), transfer the `civicrm/` folder
to `DRUPAL_ROOT/sites/all/modules`.
??? example "Download via curl + tar"
This method require shell access to the Drupal server.
* On the [CiviCRM download page](https://civicrm.org/download), note the current version.
* In the shell, navigate to the Drupal module folder (*adjust as appropriate*):
```bash
cd DRUPAL_ROOT/sites/all/modules
```
* In the shell, run the `curl` and `tar` commands. Adjust the version `X.Y.Z` to the appropriate value.
```bash
curl -L "https://download.civicrm.org/civicrm-X.Y.Z-drupal.tar.gz" | tar xvz
```
??? example "Download via Drupal web UI"
This is the easiest way for a new administrator. However, it may not work in all deployments or
all versions. For
example, if the Drupal server has a locked-down configuration, then it may encounter permission errors
or timeouts. The only way to find out is to try.
* On the [CiviCRM download page](https://civicrm.org/download), right-click the link for CiviCRM / Drupal 7. Copy the URL.
* Login to your Drupal site with *administrator* permissions.
* Navigate to **Modules >> Install new module**.
* Paste the URL
* Click "Install"
??? warning "This may not work with CiviCRM 5.13-5.30"
In CiviCRM versions 5.13 - 5.30, the prebuilt tarball included a symlink which is not accepted by
the Drupal 7 installer. This should work again in 5.31.
<!-- TODO: After 5.31 has been out for a while, we can move this option higher up and remove/downgrade the notice. -->
??? warning "The "Upload"/"Browse" option is unlikely to work."
The **Install new module** page provides another option for uploading the archive from your local computer.
In a default PHP configuration, the upload limits are too conservative to accept the CiviCRM archive.
In all cases, the final outcome should be the creation of a new folder
```
DRUPAL_ROOT/sites/all/modules/civicrm
```
### Get the translations for Drupal 7 {:#drupal7-i18n}
The basic CiviCRM release includes support for US English (`en_US`). To use another language or dialect, please [download and extract the translation files](../general/i18n_l10n.md).
### Run the installer for Drupal 7 {:#drupal7-installer}
The installer verifies requirements, prepares the database, and initializes the configuration file. You may run the installer through the web interface (*which is simpler*) or the command-line interface (*which has more options*).
??? example "Run installer via Drupal 7 web UI"
1. Enable the "CiviCRM" module
* Login to your Drupal site with *administrator* permissions.
* Navigate to the "Modules" page (`admin/modules`).
* Find "CiviCRM" and enable it.
* At the bottom, click "Save Configuration".
2. After enabling, the status message will display a link to "configure CiviCRM". Click it.
??? question "What if I didn't notice the link?"
Use the URL bar. Navigate to the `civicrm` page (e.g. `https://example.com/civicrm`).
3. The CiviCRM installer will open.
* *If there are unmet requirements*, the installer will list them. Consult the [Requirements](../general/requirements.md) documentation for additional advice.
* *If all the requirements are met*, proceed through the brief questionnaire.
* *If you have [a separate MySQL database for CiviCRM](../general/requirements.md#mysql-connection)*, then locate "Environment: CiviCRM Database". Click the edit icon and enter the [database URL](../general/requirements.md#mysql-connection).
* Finally, click "Install CiviCRM".
??? example "Run installer via the command-line"
CiviCRM has a command-line administration tool, `cv`, which can perform installation. For details, see [command-line installer](../general/cli-cv.md).
# Troubleshooting {:#troubleshooting}
* Review the [Troubleshooting](../general/troubleshooting.md) page for help with problems you may encounter during the installation.
# Post-installation {:#post-install}
Recommended steps to perform after installing CiviCRM on Drupal.
## Review the permissions {:#permissions}
!!! note ""
......@@ -339,13 +440,9 @@ See [TLS for MySQL](../general/mysql_tls.md) for introductory concepts and the s
__Webform CiviCRM module__
* [Project page on Drupal.org](https://www.drupal.org/project/webform_civicrm)
* [Documentation on CiviCRM.org](https://docs.civicrm.org/webform-civicrm/en/latest)
* [Webform project page on drupal.org](https://www.drupal.org/project/webform_civicrm)
* [Webform documentation on civicrm.org](https://docs.civicrm.org/webform-civicrm/en/latest)
__CiviCRM Entity module__
* [Project page on Drupal.org](https://www.drupal.org/project/civicrm_entity)
### Troubleshooting {:#troubleshooting}
* Review the [Troubleshooting](../general/troubleshooting.md) page for help with problems you may encounter during the installation.
docs/drupal7/index.md deleted 100644 → 0
+ 0
− 231
View file @ 7bb92148
???+ tldr "About this document"
This guide covers standard installation of CiviCRM on an existing Drupal 7 site. It assumes that you previously completed these tasks:
1. [Install Drupal 7](https://www.drupal.org/docs/7/install), and...
1. [Review the CiviCRM requirements](../general/requirements.md)
??? tldr "Alternative: Civibuild for developers"
If you plan to develop patches for CiviCRM on Drupal 7, then please use 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/).
<a name="directory"></a><!-- old anchor -->
## Get the code {:#download}
The [CiviCRM download page](https://civicrm.org/download) provides a pre-built archive for use with Drupal 7. A
typical archive file is ~20mb and looks like `civicrm-X.Y.Z-drupal.tar.gz`. It contains a folder named `civicrm/`.
In Drupal 7, there is a folder for storing add-on modules: `DRUPAL_ROOT/sites/all/modules`.
Our goal is to download the archive and extract into this folder. Here are a few example ways to download and extract:
??? example "Download via web-browser"
This method does not require shell access on the server. You may adapt based your server's arrangement.
* On the [CiviCRM download page](https://civicrm.org/download), click the link for CiviCRM / Drupal 7. Save the file locally.
* Extract the archive locally. For example, in a Linux workstation, one might say:
```bash
cd ~/Downloads
tar xvzf civicrm-X.Y.Z-drupal.tar.gz
```
* Observe the new folder `civicrm/`.
* Using your favor file-transfer system (SSH/SFTP, `rsync`, `git`, `mv`, etc), transfer the `civicrm/` folder
to `DRUPAL_ROOT/sites/all/modules`.
??? example "Download via curl + tar"
This method require shell access to the Drupal server.
* On the [CiviCRM download page](https://civicrm.org/download), note the current version.
* In the shell, navigate to the Drupal module folder (*adjust as appropriate*):
```bash
cd DRUPAL_ROOT/sites/all/modules
```
* In the shell, run the `curl` and `tar` commands. Adjust the version `X.Y.Z` to the appropriate value.
```bash
curl -L "https://download.civicrm.org/civicrm-X.Y.Z-drupal.tar.gz" | tar xvz
```
??? example "Download via Drupal web UI"
This is the easiest way for a new administrator. However, it may not work in all deployments or
all versions. For
example, if the Drupal server has a locked-down configuration, then it may encounter permission errors
or timeouts. The only way to find out is to try.
* On the [CiviCRM download page](https://civicrm.org/download), right-click the link for CiviCRM / Drupal 7. Copy the URL.
* Login to your Drupal site with *administrator* permissions.
* Navigate to **Modules >> Install new module**.
* Paste the URL
* Click "Install"
??? warning "This may not work with CiviCRM 5.13-5.30"
In CiviCRM versions 5.13 - 5.30, the prebuilt tarball included a symlink which is not accepted by
the Drupal 7 installer. This should work again in 5.31.
<!-- TODO: After 5.31 has been out for a while, we can move this option higher up and remove/downgrade the notice. -->
??? warning "The "Upload"/"Browse" option is unlikely to work."
The **Install new module** page provides another option for uploading the archive from your local computer.
In a default PHP configuration, the upload limits are too conservative to accept the CiviCRM archive.
In all cases, the final outcome should be the creation of a new folder
```
DRUPAL_ROOT/sites/all/modules/civicrm
```
## Get the translations {:#i18n}
The basic CiviCRM release includes support for US English (`en_US`). To use another language or dialect, please [download and extract the translation files](../general/i18n_l10n.md).
## Run the installer {:#installer}
The installer verifies requirements, prepares the database, and initializes the configuration file. You may run the installer through the web interface (*which is simpler*) or the command-line interface (*which has more options*).
??? example "Run installer via Drupal 7 web UI"
1. Enable the "CiviCRM" module
* Login to your Drupal site with *administrator* permissions.
* Navigate to the "Modules" page (`admin/modules`).
* Find "CiviCRM" and enable it.
* At the bottom, click "Save Configuration".
2. After enabling, the status message will display a link to "configure CiviCRM". Click it.
??? question "What if I didn't notice the link?"
Use the URL bar. Navigate to the `civicrm` page (e.g. `https://example.com/civicrm`).
3. The CiviCRM installer will open.
* *If there are unmet requirements*, the installer will list them. Consult the [Requirements](../general/requirements.md) documentation for additional advice.
* *If all the requirements are met*, proceed through the brief questionnaire.
* *If you have [a separate MySQL database for CiviCRM](../general/requirements.md#mysql-connection)*, then locate "Environment: CiviCRM Database". Click the edit icon and enter the [database URL](../general/requirements.md#mysql-connection).
* Finally, click "Install CiviCRM".
??? example "Run installer via the command-line"
CiviCRM has a command-line administration tool, `cv`, which can perform installation. For details, see [command-line installer](../general/cli-cv.md).
## Review the permissions {:#permissions}
!!! check ""
Note that Drupal tries to create the `/files/` directory (and make it writeable), but only when saving `admin/settings`. Same holds for `/temp` directory, and a `/uploads/` directory in the CiviCRM module root. On a brand-new Drupal install, this directory may be missing. Even on an existing installation, if file permissions are not set properly, the directory may be missing. If enabling the **CiviCRM** module generates errors regarding the files directory, you must create it (writeable) manually.
* Go to the CiviCRM dashboard to see the CiviCRM menus:
`https://example.org/civicrm` (or `https://example.org/index.php?q=civicrm` if you don't have Clean URLs enabled)
* Go to **Administer » User management » Permissions**
* Verify that the Roles that you want to have access to CiviCRM have the appropriate permissions checked. CiviCRM is installed with a number of fixed permissions (such as "edit contacts" and "administer CiviCRM").
<!-- markdownlint-disable MD046 -->
!!! tip "Permissions for the Anonymous Role"
Many sites want anonymous visitors to have access to certain CiviCRM functionality. These permissions are enabled during installation for the Anonymous role. You should review them and modify if needed based on your requirements:
* **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.
<!-- markdownlint-enable MD046 -->
## Synchronize the users {:#contacts-users}
Once installed, CiviCRM keeps your Drupal Users synchronized with corresponding CiviCRM contact records. The 'rule' is that there will be a matched contact record for each Drupal user record. Conversely, only contacts who are authenticated users of your site will have corresponding Drupal user records.
When CiviCRM is installed on top of an existing Drupal site, a special CiviCRM Administrative feature allows you to automatically create CiviCRM contacts for all existing Drupal users:
* Login to your Drupal site with an administrator-level login
* Click the **CiviCRM** link in the main navigation block
* If your Drupal site makes use of the `db_prefix` setting (in `settings.php`), in the top bar click **Administer » System Settings » CMS Database Integration** , and update the box for the Drupal Users Table Name so that it includes the prefix.
* Click **Administer** in the menu bar
* Click **Users and Permissions** from the drop-down menu, then select **Synchronize Users to Contacts**
## Review the checklist {:#checklist}
The **Configuration Checklist** provides a convenient way to work through the settings that need to be reviewed and configured for a new site. You can link to this checklist from the installation success page AND you can visit it at any time from **Administer** » **Administration Console** » **Configuration Checklist**.
## Test-drive CiviCRM {:#test-drive}
There should now be a **CiviCRM** link in your Drupal menu. Click that link and the CiviCRM Menu, Shortcuts, Search and New Individual Blocks should appear. You can now explore CiviCRM end-user features and begin configuring CiviCRM for your site/organization needs.
## Addenda
### TLS for MySQL
If your MySQL database is hosted on a different machine than your web server, or if your host requires it, you can use TLS to encrypt the connection between the database and the web server.
Full instructions on installing drupal are out of scope for this guide, but one method is to install into a test database first without MySQL encryption and then move the database to the live server and update settings.php to enable MySQL encryption.
See [TLS for MySQL](../general/mysql_tls.md) for introductory concepts and the settings for the CiviCRM database. For the Drupal database you have several options for updating settings.php:
1. The simplest, which doesn't require a client certificate, but doesn't verify the server certificate.
``` php
$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,
),
),
),
);
```
2. Verifies the server certificate, and doesn't require a client certificate.
!!! warning "Host name must match certificate name"
Note that the DATABASE SERVER certificate would have to have a CN (common name field) that matches exactly the `host` you are using in `$databases['default']['default']['host']`. So if the host is `db435.examplehost.com`, then that must be the name on the SERVER certificate.
``` php
'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',
),
```
3. Client certificate/key pair (not self-signed), and do not verify the server certificate.
``` php
'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',
),
```
4. Client certificate/key pair (could be self-signed), and verify the server certificate.
``` php
'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',
),
```
### Troubleshooting {:#troubleshooting}
* Review the [Troubleshooting](../general/troubleshooting.md) page for help with problems you may encounter during the installation.
* To check compatibility with other Drupal modules see: [Drupal modules incompatible with CiviCRM](https://docs.civicrm.org/sysadmin/en/latest/integration/drupal/incompatibilities/)
docs/general/cli-cv.md
+ 1
− 1
View file @ fc7b90a3
......@@ -6,7 +6,7 @@
1. Install a supported CMS
1. [Review the CiviCRM requirements](../general/requirements.md)
1. Download the CiviCRM code. (See "*Get the code*" for [Backdrop](../backdrop/index.md#download), [Drupal 7](../drupal7/index.md#download), [Drupal 9](../drupal9/index.md#download), or [WordPress](../wordpress/index.md#download)).
1. Download the CiviCRM code. (See "*Get the code*" for [Backdrop](../backdrop/index.md#download), [WordPress](../wordpress/index.md#download) or [Drupal](../drupal/index.md)).
??? tldr "Limitations"
......
docs/general/requirements.md
+ 1
− 3
View file @ fc7b90a3
......@@ -43,9 +43,7 @@ See the page on [choosing a CMS](../planning/cms.md) for more information about
### Drupal
* [Drupal 9](../drupal9/index.md)
* [Drupal 7](../drupal7/index.md)
* [Drupal 7 or Drupal 9](../drupal/index.md) is required.
### Joomla
......
docs/planning/cms.md
+ 1
− 1
View file @ fc7b90a3
......@@ -43,7 +43,7 @@ The core system is the same across all CMS options, but occasionally there are b
The size of the install base shown [on the CiviCRM Stats site](https://stats.civicrm.org/?tab=sites) also affects how well reported issues are and how quickly fixes are tested and merged. While trends are subject to change, as of 2019, Joomla shows the least growth and WordPress the most.
Therefore it may take a bit longer to identify/resolve bugs in the BackDrop, Drupal8, Joomla and WordPress integrations but automated testing on these platforms is being continually improved.
Therefore it may take a bit longer to identify/resolve bugs in the BackDrop, Drupal, Joomla and WordPress integrations but automated testing on these platforms is being continually improved.
The following chapters in this section go into more detail about what is offered for each CMS.
......
mkdocs.yml
+ 1
− 2
View file @ fc7b90a3
......@@ -28,8 +28,7 @@ markdown_extensions:
nav:
- Home: index.md
- Install CiviCRM on Backdrop: backdrop/index.md
- Install CiviCRM on Drupal 7: drupal7/index.md
- 'Install CiviCRM on Drupal 9': drupal9/index.md
- Install CiviCRM on Drupal: drupal/index.md
- Install CiviCRM on Joomla: joomla/index.md
- Install CiviCRM on WordPress: wordpress/index.md
- General:
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment