Skip to content
Snippets Groups Projects

Compare revisions

Changes are shown as if the source revision was being merged into the target revision. Learn more about comparing revisions.

Source

Select target project
No results found

Target

Select target project
  • AllenShaw/installation
  • documentation/docs/installation
  • DaveD/installation
  • seamuslee/installation
  • mattwire/installation
  • KarinG/installation
  • totten/installation
  • codebymikey/installation
  • luke.stewart/installation
  • wmortada/installation
  • ayduns/installation
  • justinfreeman/installation
  • planetwebb/installation
  • ginkgomzd/installation
  • marsh/installation
  • kcristiano/installation
  • yookoala/installation
  • JoeMurray/installation
  • fkohrt/installation
  • branham01/installation
  • iain/installation
  • Chabadrichmond/installation
  • dvhirst/installation
  • ufundo/installation
  • pwndf/installation
  • florian-dieckmann/installation
  • jebba/installation
  • resga/installation
28 results
Show changes
Commits on Source (233)
133 additional commits have been omitted to prevent performance issues.
Hide whitespace changes
Inline Side-by-side
Showing
with 1659 additions and 1069 deletions
.gitattributes 0 → 100644
View file @ 45f46fb1
*.md text eol=lf
docs/backdrop/index.md
View file @ 45f46fb1
## Scope of this guide and alternative installation methods
This guide covers standard installation of CiviCRM for production use. For installing a development environment, refer to the [section on Buildkit in the Developer Documentation](https://docs.civicrm.org/dev/en/latest/tools/buildkit/).
## Before installing
1. Ensure that your system meets the [requirements](../general/requirements.md).
1. Install Backdrop by referring to the [Backdrop Installation Guide](https://backdropcms.org/installation) if needed.
## Determine Backdrop Database Settings {:#db-settings}
You will need to know the database settings for your Backdrop installation prior to running the CiviCRM installer. You can look up these values in your Backdrop `settings.php` file (located in your Backdrop root) be looking for the following code:
``` php
$db_url = 'mysql://dbuser:dbpassword@localhost/backdrop';
```
or
``` php
$databases['default']['default'] = array(
'driver' => 'mysql',
'database' => 'database_name',
'username' => 'dbuser',
'password' => 'dbpassword',
'host' => 'localhost',
);
```
In the above example:
| Setting | Value |
| ------- | ----- |
| Database Server | localhost |
| Backdrop Database Name | backdrop |
| Database User Name | dbuser |
| Database User Password | dbpassword |
## Tell Backdrop where to find the CiviCRM Module {:#directory}
First, download CiviCRM and install the files like you would any other module:
* As administrator in Backdrop, go to Modules, click on **Install New Module**. Click **Manual Installation**, then **Install from a URL**. Fill in the URL of the module (see below). You will need to enable the **Project Installer** module in the backdrop modules page to see the **Install New Module** link.
* Alternatively, you can upload and extract the file in `<BACKDROP ROOT>/modules`
The result will be that the CiviCRM directory will be at `<BACKDROP ROOT>/modules/civicrm`
The most up-to-date version of CiviCRM will always be available from the [CiviCRM website](https://civicrm.org/download).
**Do NOT** proceed to "activate" the module - that will happen automatically when you run the installer.
## Install localization files (only for sites in a language other than US English) {:#i18n}
If using CiviCRM in another language than English, see the [internationalisation and localisation](../general/i18n_l10n.md) page about how to install files for running CiviCRM in other languages.
## Run the Installer {:#installer}
The installer will verify that you've downloaded the correct version of CiviCRM, and will check your server environment to make sure it meets CiviCRM requirements. It will then create and populate a database for CiviCRM as well as create your CiviCRM settings file (civicrm.settings.php).
* Login to your Backdrop site with Administrator level permissions.
* Point your web browser to the following URL:
`https://example.org/modules/civicrm/install/index.php?civicrm_install_type=backdrop`
* You should see the **CiviCRM Installer** screen.
* Initially, you will see a red bar with the message "These database details don't appear to be correct." This is expected as you haven't entered your database settings yet.
* If you see other errors, check the **Requirements** details at the bottom of the page for more information. You will need to correct any issues before continuing.
* Fill in the CiviCRM Database Settings.
!!! tip "Where Should I Store CiviCRM Data?"
CiviCRM may be configured to use your existing Backdrop database, or a separate (new) database. Using a separate database is generally preferred - as it makes backups and upgrades easier. The installer will create a new database for CiviCRM automatically if you enter a database name that doesn't already exist on your database server AND the database user you enter has permission to create databases. In case the installer does not automatically create a new database, simply create a new one following the same process as creating a new database for Backdrop. Note that if you plan to use the Backdrop Views module to display CiviCRM data within your Backdrop pages, and if you are going to use separate databases for Backdrop and CiviCRM, you need to ensure that your Backdrop database user has `SELECT` permissions for your CiviCRM database.
* Fill in the Backdrop Database Settings for your existing Backdrop database (as noted [above](#db-settings)).
!!! check "Loading Sample Data"
The Installer includes an option to load a set of sample contact, group, and relationship data by default. Sample data can provide a useful head-start in learning to use CiviCRM. However, if you do NOT want the sample data to be loaded, just uncheck **Load sample data** under **Other Settings**.
* Select the appropriate language for the base installation. You will be able to add other languages after the installation for multi-lingual sites.
* Click the **Check Requirements and Install CiviCRM** button.
* The installer will configure your databases, create the settings file and redirect you to your Backdrop Home page.
* If you still see a red bar with the message "These database details don't appear to be correct." - check the Database Details section below your settings for specific errors and problems. Once you correct these problems, click "Recheck requirements" to verify your settings before continuing.
* If you are on a Windows machine and get the message:
> "The user account used by your web-server needs to be granted write access to the following directory in order to configure the CiviCRM settings file: `C:<BACKDROP ROOT>/`"
even after changing directory permission in Explorer, see [the permissions page](../general/permissions.md) for instructions on how to set permissions on Linux, MacOS and Windows.
* Once you see the green "You're ready to install!" message - you can click **Check Requirements and Install CiviCRM**
## Review Permissions {:#permissions}
!!! check ""
Note that Backdrop 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 Backdrop 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 **Administer » Configuration » User accounts » 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 -->
## Create CiviCRM Contacts for Existing Backdrop Users {:#contacts-users}
Once installed, CiviCRM keeps your Backdrop Users synchronized with corresponding CiviCRM contact records. The 'rule' is that there will be a matched contact record for each Backdrop user record. Conversely, only contacts who are authenticated users of your site will have corresponding Backdrop user records.
When CiviCRM is installed on top of an existing Backdrop site, a special CiviCRM Administrative feature allows you to automatically create CiviCRM contacts for all existing Backdrop users:
* Login to your Backdrop site with an administrator-level login
* Click the **CiviCRM** link in the main navigation block
* If your Backdrop site makes use of the `db_prefix` setting (in `settings.php`), in de top bar click **Administer » System Settings » CMS Database Integration** , and update the box for the Backdrop 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 Configuration 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 Backdrop 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.
## Using Encryption with 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/) 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',
),
```
## Trouble-shooting Resources {:#troubleshooting}
* Review the [Troubleshooting](../general/troubleshooting.md) page for help with problems you may encounter during the installation.
???+ tldr "About this document"
This guide covers standard installation of CiviCRM on an existing Backdrop site. It assumes that you previously completed these tasks:
1. [Install Backdrop](https://backdropcms.org/installation), and...
1. [Review the CiviCRM requirements](../general/requirements.md)
???+ tldr "Migrating from Drupal 7"?
If you are migrating to Backdrop from Drupal 7, see [Switch from Drupal to Backdrop](https://docs.civicrm.org/sysadmin/en/latest/misc/switching-cms/drupal-to-backdrop/) in the [System Administrator Guide](https://docs.civicrm.org/sysadmin/en/latest).
??? tldr "Alternative: Civibuild for developers"
If you plan to develop patches for CiviCRM on Backdrop, 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="directory"></a><!-- old anchor -->
## Get the code {:#download}
The [CiviCRM download page](https://civicrm.org/download) provides a pre-built archive for use with Backdrop. A
typical archive file is ~20mb and looks like `civicrm-X.Y.Z-backdrop.tar.gz`. It contains a folder named `civicrm/`.
In Backdrop, there is a folder for storing add-on modules: `BACKDROP_ROOT/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 / Backdrop. 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-backdrop.tar.gz
```
* Observe the new folder `civicrm/`.
* Using your favor file-transfer system (SSH/SFTP, `rsync`, `git`, `mv`, etc), transfer the `civicrm/` folder
to `BACKDROP_ROOT/modules`.
??? example "Download via curl + tar"
This method require shell access to the Backdrop server.
* On the [CiviCRM download page](https://civicrm.org/download), note the current version.
* In the shell, navigate to the Backdrop module folder (*adjust as appropriate*):
```bash
cd BACKDROP_ROOT/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-backdrop.tar.gz" | tar xvz
```
??? example "Download via Backdrop web UI"
This is the easiest way for a new administrator. However, it may not work in all deployments. For
example, if the Backdrop 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 / Backdrop. Copy the URL.
* Login to your Backdrop site with *administrator* permissions.
* Navigate to **Functionality >> Install new modules**.
* In the right hand bar, choose **Manual installation >> Install from a URL**.
* 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 Backdrop 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
```
BACKDROP_ROOT/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 Backdrop web UI"
1. Enable the "CiviCRM" module
* Login to your Backdrop site with *administrator* permissions.
* Navigate to the "Functionality" 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 command-line"
CiviCRM has a command-line administration tool, `cv`, which can perform installation. For details, see [command-line installer](../general/cli-cv.md).
The installer will verify that you've downloaded the correct version of CiviCRM, and will check your server environment to make sure it meets CiviCRM requirements. It will then create and populate a database for CiviCRM as well as create your CiviCRM settings file (civicrm.settings.php).
## Review the permissions {:#permissions}
!!! check ""
Note that Backdrop 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 Backdrop 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 **Administer » Configuration » User accounts » 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 Backdrop Users synchronized with corresponding CiviCRM contact records. The 'rule' is that there will be a matched contact record for each Backdrop user record. Conversely, only contacts who are authenticated users of your site will have corresponding Backdrop user records.
When CiviCRM is installed on top of an existing Backdrop site, a special CiviCRM Administrative feature allows you to automatically create CiviCRM contacts for all existing Backdrop users:
* Login to your Backdrop site with an administrator-level login
* Click the **CiviCRM** link in the main navigation block
* If your Backdrop site makes use of the `db_prefix` setting (in `settings.php`), in de top bar click **Administer » System Settings » CMS Database Integration** , and update the box for the Backdrop 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 Backdrop 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 Backdrop 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 Backdrop 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' => 'backdrop',
'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.
docs/drupal9/index.md → docs/drupal/index.md
View file @ 45f46fb1
!!! warning "Experimental documentation"
???+ tldr "About this document"
This document discusses a new deployment environment. It is closesly based on the Drupal 8
document, but it has not been carefully reviewed/tested. Consequently, it is not linked in
the main menu.
CiviCRM follows the Drupal community's decisions around which versions of Drupal receive support. Drupal 8 and 9 are no longer supported, but Drupal 7 until Jan 5, 2025 and Drupal 10 are supported.
## Scope of this guide and alternative installation methods
This guide covers standard installation of CiviCRM on an existing Drupal site. Before starting, you must have completed these tasks:
This guide covers standard installation of CiviCRM for production use. For installing a development environment, refer to the [section on Buildkit in the Developer Documentation](https://docs.civicrm.org/dev/en/latest/tools/buildkit/).
1. [Installed Drupal](https://www.drupal.org/docs/installing-drupal) and...
1. [Reviewed the CiviCRM requirements](../general/requirements.md)
## Before installing
## Get the code for Drupal 10 {:#drupal10-download}
1. Ensure that your system meets the [requirements](../general/requirements.md).
1. Install Drupal 9 by referring to the [Drupal 8 Installation Guide](https://www.drupal.org/docs/8/install) if needed.
Drupal 10 sites are typically administered with [Composer](https://getcomposer.org). Composer is a *dependency management* tool which can add, upgrade and remove software *packages* for your site.
!!! warning "Composer install required!"
This guide will assume that you have installed Drupal 9 using composer. At this time manual installation of Drupal 8 using zip or tarball install methods is not supported.
If `composer` is properly installed, then these example commands will add latest CiviCRM version to D10:
## Downloading CiviCRM on Drupal 9 with Composer {:#downloading}
```
cd /var/www/d10.example.org
composer config extra.enable-patching true
composer require civicrm/civicrm-{core,packages,drupal-8}
composer require civicrm/cli-tools
```
To download CiviCRM on a Drupal 9 site we'll need to ask [Composer](https://www.getcomposer.org) to `require` the CiviCRM libraries. We do this by requiring the `civicrm-core`, `civicrm-drupal-8`, `civicrm-packages` and `civicrm-asset-plugin` libraries.
??? info "More detail: Enable patching"
<!-- markdownlint-disable MD046 -->
!!! tip "Versions!"
It is **strongly** recommended that you provide a version when requiring these libraries, as such our example command below will include, as an example, the version `5.27.2`. Note that installing ESR versions onto CiviCRM has not been tested at this time and as such no instructions for doing so are provided.
A handful of packages used by CiviCRM require extra patch-files.
Note that that Drupal 9 installation has only been confirmed to work from 5.28.0 onwards.
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).
Failure to provide a version will most likely result in you installing the `dev-master` version which is bleeding-edge code and may result in an unstable site/setup!
### Install CiviCRM without any translations {#drupal10-installation}
!!! tip "Composer running out of memory?"
You may need to [increase composer's memory limit](https://getcomposer.org/doc/articles/troubleshooting.md#memory-limit-errors) in order to avoid out of memory errors.
To install CiviCRM without any translations we use the command line tool `cv` and we assume you already have an empty database.
Best practice is to use `composer require` locally or in dev/test and then deploy your `composer.lock` to staging and use `composer install` which requires less memory and implements the changes you've tested and committed to your repo!
<!-- markdownlint-enable MD046 -->
Change the following in the command below:
* `https://d10.example.org` change this to your civicrm url
* `database_user` change this to your database user
* `database_pass` change this to the password of your database user
* `civicrm_database` change this to name of your civicrm database
```
cv core:install --cms-base-url="https://d10.example.org" --db="mysql://database_user:database_pass@localhost:3306/civicrm_database"
```
### Install a translated CiviCRM {:#drupal10-i18n}
To install a translated CiviCRM on Drupal 10 requires an additional step to download the translation files.
Change the following in the command below:
* `nl_NL` to your language, e.g. fr_FR, or nl_BE etc...
* `https://d10.example.org` change this to your civicrm url
* `database_user` change this to your database user
* `database_pass` change this to the password of your database user
* `civicrm_database` change this to name of your civicrm database
```
mkdir -p web/sites/default/files/civicrm/l10n/nl_NL/LC_MESSAGES
curl -Lss -o web/sites/default/files/civicrm/l10n/nl_NL/LC_MESSAGES/civicrm.mo https://download.civicrm.org/civicrm-l10n-core/mo/nl_NL/civicrm.mo
export CIVICRM_L10N_BASEDIR=/var/www/d10.example.org/web/sites/default/files/civicrm/l10n
cv core:install --cms-base-url="https://d10.example.org" --db="mysql://database_user:database_pass@localhost:3306/civicrm_database" --lang="nl_NL"
```
## Get the code for Drupal 9 {:#drupal9-download}
!!! warning "Drupal 9 reaches end of life status soon"
If you start implementing a new CiviCRM environment you might want to start with Drupal 10 or a different [CMS](../planning/cms.md). Check out Drupal 9 [end of life status](https://www.drupal.org/docs/understanding-drupal/drupal-9-release-date-and-what-it-means/how-long-will-drupal-9-be-supported)
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.
If you do not work regularly with D9+Composer, then you should take a refresher before installing CiviCRM.
??? example "Quick and dirty introduction to D9 with `composer`"
Composer requires shell access to the D9 site. It defines a command `composer`.
Many 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 D9,
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 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.
<!-- For D9, do we still need the caveats about web-root? Are we sure everyone on D9 has web/? -->
A typical file-hierarchy might look like:
```
/var/www/d9.example.org/ Composer-root
/var/www/d9.example.org/composer.json Composer-configuration
/var/www/d9.example.org/composer.lock Composer-configuration
/var/www/d9.example.org/web/ Web-root (usually)
/var/www/d9.example.org/vendor/ Downloaded packages
```
To work with `composer` and D9, you must open a shell and navigate to the composer-root, e.g.
```
cd /var/www/d9.example.org
```
If `composer` is properly installed, then these example commands will add CiviCRM to D9:
```
cd /var/www/d9.example.org
composer config extra.enable-patching true
composer config minimum-stability dev
composer require civicrm/civicrm-{core,packages,drupal-8}:'~5.42'
composer civicrm:publish
```
You should adjust the example path (`/var/www/d9.example.org`) and the example version (`~5.42`) as needed.
!!! warning "Install CiviCRM before Drush"
You should install CiviCRM packages before installing Drush to avoid dependency issues with `symfony/finder` or `symfony/filesystem`. If you've already got Drush installed and want to install CiviCRM remove Drush first.
```bash
composer remove drush/drush
composer require civicrm/civicrm-{core,packages,drupal-8}
composer require drush/drush
```
If you'd like more details to understand these commands or common errors, then please drill-down below.
??? info "More detail: Enable patching"
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).
??? info "More detail: Package stability"
### Expert Mode - Just the command
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.
To require the CiviCRM libraries on a Drupal 9 site you can use the following one-line command:
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.
??? note "Enabling Patching for composer libraries"
You should make sure that before running this line that you either modify the composer.json file to include the parameter `"enable-patching": true` in the extra section or run `composer config 'extra.enable-patching' true` as per the [composer-patches documentation](https://github.com/cweagans/composer-patches#allowing-patches-to-be-applied-from-dependencies). This isn't necessary immediately but from CiviCRM 5.30 it will be required for CiviCRM to function correctly.
`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.
* `composer require civicrm/civicrm-asset-plugin:'~1.0.0' civicrm/civicrm-{core,packages,drupal-8}:'~5.28'`
??? info "More detail: Compilation tasks"
### Guided Mode - More context and information
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`.
!!! tip "Location, Location... Location"
You should always run `composer` commands from the top-level folder above the web and vendor folders, where in the same place as your `composer.json` file.
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).
??? note "Enabling Patching for composer libraries"
You should start by ensuring that patching is enabled for dependencies by altering composer.json and adding `"enable-patching": true` in the extra section or run `composer config 'extra.enable-patching' true` as per the [composer-patches documentation](https://github.com/cweagans/composer-patches#allowing-patches-to-be-applied-from-dependencies). This isn't necessary immediately but from CiviCRM 5.30 it will be required for CiviCRM to function correctly.
??? info "More detail: Required packages"
You can also install CiviCRM by running these commands separately, this is what that looks like, along with a brief explanation of what each step is doing:
| 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 D9's `web/` folder. Required by civicrm/civicrm-drupal-8 |
1. Require the CiviCRM composer asset plugin which helps build a predictable structure for your CiviCRM codebase: `composer require civicrm/civicrm-asset-plugin:'~1.0.0'`
1. Require the CiviCRM core code: `composer require civicrm/civicrm-core:'~5.28'`
1. Require the CiviCRM third-party packages library: `composer require civicrm/civicrm-packages:'~5.28'`
1. Require the CiviCRM Drupal 9 integration code: `composer require civicrm/civicrm-drupal8:'~5.28'`
??? info "More detail: Version constraints"
The primary CiviCRM packages (`civicrm-core`, `civicrm-drupal-8`, `civicrm-packages`) have *synchronized*
versions. If one package is installed with v5.30.1, then the others should also be v5.30.1.
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/D9. 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 D9 site-builders to make the configuration promiscuous -->
<!--
Optionally you can also require the [`cv`](https://github.com/civicrm/cv) command-line helper/interface for CiviCRM with:
......@@ -65,7 +209,9 @@ Optionally you can also require the [`cv`](https://github.com/civicrm/cv) comman
* `composer require civicrm/cv` - This will place the cv binary in `./vendor/bin/cv` relative to your `composer.json` file.
## Install localization files (for sites needing languages other than US-English) {:#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.
......@@ -75,9 +221,9 @@ Optionally you can also require the [`cv`](https://github.com/civicrm/cv) comman
You will also have to repeat these steps **every** time you upgrade CiviCRM.
The warnings above notwithstanding to install CiviCRM on Drupal 9 requires the following additional steps to prepare:
The warnings above notwithstanding to install CiviCRM with i18n on Drupal 9 requires the following additional steps to prepare:
1. Add [`cv`](https://github.com/civicrm/cv) to your Drupal 9 Site with: `composer require civicrm/cv` (**composer installs of cv are currently broken** for now use the [manual install steps](https://github.com/civicrm/cv#download).)
1. Add [`cv`](https://github.com/civicrm/cv) to your Drupal 9 Site with: `composer require civicrm/cv`.
1. Grab the localisation (*l10n*) files and unpack the `l10n` and `sql` subfolders into `vendor/civicrm/civicrm-core/`
* You'll find the l10n files on the [CiviCRM Download](https://civicrm.org/download) page or from `https://download.civicrm.org/civicrm-VERSION-l10n.tar.gz` where `VERSION` is a recent version of CiviCRM.
......@@ -100,58 +246,147 @@ The warnings above notwithstanding to install CiviCRM on Drupal 9 requires the f
Now we move onto [Installing CiviCRM - Command line install](#installing-commandline)
## Installing CiviCRM {:#installing}
<a name="installing"></a><a name="installing-gui"></a><a name="installing-commandline"></a>
### Run the installer for Drupal 9 {:#drupal9-installer}
### GUI install {:#installing-gui}
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*).
<!-- markdownlint-disable MD046 -->
!!! 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 9.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`.
??? example "Run installer via Drupal 9 web UI"
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`.
<!-- markdownlint-enable MD046 -->
??? warning "Installation options are very limited"
* Login to your Drupal site with Administrator level permissions.
* Proceed to **Manage >> Extend** or point your web browser to the following URL:
Currently there is no interactive installer for CiviCRM on Drupal 9, so the installer uses a firm set of defaults, e.g.
`https://example.org/admin/modules/`
* *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.
* Currently there is no interactive installer for CiviCRM on Drupal 9 and enabling the module in Drupal 8 will install CiviCRM into your existing Drupal 8 database.
If you need to configure any of these options, then use the command-line installer.
!!! tip "Where Should I Store CiviCRM Data?"
[GUI installs](#installing-gui) of CiviCRM on Drupal 9 can only install into your existing Drupal 8 database. However using a separate database is generally preferred - as it makes backups and upgrades easier. If you want to install via the GUI **and** use a separate CiviCRM database you'd need to create the CiviCRM database manually and move the `civicrm_` tables into the new CiviCRM database, then update `civicrm.settings.php` with the new database details. If you want to install directly into a separate database see the [command line install](#installing-commandline) instructions.
??? 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 9 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`.
### Command line install {:installing-commandline}
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`.
<!-- markdownlint-disable MD046 -->
!!! note "Prerequisites"
The steps below assume that you have the prerequisites for a command line install, namely cv or some other tested command-line installer for Drupal 9 (**Hint:** There's only one of those at the moment and it's cv)
1. Login to your Drupal site with *administrator* permissions.
2. Navigate to **Manage >> Extend** or point your web browser to the following URL:
!!! 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 9.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`.
`https://example.org/admin/modules/`
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`.
<!-- markdownlint-enable MD046 -->
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.)
Make sure you're in the root directory for your Drupal 9 / CiviCRM site (the same folder/directory that holds `composer.json`).
??? example "Run installer via command-line"
The essence of a cv install command looks like this `cv core:install -vv --cms-base-url="https://urltocms.example.org" --db="mysql://database:details@go/here:3306" --lang="en_GB"` there are many parameters available. <!-- META:To-Do Document cv usage -->
CiviCRM has a command-line administration tool, `cv`, which can perform installation. For details, see [command-line installer](../general/cli-cv.md).
For our CiviCRM install on Drupal 9 we want a command that looks like this:
## 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
<!-- markdownlint-disable MD046 -->
``` bash
cv core:install -vv --db="DATABASE" --cms-base-url="URL" --lang="LANG"
```
<!-- markdownlint-enable MD046 -->
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*).
Replace `cv` with the path to the cv phar on your system if applicable. The parts in `CAPS` above will need to be replaced with your site-specific information as follows:
??? example "Run installer via Drupal 7 web UI"
* `DATABASE` (required) is the [DSN](https://en.wikipedia.org/wiki/Data_source_name) for the database where you want CiviCRM installed.
* `URL` (required) is the canonical URL to the root of your CMS site.
* `LANG` (optional) is one of the supported languages for CiviCRM - it **must** exist in your `l10n` folder.
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.
## Review Permissions {:#permissions}
??? 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 ""
Drupal will 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.
......@@ -176,7 +411,7 @@ Replace `cv` with the path to the cv phar on your system if applicable. The part
* **view event participants** : Enable this permission to allow anonymous users to access participant listing pages for events.
<!-- markdownlint-enable MD046 -->
## Create CiviCRM Contacts for Existing Drupal Users {:#contacts-users}
## 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.
......@@ -188,7 +423,7 @@ When CiviCRM is installed on top of an existing Drupal site, a special CiviCRM A
* Click **Administer** in the menu bar
* Click **Users and Permissions** from the drop-down menu, then select **Synchronize Users to Contacts**
## Review the Configuration Checklist {:#checklist}
## 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**.
......@@ -196,13 +431,15 @@ The **Configuration Checklist** provides a convenient way to work through the se
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.
## Using Encryption with MySQL
## 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/) for introductory concepts and the settings for the CiviCRM database. For the Drupal database you have several options for updating settings.php:
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.
......@@ -267,17 +504,13 @@ See [TLS for MySQL](/general/mysql_tls/) for introductory concepts and the setti
),
```
## D8 <-> CiviCRM Integration modules {:#integration-modules}
### Integration modules {:#integration-modules}
### Webform CiviCRM module
__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
__CiviCRM Entity module__
* [Project page on Drupal.org](https://www.drupal.org/project/civicrm_entity)
## Troubleshooting Resources {:#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
View file @ 45583ad5
## Scope of this guide and alternative installation methods
This guide covers standard installation of CiviCRM for production use. For installing a development environment, refer to the [section on Buildkit in the Developer Documentation](https://docs.civicrm.org/dev/en/latest/tools/buildkit/).
## Before installing
1. Ensure that your system meets the [requirements](../general/requirements.md).
1. Install Drupal 7 by referring to the [Drupal 7 Installation Guide](https://www.drupal.org/docs/7/install) if needed.
## Determine Drupal Database Settings {:#db-settings}
You will need to know the database settings for your Drupal installation prior to running the CiviCRM installer: You can look up these values in your Drupal `settings.php` file (located by default in your `<drupal_root>/sites/default directory`) be looking for the following code:
```php
$databases = array (
'default' =>
array (
'default' =>
array (
'database' => 'drupal',
'username' => 'dbuser',
'password' => 'dbpassword',
'host' => 'localhost',
'port' => '',
'driver' => 'mysql',
'prefix' => '',
),
),
);
```
In the above example:
| Setting | Value |
| ---------------------- | ---------- |
| Database Server | localhost |
| Drupal Database Name | drupal |
| Database User Name | dbuser |
| Database User Password | dbpassword |
## Tell Drupal where to find the CiviCRM Module {:#directory}
First, download CiviCRM and install the files like you would any other module:
* As administrator in Drupal, go to Modules, click on **Install New Module** , and it will ask you to fill in the URL of the module. It will then fetch it and install it for you. You will need to enable the **Update Manager** module in the Drupal modules page to see the **Install New Module** link.
* Alternatively, you can upload and extract the file in `<DRUPAL ROOT>/sites/all/modules`
The result will be that the CiviCRM directory will be at `<DRUPAL ROOT>/sites/all/modules/civicrm`
The most up-to-date version of CiviCRM is always available from the [CiviCRM website](https://civicrm.org/download)
**Do NOT** activate the module yet - that will happen automatically when you run the installer.
## Install localization files (only for non-English sites) {:#i18n}
If using CiviCRM in another language than English, see the [internationalisation and localisation](../general/i18n_l10n.md) page about how to install files for running CiviCRM in other languages.
## Run the Installer {:#installer}
The installer will verify that you've downloaded the correct version of CiviCRM, and will check your server environment to make sure it meets CiviCRM requirements. It will then create and populate a database for CiviCRM as well as create your CiviCRM settings file (civicrm.settings.php).
* Login to your Drupal site with Administrator level permissions.
* Point your web browser to the following URL:
`https://example.org/sites/all/modules/civicrm/install/index.php`
* You should see the **CiviCRM Installer** screen.
* Initially, you will see a red bar with the message "These database details don't appear to be correct." This is expected as you haven't entered your database settings yet.
* If you see other errors, check the **Requirements** details at the bottom of the page for more information. You will need to correct any issues before continuing.
* Fill in the CiviCRM Database Settings.
!!! tip "Where Should I Store CiviCRM Data?"
CiviCRM may be configured to use your existing Drupal database, or a separate (new) database. Using a separate database is generally preferred - as it makes backups and upgrades easier. The installer will create a new database for CiviCRM automatically if you enter a database name that doesn't already exist on your database server AND the database user you enter has permission to create databases. In case the installer does not automatically create a new database, simply create a new one following the same process as creating a new database for Drupal. Note that if you plan to use the Drupal Views module to display CiviCRM data within your Drupal pages, and if you are going to use separate databases for Drupal and CiviCRM, you need to ensure that your Drupal database user has `SELECT` permissions for your CiviCRM database.
* Fill in the Drupal Database Settings for your existing Drupal database (as noted [above](#db-settings)).
!!! check "Loading Sample Data"
The Installer includes an option to load a set of sample contact, group, and relationship data by default. Sample data can provide a useful head-start in learning to use CiviCRM. However, if you do NOT want the sample data to be loaded, just uncheck **Load sample data** under **Other Settings**.
* Select the appropriate language for the base installation. You will be able to add other languages after the installation for multi-lingual sites.
* Click the **Check Requirements and Install CiviCRM** button.
* The installer will configure your databases, create the settings file and redirect you to your Drupal Home page.
* If you still see a red bar with the message "These database details don't appear to be correct." - check the Database Details section below your settings for specific errors and problems. Once you correct these problems, click "Recheck requirements" to verify your settings before continuing.
* If you are on a Windows machine and get the message:
> "The user account used by your web-server needs to be granted write access to the following directory in order to configure the CiviCRM settings file: `C:<DRUPAL ROOT>/sites/default/`"
even after changing directory permission in Explorer, see [the permissions page](../general/permissions.md) for instructions on how to set permissions on Linux, MacOS and Windows.
* Once you see the green "You're ready to install!" message - you can click **Check Requirements and Install CiviCRM**
## Review 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 -->
## Create CiviCRM Contacts for Existing Drupal 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 Configuration 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.
## Using Encryption with 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/) 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',
),
```
## Trouble-shooting Resources {:#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/drupal8/index.md deleted 100644 → 0
View file @ 45583ad5
## Scope of this guide and alternative installation methods
This guide covers standard installation of CiviCRM for production use. For installing a development environment, refer to the [section on Buildkit in the Developer Documentation](https://docs.civicrm.org/dev/en/latest/tools/buildkit/).
## Before installing
1. Ensure that your system meets the [requirements](../general/requirements.md).
1. Install Drupal 8 by referring to the [Drupal 8 Installation Guide](https://www.drupal.org/docs/8/install) if needed.
!!! warning "Composer install required!"
This guide will assume that you have installed Drupal 8 using composer. At this time manual installation of Drupal 8 using zip or tarball install methods is not supported.
## Downloading CiviCRM on Drupal 8 with Composer {:#downloading}
To download CiviCRM on a Drupal 8 site we'll need to ask [Composer](https://www.getcomposer.org) to `require` the CiviCRM libraries. We do this by requiring the `civicrm-core`, `civicrm-drupal-8`, `civicrm-packages` and `civicrm-asset-plugin` libraries.
<!-- markdownlint-disable MD046 -->
!!! tip "Versions!"
It is **strongly** recommended that you provide a version when requiring these libraries, as such our example command below will include, as an example, the version `5.27.2`. Note that installing ESR versions onto CiviCRM has not been tested at this time and as such no instructions for doing so are provided.
Failure to provide a version will most likely result in you installing the `dev-master` version which is bleeding-edge code and may result in an unstable site/setup!
!!! tip "Composer running out of memory?"
You may need to [increase composer's memory limit](https://getcomposer.org/doc/articles/troubleshooting.md#memory-limit-errors) in order to avoid out of memory errors.
Best practice is to use `composer require` locally or in dev/test and then deploy your `composer.lock` to staging and use `composer install` which requires less memory and implements the changes you've tested and committed to your repo!
<!-- markdownlint-enable MD046 -->
### Expert Mode - Just the command
To require the CiviCRM libraries on a Drupal 8 site you can use the following one-line command:
??? note "Enabling Patching for composer libraries"
You should make sure that before running this line that you either modify the composer.json file to include the parameter `"enable-patching": true` in the extra section or run `composer config 'extra.enable-patching' true` as per the [composer-patches documentation](https://github.com/cweagans/composer-patches#allowing-patches-to-be-applied-from-dependencies). This isn't necessary immediately but from CiviCRM 5.30 it will be required for CiviCRM to function correctly.
* `composer require civicrm/civicrm-asset-plugin:'~1.0.0' civicrm/civicrm-{core,packages,drupal-8}:'~5.28'`
### Guided Mode - More context and information
!!! tip "Location, Location... Location"
You should always run `composer` commands from the top-level folder above the web and vendor folders, where in the same place as your `composer.json` file.
??? note "Enabling Patching for composer libraries"
You should start by ensuring that patching is enabled for dependencies by altering composer.json and adding `"enable-patching": true` in the extra section or run `composer config 'extra.enable-patching' true` as per the [composer-patches documentation](https://github.com/cweagans/composer-patches#allowing-patches-to-be-applied-from-dependencies). This isn't necessary immediately but from CiviCRM 5.30 it will be required for CiviCRM to function correctly.
You can also install CiviCRM by running these commands separately, this is what that looks like, along with a brief explanation of what each step is doing:
1. Require the CiviCRM composer asset plugin which helps build a predictable structure for your CiviCRM codebase: `composer require civicrm/civicrm-asset-plugin:'~1.0.0'`
1. Require the CiviCRM core code: `composer require civicrm/civicrm-core:'~5.28'`
1. Require the CiviCRM third-party packages library: `composer require civicrm/civicrm-packages:'~5.28'`
1. Require the CiviCRM Drupal 8 integration code: `composer require civicrm/civicrm-drupal8:'~5.28'`
!!! note "pear/exception conflict"
If you get an error message from composer when trying to install CiviCRM that there is a conflict in requirements for the package pear/exception. Then run the following command: `composer require pear/exception 1.0.1 as 1.0.0` before trying to run the command in step 3 above.
Optionally you can also require the [`cv`](https://github.com/civicrm/cv) command-line helper/interface for CiviCRM with:
!!! note ""
**Composer installs of cv are currently broken** for now use the [manual install steps](https://github.com/civicrm/cv#download).
* `composer require civicrm/cv` - This will place the cv binary in `./vendor/bin/cv` relative to your `composer.json` file.
## Install localization files (for sites needing languages other than US-English) {:#i18n}
!!! warning "I18n & L10n on Drupal 8"
If installing with the GUI it is currently only possible to install CiviCRM in English (US) on Drupal 8. 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.
!!! error "Here Be Dragons..."
The following steps are provided as an example - they are not supported or widely tested and may leave your site in a broken state. You use them at your own risk. No. Seriously...
You will also have to repeat these steps **every** time you upgrade CiviCRM.
The warnings above notwithstanding to install CiviCRM on Drupal 8 requires the following additional steps to prepare:
1. Add [`cv`](https://github.com/civicrm/cv) to your Drupal 8 Site with: `composer require civicrm/cv` (**composer installs of cv are currently broken** for now use the [manual install steps](https://github.com/civicrm/cv#download).)
1. Grab the localisation (*l10n*) files and unpack the `l10n` and `sql` subfolders into `vendor/civicrm/civicrm-core/`
* You'll find the l10n files on the [CiviCRM Download](https://civicrm.org/download) page or from `https://download.civicrm.org/civicrm-VERSION-l10n.tar.gz` where `VERSION` is a recent version of CiviCRM.
**Example:**
<!-- markdownlint-disable MD046 -->
``` bash
wget https://download.civicrm.org/civicrm-5.27.2-l10n.tar.gz
tar -zxvf civicrm-5.27.2-l10n.tar.gz
cd civicrm/
cp -R l10n/ ../vendor/civicrm/civicrm-core/
cp -R sql/ ../vendor/civicrm/civicrm-core/
cd ..
rm -rf civicrm/
```
<!-- markdownlint-enable MD046 -->
1. If you've done this correctly, you should end up with `vendor/civicrm/civicrm-core/l10n` and `vendor/civicrm/civicrm-core/sql/`
* You can remove any languages you don't need by deleting them before copying the `l10n` and `sql` folders.
Now we move onto [Installing CiviCRM - Command line install](#installing-commandline)
## Installing CiviCRM {:#installing}
### GUI install {:#installing-gui}
<!-- markdownlint-disable MD046 -->
!!! 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`.
<!-- markdownlint-enable MD046 -->
* Login to your Drupal site with Administrator level permissions.
* Proceed to **Manage >> Extend** or point your web browser to the following URL:
`https://example.org/admin/modules/`
* Currently there is no interactive installer for CiviCRM on Drupal 8 and enabling the module in Drupal 8 will install CiviCRM into your existing Drupal 8 database.
!!! tip "Where Should I Store CiviCRM Data?"
[GUI installs](#installing-gui) of CiviCRM on Drupal 8 can only install into your existing Drupal 8 database. However using a separate database is generally preferred - as it makes backups and upgrades easier. If you want to install via the GUI **and** use a separate CiviCRM database you'd need to create the CiviCRM database manually and move the `civicrm_` tables into the new CiviCRM database, then update `civicrm.settings.php` with the new database details. If you want to install directly into a separate database see the [command line install](#installing-commandline) instructions.
### Command line install {:installing-commandline}
<!-- markdownlint-disable MD046 -->
!!! note "Prerequisites"
The steps below assume that you have the prerequisites for a command line install, namely cv or some other tested command-line installer for Drupal 8 (**Hint:** There's only one of those at the moment and it's cv)
!!! 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`.
<!-- markdownlint-enable MD046 -->
Make sure you're in the root directory for your Drupal 8 / CiviCRM site (the same folder/directory that holds `composer.json`).
The essence of a cv install command looks like this `cv core:install -vv --cms-base-url="https://urltocms.example.org" --db="mysql://database:details@go/here:3306" --lang="en_GB"` there are many parameters available. <!-- META:To-Do Document cv usage -->
For our CiviCRM install on Drupal 8 we want a command that looks like this:
<!-- markdownlint-disable MD046 -->
``` bash
cv core:install -vv --db="DATABASE" --cms-base-url="URL" --lang="LANG"
```
<!-- markdownlint-enable MD046 -->
Replace `cv` with the path to the cv phar on your system if applicable. The parts in `CAPS` above will need to be replaced with your site-specific information as follows:
* `DATABASE` (required) is the [DSN](https://en.wikipedia.org/wiki/Data_source_name) for the database where you want CiviCRM installed.
* `URL` (required) is the canonical URL to the root of your CMS site.
* `LANG` (optional) is one of the supported languages for CiviCRM - it **must** exist in your `l10n` folder.
## Review Permissions {:#permissions}
!!! note ""
Drupal will 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 -->
## Create CiviCRM Contacts for Existing Drupal 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 Configuration 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.
## Using Encryption with 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/) 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',
),
```
## D8 <-> CiviCRM Integration modules {:#integration-modules}
### 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)
### CiviCRM Entity module
* [Project page on Drupal.org](https://www.drupal.org/project/civicrm_entity)
## Troubleshooting Resources {:#troubleshooting}
* Review the [Troubleshooting](../general/troubleshooting.md) page for help with problems you may encounter during the installation.
docs/general/cli-cv.md 0 → 100644
View file @ 45f46fb1
<!-- markdownlint-disable MD046 -->
???+ tldr "About this document"
This guide covers installation of CiviCRM on the command-line. It assumes that you previously completed these tasks:
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), [WordPress](../wordpress/index.md#download) or [Drupal](../drupal/index.md)).
??? tldr "Limitations"
At time of writing, the CLI installer is primarily tested with Backdrop, Drupal 7/8/9, and WordPress. It is primarily tested with
single-site deployments. For other configurations (e.g. Joomla; e.g. multisite), it may require extra variables/options/patches.
<!-- markdownlint-enable MD046 -->
The installer verifies requirements, prepares the database, and initializes the configuration file.
Each Civi-CMS integration has an option to install through the web interface -- which is intended for new and casual administrators.
For more advanced administrators, there is a general-purpose command-line interface (CLI) for installation. This is useful for:
* Automating installation
* Accessing uncommon or hidden options
* Debugging or developing changes to the installer
??? tip "Debugging and development"
If you are using the CLI for debugging or development, then the __CiviCRM Developer Guide__ has additional guidance.
See [Setup Reference: Overview](https://docs.civicrm.org/dev/en/latest/framework/setup/) and
[Setup Reference: Getting Started](https://docs.civicrm.org/dev/en/latest/framework/setup/getting-started/)
## Download "cv"
The CLI installer is part of [cv](https://github.com/civicrm/cv), a general-purpose tool for managing CiviCRM on the command-line. `cv` is
distributed in PHAR format, which is a portable executable file for PHP. It should run in most Unix-like environments that support PHP.
Simply download [cv.phar](https://download.civicrm.org/cv/cv.phar) and put it somewhere in the `PATH`. For example:
```bash
sudo curl -LsS https://download.civicrm.org/cv/cv.phar -o /usr/local/bin/cv
sudo chmod +x /usr/local/bin/cv
```
## Change directory
To run `cv`, you should navigate into the base folder of the CMS. For example:
```bash
cd /var/www/example.org
```
## Run the installer
A typical installation command will look like this:
```bash
cv core:install --cms-base-url="URL" --lang="LANG"
```
For example:
```
$ cv core:install --cms-base-url="https://example.org" --lang="fr_CA"
Found code for civicrm-core in /var/www/example.org/wp-content/plugins/civicrm/civicrm
Found code for civicrm-setup in /var/www/example.org/wp-content/plugins/civicrm/civicrm/setup
Creating file /var/www/example.org/wp-content/uploads/civicrm/civicrm.settings.php
Creating civicrm_* database tables in hydrawpcms_p7urq
```
There are several available options for the installer. Expand the topics below for more details.
<!-- FIXME: Options for multisite ... -->
??? info "Option: CMS Base URL"
```
cv core:install ... --cms-base-url="https://example.org"
```
The "CMS Base URL" is the public URL of the website. It is required for most CLI installations.
Setting this option ensures that CiviCRM's background jobs (e.g. email-blasts and membership-reminders)
can generate correct URLs.
??? info "Option: Database URL"
```
cv core:install ... --db="mysql://user:pass@hostname:port/db"
```
The "Database URL" points to the MySQL database where we will install CiviCRM.
By default, CiviCRM will use the same database as the CMS. However, some administrators prefer to use a separate database.
See [Requirements: MySQL: Connection](../general/requirements.md#mysql-connection) for more discussion.
??? info "Option: Language"
```
cv core:install ... --lang=fr_CA
```
The "Language" is the primary language used by the organization.
Based on the language, the installer loads a set of *default configuration data*. This includes common activity types ("Meeting" or
"Phone Call"), common location types ("Home" or "Office"), and so on.
__Note__: For a specific language to work, there *must* be corresponding data in the `l10n` folder.
??? info "Option: Sample data"
```
cv core:install ... -m loadGenerated=1
```
The sample data provides a number of fake, auto-generated records -- i.e. sample contacts, contributions, activities, etc. The sample
data is useful for testing or reviewing CiviCRM.
__Note__: At time of writing, the sample data is only supported in the default locale, `en_US`.
??? info "Option: Admin User (Standalone)"
```
cv core:install ... -m extras.adminUser=USERNAME \
-m extras.adminPass=SECRET \
-m extras.adminEmail=ME@EXAMPLE.COM
```
When installing CiviCRM Standalone, you should specify the credentials for the first administrative user.
If omitted, the credentials will be auto-generated and stored in the CiviCRM log.
??? info "Option: Verbose output"
```bash
## Verbose
cv core:install ... -v
## Very verbose
cv core:install ... -vv
```
The "verbose" option provides more details about how the installer works. Enabling the verbose option helps one identify problems.
The installer may report a problem. Some common ones are:
??? warning "Problem: CMS Base URL"
On most systems, the `--cms-base-url` cannot be detected automatically. You must explicitly set it.
??? warning "Problem: File write permission"
The installer needs to create some files and folders. However, if the parent folder is locked-down, then you will need to relax permissions.
For example: in a Drupal site, the installer creates a file `web/sites/<sitename>/civicrm.settings.php`. You may need to mark
the parent folder (`web/sites/default` or `web/sites/example.org`) as writeable, e.g.:
```bash
## Grant write-access for the owner-user
chmod 755 web/sites/default
## Grant write-access for all users
chmod 777 web/sites/default
```
??? warning "Problem: PHP or MySQL configuration"
The PHP or MySQL configuration may require an update - e.g. to expand the PHP memory limit, to enable a PHP extension, or to enlarge a MySQL buffer.
Common issues are discussed in the [Requirements](requirements.md).
??? "Error: Call to undefined method Drupal::entityManager"
This error appears installing with the `--user` option under Drupal 9. Avoid this error simply by not using the `--user` option.
For common problems, you can simply fix the problem and re-run the installer.
For unusual problems, be sure to enable verbose output (`-v` or `-vv`). It may also help to [inspect the model, plugins, or requirements](https://docs.civicrm.org/dev/en/latest/framework/setup/getting-started/).
## Configure the site
After running `core:install`, you can login to the CMS, open CiviCRM, and configure additional details. The [System Administrator
Guide](https://docs.civicrm.org/sysadmin/en/latest/) has more advice on how to configure CiviCRM.
If you are automating the installation, then you may wish to automate some common configuration steps, such as:
??? info "Task: Manage extensions"
To view available extensions:
```bash
cv ext:list
```
To download extensions from the [Extension Directory](https://civicrm.org/extensions/):
```bash
cv dl EXTENSION_1 EXTENSION_2 ...
```
By default, it downloads stable releases. To download pre-releases (alphas/betas), use dev feed or an explicit URL:
```bash
## Download from the "dev" feed
cv dl --dev EXTENSION_1 EXTENSION_2 ...
## Download from an explicit URL
cv dl EXTESION_KEY@ZIP_URL
```
Alternatively, if you downloaded an extension by other means, then you may enable it:
```bash
cv en EXTENSION_1 EXTENSION_2 ...
```
??? info "Task: Manage settings"
Many options are managed through the [Settings](https://docs.civicrm.org/dev/en/latest/framework/setting/) framework.
These may be configured in the CLI:
```bash
## List current settings
cv api setting.get
## Update specific settings
cv api setting.create KEY_1=VALUE_1 KEY_2=VALUE_2 ...
```
??? info "Task: Clear caches"
```bash
cv flush
```
<!--
??? example "Example: Install Mosaico and Shoreditch"
Here's an example bringing the pieces together:
```
cv dl --dev mosaico shoreditch
cv api setting.create theme_backend=shoreditch
```
-->
docs/general/i18n_l10n.md
View file @ 45f46fb1
## Coming Soon
!!! note ""
This page is a placeholder for content being migrated in from the old Wiki.
## Using CivCRM in a language other than US-English
CiviCRM uses US English by default but supports translation into a wide range of other languages with varying degrees of completeness.
!!! note ""
If you want to help out with translations visit the [translation documentation](https://lab.civicrm.org/dev/translation/wikis).
To enable use of CiviCRM in a new language translation you need to
* download the translation files
* install them in the appropriate directory
* select the language in the Language settings
The exact instructions on how to download and install the translations files differ between platforms:
* [Backdrop](../backdrop/index.md#i18n)
* [Drupal 9](../drupal/index.md#drupal9-i18n)
* [Drupal 7](../drupal/index.md#drupal7-i18n)
* [Joomla](../joomla/index.md#i18n)
* [Wordpress](../wordpress/index.md#i18n)
## Changing the default CiviCRM language after installation
Once you have installed the translation files, you can change the language used by CiviCRM:
* Go to **Administer > Localization > Languages, Currency, Location**
* Select the new default language.
* Update the default currency, money formatting options, default country, etc.
You will also probably want to update the date and time formats:
* Go to **Administer > Localization > Date Formats**
Finally, you may notice that many other options in CiviCRM will not be correctly translated:
* Individual prefixes (Mrs, M, etc)
* Gender options (M, F, other)
* Address Location Types
* Some fieldsets in the "Edit Contact" screen
These are known in CiviCRM as Option Values, and there are many of these.
To avoid having to change every single setting, you can install the following extension: [fixoptiontranslations](https://lab.civicrm.org/extensions/fixoptiontranslations). Once the extension is enabled, all options will be translated. The extension can then be uninstalled and removed.
## Updating translation files
The easiest way to update your translations regularly is to use the [l10n update](https://github.com/cividesk/com.cividesk.l10n.update/) extension:
The "l10n update" extension will do a daily check to update the translation files for CiviCRM core, as well as for extensions. Every night, around 2 AM (North American Eastern Time), the CiviCRM website packages updated translation files. These are available at the following address: `https://download.civicrm.org/civicrm-l10n-core/mo/xx_XX/civicrm.mo` where `xx_XX` is an ISO language code corresponding to one CiviCRM has published translations for.
For example, for Spanish CiviCRM core:
```sh
wget https://download.civicrm.org/civicrm-l10n-core/mo/es_ES/civicrm.mo
```
For the CDN Tax Receipts extension in Canadian French:
```sh
wget https://download.civicrm.org/civicrm-l10n-extensions/mo/cdntaxreceipts/fr_CA/cdntaxreceipts.mo
```
## Storing translation files in another directory
By default, CiviCRM looks in `[civicrm.root]/l10n` for translation files. Since CiviCRM 5.23, there is a new setting available to store those files in another directory. This can be convenient when files are updated regularly, or when using the l10nupdate extension, which requires the files to be web-writable. More information, see [PR15408](https://github.com/civicrm/civicrm-core/pull/15408). As of this writing, this setting only applies to core translations, not extensions.
## Native gettext
`gettext` is the mechanism by which strings are translated. By default, CiviCRM uses the PHP-Gettext implementation. This implementation can cause a 20-30% performance loss.
Since CiviCRM 4.2, it is possible to use native `gettext`. This may require some changes to your hosting environment and is therefore recommended mainly for sites hosted on dedicated environments (VPS or dedicated server, it may not work on shared hosting).
To enable it:
* PHP must have `gettext` support compiled in (it usually is the case, see `phpinfo()` for more information). Debian and Ubuntu include it by default.
* The operating system must have the locale enabled. For example, on Linux-based systems, this is in `/etc/locale.gen`, or by typing this command:
```sh
locale -a
```
Debian/Ubuntu systems can enable locales by typing:
```sh
dpkg-reconfigure locales
```
!!! note
The "UTF-8" variant of the locale must be enabled. For example: "fr_FR.UTF-8".
Apache or PHP-FPM must be restarted after adding a new locale. Finally, uncomment the following in civicrm.settings.php:
```php
define('CIVICRM_GETTEXT_NATIVE', 1);
```
docs/general/permissions.md
View file @ 45f46fb1
## Coming Soon
!!! note ""
This page is a placeholder for content being created to help configure filesystem permissions for CiviCRM.
## Coming Soon
!!! note ""
This page is a placeholder for content being created to help configure filesystem permissions for CiviCRM.
docs/general/requirements.md
View file @ 45f46fb1
# Installation Requirements
Ensure that your system meets the following requirements before installing or upgrading CiviCRM.
If you are curious what technologies other organizations are using to run CiviCRM, you can look at the [CiviCRM Stats](https://stats.civicrm.org/?tab=technology).
## Server Environment {:#server}
### Operating System {:#os}
If your server meets all of the requirements described on this page, CiviCRM *should* function correctly. There are no explicit operating system requirements. However, it's worth noting that CiviCRM is far more widely deployed and tested on UNIX-based operating systems, in particular Linux (e.g. Ubuntu, Debian, etc.), than with Microsoft Windows. You can still use CiviCRM fine from Windows desktops when the hosting environment runs Linux.
### Hosting
In general, CiviCRM is a demanding web application which requires substantial server resources. It may not perform well on all hosting platforms. Learn more about [choosing your hosting platform](../planning/hosting.md).
## CMS {:#cms}
A CMS, or Content Management System, is a type of application which controls and manages the content of a website. CiviCRM must be installed within one of these compatible CMS platforms.
See the page on [choosing a CMS](../planning/cms.md) for more information about the advantages and disadvantages of each compatible CMS platform.
### Backdrop
* [Backdrop](../backdrop/index.md) 1.0 or newer is required.
### Drupal
* [Drupal 8](../drupal8/index.md)
* [Drupal 7](../drupal7/index.md)
### Joomla
* [Joomla](../joomla/index.md) 3.x.x is required.
### WordPress
* [WordPress](../wordpress/index.md) 4.9 or newer is required.
## PHP {:#php}
### PHP Version on the Command Line
The PHP version used on the command line is important and should match the version used by the web server. Using PHP 7.1 (or lower) on the command line and using PHP 7.2 (or higher) on the web server can cause issues.
It is also important to ensure that the same PHP extensions/modules are loaded on the command line and the web server.
### PHP Version
| | CiviCRM 5.27 ESR | CiviCRM 5.x.x stable |
| ---- | ---- | ---- |
| PHP 7.4 | **incompatible** | Testing has shown that as of CiviCRM 5.28 can be run but issues are still being worked on in this [lab issue](https://lab.civicrm.org/dev/core/-/issues/1496) |
| PHP 7.3 | compatible and **recommended** | compatible and **recommended** |
| PHP 7.2 | compatible and **recommended** - but see note below about resaving the SMTP password | compatible and **recommended** but see note below about resaving the SMTP password |
| PHP 7.1 | compatible but **not recommended** due to to [PHP end-of life](http://php.net/eol.php) in Dec 2019 | compatible but **not recommended** due to to [PHP end-of life](http://php.net/eol.php) in Dec 2019 |
| PHP 7.0 | **incompatible** | incompatible as of 5.25.0 |
| PHP 5.6 | **incompatible** | **incompatible** |
### PHP Extensions
To install these extensions, you will typically install a separate package within your server's package manager (e.g. `apt-get` on Ubuntu).
#### Required for CiviCRM Core
* [PHP BCMath](https://www.php.net/bcmath) - required for calculating financial values in CiviCRM Core.
* [PHP Curl](https://www.php.net/curl) - required for many payment processors, the extension manager, and the CiviCRM News dashlet.
* [PHP DOM XML](https://www.php.net/manual/en/dom.setup.php) - required by CiviCase.
* [PHP Multibyte](https://php.net/manual/en/ref.mbstring.php) - required for internationalisation and proper encoding of fields.
* [PHP Zip](https://php.net/manual/en/book.zip.php) - required for unzipping auto-downloaded extensions so they can be installed from the browser.
* [PHP INTL](https://www.php.net/intl) - required for outputting localized formatted number strings from CiviCRM 5.28 onwards
#### Required for Third-Party Functionality or CiviCRM Extensions
* [PHP SOAP](https://www.php.net/soap) - required to use the SOAP processor (required for the CiviSMTP service)
#### PHP 7.1 and the MCrypt library
* [PHP MCrypt](https://php.net/manual/en/intro.mcrypt.php) - the MCrypt extension is no longer recommended for new installations.
!!! warning "PHP 7.2 Compatibility"
7.2 upgrade warning - 7.2 does not support MCrypt and if MCrypt is not installed the SMTP password (if entered) will need to be re-saved once you update your PHP version to 7.2.
!!! warning "PHP 7.1 cannot access SMTP credentials"
CiviCRM will incorrectly attempt to decrypt the SMTP password using the MCrypt library when executed using PHP 7.1. If PHP 7.2 or higher was used to save the SMTP password. This can occur if the PHP version on the command line does not match the web server version.
### PHP Configuration
* Set `memory_limit` between 256 and 512 megabytes
* Don't enable the deprecated `open_basedir` or `safemode` PHP directives. Otherwise you will have an error when automatically installing most of the extensions.
* Don't use MAMP XCache - Several people have reported "white screen of death" trying to run CiviCRM with MAMP's XCache enabled (check MAMP > Preferences > PHP > Cache).
## MySQL
CiviCRM requires MySQL (or compatible) database software.
[MariaDB](https://mariadb.org/) and [Percona](https://www.percona.com/software/mysql-database/percona-server) are forks of the MySQL project and can be used as drop-in replacements for MySQL.
Other database servers (such as PostgreSQL) are not compatible with CiviCRM.
### MySQL Version
Your MySQL version should be **5.7.5 or greater** or MariaDB **10.0.2 or greater**. As of version 5.28 the minimum install version for CiviCRM is 5.6 users on versions before that are advised to upgrade their MySQL instance to a recommended version. CiviCRM may not run correctly on MySQL 5.6 as these versions don't support some of the functionality CiviCRM uses to ensure that database actions don't compete for the same resources.
#### MySQL 8
As of version 5.24 CiviCRM has been shown to be able to run on MySQL 8 through the execution of our test matrix. Not all of the Content Management Systems support MySQL 8, CiviCRM MySQL 8 support is being tracked in this [open issue for MySQL 8 support](https://lab.civicrm.org/dev/core/issues/392). It is also worth knowing that both [Backdrop](https://forum.backdropcms.org/forum/installing-backdrop-1126-mysql-8-sqlmode-cant-be-set-value-noautocreateuser) and [Drupal 7](https://www.drupal.org/project/drupal/issues/2978575) have open issues with regards to MySQL 8 support. [Drupal 8](https://www.drupal.org/docs/8/system-requirements/database-server) [supports MySQL 8 as of version 8.6](https://www.drupal.org/project/drupal/issues/2966523), Current versions of WordPress and [Joomla](https://docs.joomla.org/Joomla_and_MySQL_8) appear to be compatible with MySQL 8
### MySQL Configuration
* Support for the `innodb` storage engine is required.
* The `thread_stack` configuration variable should be set to 192k or higher.
* Trigger support is required.
* The `ONLY_FULL_GROUP_BY` mode should be turned off on production sites - although this is mostly precautionary now.
* In MySQL 5.7+ the SQL mode `ONLY_FULL_GROUP_BY` is enabled by default which causes some errors due to some of CiviCRM's SQL queries that were written with the assumption that this mode would be disabled.
* Administrators are advised to turn off this SQL mode by removing the string `ONLY_FULL_GROUP_BY` from the `sql_mode` variable. The following SQL query will do the trick.
```sql
SET GLOBAL sql_mode=(SELECT REPLACE(@@sql_mode,'ONLY_FULL_GROUP_BY',''));
```
* See also:
* A popular [Stack Exchange question](https://stackoverflow.com/a/36033983/895563) discussing this issue
* [MySQL documentation on `sql_mode`](https://dev.mysql.com/doc/refman/5.7/en/sql-mode.html#sql-mode-setting)
* If you plan to have multiple languages used in your CiviCRM installation it is strongly recommended that you ensure that `locale` is set to a UTF8 locale and also ensure that you set utf8 as the standard encoding for MySQL. To alter locale you can configure as per [Ubuntu instructions](https://www.thomas-krenn.com/en/wiki/Configure_Locales_in_Ubuntu), [Debian](https://wiki.debian.org/Locale), [CentOS](https://www.rosehosting.com/blog/how-to-set-up-system-locale-on-centos-7/). To set the default encoding for MySQL you should follow the steps provided in this [Stack Overflow post](https://stackoverflow.com/questions/3513773/change-mysql-default-character-set-to-utf-8-in-my-cnf)
* In order to support a future data migration from `utf8` to the `utf8mb4` character set, it is recommended, though not yet required, to add the following configuration directives on MySQL 5.5 or 5.6 (these are the default values on MySQL 5.7):
```ini
[mysqld]
innodb_large_prefix=true
innodb_file_format=barracuda
innodb_file_per_table=true
```
* In MySQL 8 the default authentication plugin changes from `mysql_native_password` to `caching_sha2_password`. This may cause issues with your PHP layer. Fortunately you can revert this change by specifying your chosen authentication plugin in your MySQL configuration:
```ini
[mysqld]
default_authentication_plugin=mysql_native_password
```
Also in MySQL 8 the following variables, used fairly extensively in CiviCRM installs, have been removed `innodb_large_prefix` and `innodb_file_format`. In MySQL 8 binary logging is also turned on by default which many users may want to turn off, this can be achieved by adding to your MySQL configuration file:
```ini
[mysqld]
skip-log-bin
```
#### MySQL Time
CiviCRM performs various operations based on dates and times – for example, deactivating expired records or triggering scheduled reminders. To perform these operations correctly, the dates and times reported by PHP and MySQL should match. If the dates or times are mismatched, then one or more of the following may be the problem:
* PHP and MySQL may be running on different servers, and the clocks may be out-of-sync. Configuring automatic clock synchronization is the best solution.
* PHP, MySQL, and/or the operating system may be configured to use different default timezones. Verify the configuration of each.
* The content management system (Drupal, Joomla, or WordPress) or one of its plugins may manipulate the timezone settings without informing CiviCRM's. You may wish to post to [Stack Exchange](https://civicrm.stackexchange.com/) or [Mattermost](https://chat.civicrm.org) about your problem. Please include any available details about the timezone settings in the operating system, PHP, MySQL, and the CMS; if you have any special CMS plugins or configuration options which may affect timezones, please report them.
### MySQL Permissions
The permissions you'll need to assign to the MySQL user that CiviCRM uses will **depend on your version of MySQL**. The following example assumes you have a database called `civicrm` and a MySQL user called `civicrm_user`.
```sql
GRANT
SELECT,
INSERT,
UPDATE,
DELETE,
CREATE,
DROP,
INDEX,
ALTER,
CREATE TEMPORARY TABLES,
LOCK TABLES,
TRIGGER,
CREATE ROUTINE,
ALTER ROUTINE,
REFERENCES,
CREATE VIEW,
SHOW VIEW
ON civicrm.*
TO 'civicrm_user'@'localhost'
IDENTIFIED BY 'realpasswordhere';
```
#### Binary Logging
If you want to enable binary logging you will need to choose one of the following. Either:
* Add the following line to your `/etc/my.cnf` file.
```ini
log_bin_trust_function_creators = 1
```
(See the [MySQL manual reference](http://dev.mysql.com/doc/refman/5.1/en/server-system-variables.html#sysvar_log_bin_trust_function_creators) for more information.)
* Or give the `SUPER` permission (even if your MySQL version is greater than 5.1.6).
```sql
GRANT SUPER ON *.* TO 'civicrm_user'@'localhost';
```
(More information on triggers is available in the MySQL documentation about [Binary Logging of Stored Programs](http://dev.mysql.com/doc/refman/5.1/en/stored-programs-logging.html).)
# Installation Requirements
Ensure that your system meets the following requirements before installing or upgrading CiviCRM.
If you are curious what technologies other organizations are using to run CiviCRM, you can look at the [CiviCRM Stats](https://stats.civicrm.org/?tab=technology).
## Summary {:#summary}
A recommended server environment should typically meet these guidelines:
* __Operating system__: Linux
* __PHP__: PHP 8.2 or 8.3 is recommended
* __MySQL__: MySQL 5.7.5+ or MariaDB 10.2+ -- with configuration requirements
* __CMS__: Backdrop, Drupal 7, Drupal 10, Joomla 4 or WordPress (optional, if you're using a CMS)
Other environments may also meet the system requirements. The following sections present requirements more precisely.
## Server Environment {:#server}
### Operating System {:#os}
If your server meets all of the requirements described on this page, CiviCRM *should* function correctly. There are no explicit operating system requirements. However, it's worth noting that CiviCRM is far more widely deployed and tested on UNIX-based operating systems, in particular Linux (e.g. Ubuntu, Debian, etc.), than with Microsoft Windows. You can still use CiviCRM fine from Windows desktops when the hosting environment runs Linux.
### Hosting
In general, CiviCRM is a demanding web application which requires substantial server resources. It may not perform well on all hosting platforms. Learn more about [choosing your hosting platform](../planning/hosting.md).
## CMS {:#cms}
A CMS, or Content Management System, is a type of application which controls and manages the content of a website. CiviCRM must be installed within one of these compatible CMS platforms.
See the page on [choosing a CMS](../planning/cms.md) for more information about the advantages and disadvantages of each compatible CMS platform.
Each CMS has its own policies for which versions are supported or receiving only security support.
### Backdrop
* [Backdrop](../backdrop/index.md) 1.0 or newer is required.
### Drupal
* [Drupal 7, Drupal 10](../drupal/index.md) are recommended, although Drupal 8 and 9 which do not have security support also work with CiviCRM.
### Joomla
* [Joomla 4](../joomla/index.md) is recommended, although Joomla 3 which does not have security support also works with CiviCRM.
### WordPress
* [WordPress](../wordpress/index.md) latest major release is recommended as it is the only one that has official security support, though WordPress 4.9 or newer work with CiviCRM.
## PHP {:#php}
### PHP Version on the Command Line
The PHP version used on the command line is important and should match the version used by the web server. For example, using PHP 8.0 (or lower) on the command line and using PHP 8.3 (or higher) on the web server has been known to cause issues.
It is also important to ensure that the same PHP extensions/modules are loaded and enabled on both the command line version of PHP and the web server version.
### PHP Version
The following recommendations relate to the CiviCRM core codebase. CiviCRM native extensions, and modules and plugins that integrate CiviCRM with CMSes are maintained and released on other schedules. As they typically lag in supporting newer versions of PHP, it is recommended that you test your full site including this other software extensively as part of migrating to a newer version of PHP.
You can find the lifecycle of current PHP versions [here](https://www.php.net/supported-versions.php).
| | CiviCRM 5.81 ESR | CiviCRM 5.x.x stable |
| ---- | ---- | ---- |
| PHP 8.4 | not compatible| not compatible|
| PHP 8.3 | **compatible and recommended** | **compatible and recommended** |
| PHP 8.2 | **compatible and recommended** | **compatible and recommended** |
| PHP 8.1 | **compatible and recommended** | **compatible and recommended** |
| PHP 8.0 | compatible but **not recommended** due to [PHP end-of life](http://php.net/eol.php) in Nov 2023 | compatible but **not recommended** due to [PHP end-of life](http://php.net/eol.php) in Nov 2023 |
| PHP 7.4 | compatible but **not recommended** due to [PHP end-of life](http://php.net/eol.php) in Nov 2022 | ** not compatible ** |
| PHP <7.4 | **not compatible** | **not compatible** |
??? info "Historical PHP Versions"
The table below gives information on PHP minimum and recommended version compatibility for old versions of CiviCRM:
| CiviCRM Version | PHP Minimum Version | PHP Recommended Version |
| ------------------------ | ------------------- | ----------------------- |
| 5.1 - 5.5 | 5.5 | 7.0 |
| 5.6 - 5.9 | 5.5 | 7.1 |
| 5.10 - 5.13 | 5.6 | 7.2 |
| 5.14 - 5.23 | 7.0 | 7.2 |
| 5.24 | 7.0 | 7.3 |
| 5.25 - 5.34 | 7.1 | 7.3 |
| 5.35 - 5.36 | 7.2 | 7.3 |
| 5.37 - 5.45 | 7.2 | 7.4 |
| 5.46 - 5.69 | 7.3 | 7.4 |
| 5.70 - 5.81 | 7.4 | 8.1 |
### PHP Extensions
To install these extensions, you will typically install a separate package within your server's package manager (e.g. `apt-get` on Ubuntu).
#### Required for CiviCRM Core
* [PHP BCMath](https://www.php.net/bcmath) - required for calculating financial values in CiviCRM Core.
* [PHP Curl](https://www.php.net/curl) - required for many payment processors, the extension manager, and the CiviCRM News dashlet.
* [PHP DOM XML](https://www.php.net/manual/en/dom.setup.php) - required by CiviCase.
* [PHP Multibyte](https://php.net/manual/en/ref.mbstring.php) - required for internationalisation and proper encoding of fields.
* [PHP Zip](https://php.net/manual/en/book.zip.php) - required for unzipping auto-downloaded extensions so they can be installed from the browser.
* [PHP INTL](https://www.php.net/intl) - required for outputting localized formatted number strings from CiviCRM 5.28 onwards
* [PHP File Information](https://www.php.net/manual/en/book.fileinfo.php) - required for spreadsheet support from 5.44 onwards
#### Required for Third-Party Functionality or CiviCRM Extensions
* [PHP SOAP](https://www.php.net/soap) - required to use the SOAP processor (required for the CiviSMTP service)
### PHP Configuration
The following PHP directives is the recommended minimum. These are defined in the [php.ini file](https://www.php.net/manual/ini.list.php).
* [`memory_limit`](https://www.php.net/manual/ini.core.php#ini.memory-limit) 256M
* [`max_execution_time`](https://www.php.net/manual/info.configuration.php#ini.max-execution-time) 240
* [`max_input_time`](https://www.php.net/manual/info.configuration.php#ini.max-input-time) 120
* [`post_max_size`](https://www.php.net/manual/ini.core.php#ini.post-max-size) and [`upload_max_filesize`](https://www.php.net/manual/ini.core.php#ini.upload-max-filesize) 50M
!!! warning "Don't use MAMP XCache"
Several people have reported "white screen of death" trying to run CiviCRM with MAMP's XCache enabled (check MAMP > Preferences > PHP > Cache).
## MySQL
CiviCRM requires MySQL (or compatible) database software.
[MariaDB](https://mariadb.org/) and [Percona](https://www.percona.com/software/mysql-database/percona-server) are forks of the MySQL project and can be used as drop-in replacements for MySQL.
Other database servers (such as PostgreSQL) are not compatible with CiviCRM.
### MySQL Version
Your MySQL version should be **5.7.5 or greater** or MariaDB **10.2 or greater**.
??? info "Historical MySQL Versions"
The table below gives information on MySQL minimum and recommended version compatibility for old versions of CiviCRM:
| CiviCRM Version | MySQL Minimum Version | MySQL Recommended Version | MariaDB Minimum Version | MariaDB Recommended Version |
| ------------------------ | --------------------- | ------------------------- | ----------------------- | ------------------- |
| 5.26 - 5.27 | 5.5 | 5.7 | | |
| 5.28 - 5.33 | 5.6.5 | 5.7 | | 10.4 |
| 5.34 - 5.51 | 5.7 (unenforced) | 5.7 | 10.0.2 | 10.4 |
| 5.52 - Latest | 5.7 (enforced) | 5.7 | 10.2 | 10.4 |
#### MySQL 8
As of version 5.24 CiviCRM has been shown to be able to run on MySQL 8 through the execution of our test matrix. All of the Content Management Systems support MySQL 8, CiviCRM MySQL 8 support was being tracked in this [issue for MySQL 8 support](https://lab.civicrm.org/dev/core/issues/392). [Backdrop supports MySQL 8 as of 1.17.2](https://github.com/backdrop/backdrop/releases/tag/1.17.2), [Drupal 7 as of 7.76 Supports MySQL 8](https://www.drupal.org/node/3185889), All versions of [Drupal 9](https://www.drupal.org/docs/system-requirements/database-server-requirements) support MySQL 8, Current versions of WordPress and [Joomla](https://docs.joomla.org/Joomla_and_MySQL_8) appear to be compatible with MySQL 8.
### MySQL Connection {:#mysql-connection}
By default, new installations of CiviCRM will copy the MySQL connection details from the CMS, creating a shared database. It is also possible to
install CiviCRM on a separate database. As a rule of thumb:
* *A shared database* works well for small deployments (eg a few thousand records and a single administrator or developer).
* *Separate databases* work well for large deployments (eg a million records and multiple administrators/developers).
If you are unsure which style fits better, consider some trade-offs:
* _Initial setup_: The shared database can be setup automatically. To use a separate database, you must create the second one.
* _"Views" integration_: On Drupal 7 / Backdrop, the "Views" integration can query MySQL data from both
CMS and Civi. This works easily with a shared database, but it requires effort with separate databases.
* _Backups_: If you have a small data-set and a good backup mechanism, the shared database is easier to backup --
it's only one job.
* _Large datasets_: If the CMS dataset and Civi dataset grow large (eg millions of records), then separating the
databases will allow better resource-management.
* _Development/staging process_: If you have different people working on the system code or system configuration,
then they may need to work with different subsets of the data. (Ex: A theme developer may need access to
the CMS data but not the Civi data. For an application developer, that could be reversed.) With separate
databases, it may be easier to negotiate the workflow.
If your choose to use separate databases, then you need connection details for the second database. Connections are represented in URL format. For example:
```
mysql://dbuser:dbpassword@localhost:3306/dbname
```
The example URL captures several pieces of information:
| Setting | Example Value |
| ------- | ----- |
| Database User Name | `dbuser` |
| Database User Password | `dbpassword` |
| Database Server | `localhost` |
| Database Port | `3306` |
| Database Name | `dbname` |
Additional URL parameters may be added to support [MySQL with TLS](mysql_tls.md).
### MySQL Configuration
* Support for the `innodb` storage engine is required.
* The `thread_stack` configuration variable should be set to 192k or higher.
* Trigger support is required.
* `ANSI` or `ANSI_QUOTES` is not a supported `sql_mode`.
* The `ONLY_FULL_GROUP_BY` mode should be turned off on production sites - although this is mostly precautionary now.
* In MySQL 5.7+ the SQL mode `ONLY_FULL_GROUP_BY` is enabled by default which causes some errors due to some of CiviCRM's SQL queries that were written with the assumption that this mode would be disabled.
* Administrators are advised to turn off this SQL mode by removing the string `ONLY_FULL_GROUP_BY` from the `sql_mode` variable. The following SQL query will do the trick.
```sql
SET GLOBAL sql_mode=(SELECT REPLACE(@@sql_mode,'ONLY_FULL_GROUP_BY',''));
```
* See also:
* A popular [Stack Exchange question](https://stackoverflow.com/a/36033983/895563) discussing this issue
* [MySQL documentation on `sql_mode`](https://dev.mysql.com/doc/refman/5.7/en/sql-mode.html#sql-mode-setting)
* If you plan to have multiple languages used in your CiviCRM installation it is strongly recommended that you ensure that `locale` is set to a UTF8 locale and also ensure that you set utf8 as the standard encoding for MySQL. To alter locale you can configure as per [Ubuntu instructions](https://www.thomas-krenn.com/en/wiki/Configure_Locales_in_Ubuntu), [Debian](https://wiki.debian.org/Locale), [CentOS](https://www.rosehosting.com/blog/how-to-set-up-system-locale-on-centos-7/). To set the default encoding for MySQL you should follow the steps provided in this [Stack Overflow post](https://stackoverflow.com/questions/3513773/change-mysql-default-character-set-to-utf-8-in-my-cnf)
* In order to support a future data migration from `utf8` to the `utf8mb4` character set, it is recommended, though not yet required, to add the following configuration directives on MySQL 5.5 or 5.6 (these are the default values on MySQL 5.7):
```ini
[mysqld]
innodb_large_prefix=true
innodb_file_format=barracuda
innodb_file_per_table=true
```
* In MySQL 8 the default authentication plugin changes from `mysql_native_password` to `caching_sha2_password`. This may cause issues with your PHP layer. Fortunately you can revert this change by specifying your chosen authentication plugin in your MySQL configuration:
```ini
[mysqld]
default_authentication_plugin=mysql_native_password
```
Also in MySQL 8 the following variables, used fairly extensively in CiviCRM installs, have been removed `innodb_large_prefix` and `innodb_file_format`. In MySQL 8 binary logging is also turned on by default which many users may want to turn off, this can be achieved by adding to your MySQL configuration file:
```ini
[mysqld]
skip-log-bin
```
### MySQL Time
#### Synchronization {:#mysql-time-sync}
CiviCRM performs various operations based on dates and times – for example, deactivating expired records or triggering scheduled reminders. To perform these operations correctly, the dates and times reported by PHP and MySQL should match. If the dates or times are mismatched, then one or more of the following may be the problem:
* PHP and MySQL may be running on different servers, and the clocks may be out-of-sync. Configuring automatic clock synchronization is the best solution.
* PHP, MySQL, and/or the operating system may be configured to use different default timezones. Verify the configuration of each.
* The content management system (Drupal, Joomla, or WordPress) or one of its plugins may manipulate the timezone settings without informing CiviCRM's. You may wish to post to [Stack Exchange](https://civicrm.stackexchange.com/) or [Mattermost](https://chat.civicrm.org) about your problem. Please include any available details about the timezone settings in the operating system, PHP, MySQL, and the CMS; if you have any special CMS plugins or configuration options which may affect timezones, please report them.
!!! tip "WordPress Settings"
If you get a MySQL/PHP mismatch warning, under `Settings > General` set the timezone to a City, not UTC offset. For example, use `London` not `UTC+0`.
#### Timezones {:#mysql-timezones}
To support full and consistent display of timestamps, the MySQL server requires timezone data. Many servers include this data by default, but others require you to load it.
??? info "Survey of MySQL Servers and Timezone Support"
<!-- Sorted by `Status,Environment` -->
| Status | Environment | Comment |
| -- | -- | -- |
| ✅ | CiviHosting | |
| ✅ | Digital Ocean | Specifically tested w/[managed MySQL 8.0](https://www.digitalocean.com/products/managed-databases-mysql) |
| ✅ | Docker `mysql` | Specifically tested w/[8.0, 8.0-oracle, and 5.7](https://hub.docker.com/_/mysql) |
| ✅ | Docker `mariadb` | Specifically tested w/[10.3 and 10.4](https://hub.docker.com/_/mariadb) |
| ✅ | Google Cloud SQL | Specifically tested w/5.6. Warning from docs: ["not guaranteed to provide up-to-date time settings"](https://cloud.google.com/sql/docs/mysql/known-issues) |
| 🛠 | Azure Database | Use [`az_load_timezone()`](https://docs.microsoft.com/en-us/azure/mysql/howto-server-parameters#working-with-the-time-zone-parameter) |
| 🛠 | CentOS MariaDB/MySQL | Use `mysql_tzinfo_to_sql` |
| 🛠 | cPanel/WHM (with root access) | Use `mysql_tzinfo_to_sql` |
| 🛠 | Debian/Ubuntu MariaDB/MySQL | Use `mysql_tzinfo_to_sql` |
| 🛠 | Nix MariaDB/MySQL | Use `mysql_tzinfo_to_sql` |
| ❓ | Amazon RDS | Needs testing/clarification. There are old google-cached forum posts which imply gradual evolution toward support. The current ["Local time zone" page](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_MySQL.html#MySQL.Concepts.LocalTimeZone) seems to affirm, so probably ✅ ... but the docs don't specifically mention session-scoped timezones. |
| ❓ | cPanel/WHM (without root access) | Needs testing/clarification. If you lack access to `mysql_tzinfo_sql` (SSH) but have other ways to perform MySQL administration, then you may be able to load [pre-generated MySQL timezone data](https://github.com/civicrm/tzdata-mysql). Key question is whether you have MySQL admin rights. |
| ❓ | Pantheon | Needs testing/clarification. |
| ❓ | WP Engine | Needs testing/clarification. |
Definitions:
* (✅) Already support MySQL timezones
* (🛠) Can support MySQL timezones, with extra setup
* (❓) Status is not certain
* (🛑) Cannot support MySQL timezones
To determine if your server currently supports timezones, you can run a test with the `CONVERT_TZ()` function.
```sql
mysql> SELECT CONVERT_TZ("2001-02-03 04:05:00", "GMT", "America/New_York");
+--------------------------------------------------------------+
| CONVERT_TZ("2001-02-03 04:05:00", "GMT", "America/New_York") |
+--------------------------------------------------------------+
| 2001-02-02 23:05:00 |
+--------------------------------------------------------------+
```
If this doesn't perform a proper conversion, then you probably need to load the timezone data.
* On a self-hosted instance of MySQL or MariaDB, the standard technique is to run [`mysql_tzinfo_to_sql`](https://dev.mysql.com/doc/refman/8.0/en/mysql-tzinfo-to-sql.html).
* If you cannot run `mysql_tzinfo_to_sql` but have administrative access through another medium, you may load the [pre-generated MySQL timezone data](https://github.com/civicrm/tzdata-mysql/tree/master/sql).
Be sure to load the appropriate SQL file into the database named `mysql`.
* Some managed hosts require their own process. For example, "Azure Database" has a special procedure ([`az_load_timezone()`](https://docs.microsoft.com/en-us/azure/mysql/howto-server-parameters#working-with-the-time-zone-parameter)).
For managed hosts, you may need to consult their documentation or inquire with support.
??? info "Global organizations and service-providers should consider automation."
Timezone definitions change, albeit infrequently. For example, in 1996, Mexico adopted Daylight Savings Time (for most of its timezones); then,
in 2022, they dropped DST. For computer-based clocks supporting users in Mexico, those changes require an update to the timezone data. But it's
rare -- for Mexico, that represents two major changes (circa 1996 and 2022) over the span of 26 years.
The significance of timezone change is circumstantial. Compare:
* A local organization may go 20 years without needing an update. When there is a local or national change, it will be covered in the local news.
You may get by with infrequent/ad-hoc updates.
* Globally, in any given year, there will be several locales which do change their rules, and you may not be specifically aware of every change.
A global organization or service-provider should consider automatic updates. For example, you might define a system-startup script or a
monthly cron-job to run `mysql_tzinfo_to_sql`.
### MySQL Permissions
The permissions you'll need to assign to the MySQL user that CiviCRM uses will **depend on your version of MySQL**. The following example assumes you have a database called `civicrm` and a MySQL user called `civicrm_user`.
```sql
GRANT
SELECT,
INSERT,
UPDATE,
DELETE,
CREATE,
DROP,
INDEX,
ALTER,
CREATE TEMPORARY TABLES,
LOCK TABLES,
TRIGGER,
CREATE ROUTINE,
ALTER ROUTINE,
REFERENCES,
CREATE VIEW,
SHOW VIEW
ON civicrm.*
TO 'civicrm_user'@'localhost'
IDENTIFIED BY 'realpasswordhere';
```
#### Binary Logging
If you want to enable binary logging you will need to choose one of the following. Either:
* Add the following line to your configuration file. The location of the configuration file depends on your operating system and database server you can find more information [for MySQL here](https://dev.mysql.com/doc/refman/5.7/en/option-files.html) and [for MariaDB here](https://mariadb.com/kb/en/configuring-mariadb-with-option-files/).
```ini
log_bin_trust_function_creators = 1
```
(See the [MySQL manual reference](http://dev.mysql.com/doc/refman/5.1/en/server-system-variables.html#sysvar_log_bin_trust_function_creators) for more information.)
* Or give the `SUPER` permission (even if your MySQL version is greater than 5.1.6).
```sql
GRANT SUPER ON *.* TO 'civicrm_user'@'localhost';
```
(More information on triggers is available in the MySQL documentation about [Binary Logging of Stored Programs](http://dev.mysql.com/doc/refman/5.1/en/stored-programs-logging.html).)
#### Installing on certain Cloud Providers
When installing on certain cloud providers (AWS, Azure) where you are using database as a service, you will not have access to the my.cnf but you can generally use [Database Parameter Groups](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_WorkingWithParamGroups.html) or in [Azure](https://docs.microsoft.com/bs-cyrl-ba/azure/mysql/howto-server-parameters) to set the parameters such as the `log_bin_trust_function_creators` as appropriate. On Azure running with DB as a service there needs to be a change made to the installation code as per the answer on [Stack Exchange here](https://civicrm.stackexchange.com/questions/31794/civicrm-on-azure-not-finding-the-server). This is due to Azure not permitting connections to databases without credentials.
docs/general/troubleshooting.md
View file @ 45f46fb1
## General advice
Try searching the [CiviCRM Stack Exchange](https://civicrm.stackexchange.com/tour) for solutions.
Try to replicate the problem on the CiviCRM sandboxes - see "Testing Sandboxes" on the [CiviCRM demo page](https://civicrm.org/demo). If you can demonstrate that the problem doesn't just exist for you, more community members will give assistance.
Post a question on [CiviCRM Stack Exchange](https://civicrm.stackexchange.com/tour). Be sure to include:
* your CiviCRM version
* which CMS you use
* your CMS version
Consider improving the question with screenshots and/or detailed error messages. Be sure to mention if the problem exists on the demo site.
## More Detailed Errors (Debugging and Backtrace) {:#debugging}
If you receive a CiviCRM fatal error, you can find a more detailed error in one of two ways.
CiviCRM fatal errors are characterized by a yellow background:
![Fatal error screenshot without debug/backtrace enabled](../images/fatal-error.jpg)
### Review the CiviCRM log
If you have direct access to the files on your server, the CiviCRM log can be found in the ConfigAndLog directory. [Directions to find the ConfigAndLog directory can be found here](https://civicrm.stackexchange.com/a/15932/12). Errors are labeled with timestamps, and include both debug and backtrace information.
### Using the built-in Debugging Tools
Go to **Administer menu > System Settings > Debugging and Error Handling**, select "Yes" to both "Enable Debugging" and "Display Backtrace", and press "Save". Repeat the steps that caused your error, and you'll see a much more detailed error.
!!! danger "Do NOT Leave Debug Turned On in Production Sites"
When debugging is turned on, some internal settings are visible to site visitors. For security purposes, it's best to avoid turning on debugging/backtrace on public sites whenever possible.
Example with debug/backtrace enabled:
![Fatal error screenshot with debug/backtrace enabled](../images/backtrace.png)
## Symptoms
* **Directory Cleanup** - Empties template cache and/or upload file folders.
* To empty template cache (civicrm/templates_c folder), add `&directoryCleanup=1`
* To remove temporary upload files (civicrm/upload folder), add `&directoryCleanup=2`
* To cleanup both, add `&directoryCleanup=3`
* **Stack Trace** - To display stack trace at the top of the page when an error occurs, set Enable Backtrace from **Administer » System Settings » Debugging** **and Error Handling**.
### "civicrm_strip_non_numeric does not exist"
This error occurs when your database has lost a MySQL function definition for `civicrm_strip_non_numeric`. It can happen when moving from one server to another with the wrong `mysqldump` parameters, or if you use phpMyAdmin or certain other tools to rename a database, since they copy most but not all of the contents of the database to a database with the new name before deleting the old one. [Re-build your database triggers](#trigger-rebuild) to fix the problem.
### "Could not find valid Key"
If you are getting this error when submitting a form (search or adding / editing records), check the following:
* Ensure cookies are enabled on browser. Like most web applications, CiviCRM can not function properly with cookies disabled.
* Ensure your configuration settings are using the same "machine name" for CiviCRM and your CMS. For example, you will have problems if CiviCRM is configured to use `http://example.com` as its `BASE_URL` and your CMS is using `http://www.example.com`. You can use an `.htaccess` entry to redirect to the configured URL if needed (i.e. push all users to `http://www.example.com` even if they hit `http://example.com`).
1. For Drupal sites, ensure that `uid = 0` exists in your Drupal users table. This is required for anonymous access to CiviCRM pages and forms to work properly.
1. For Drupal sites, ensure that Drupal sessions table uses UTF8 collation, AND that the session column in this table is of SQL type longtext in the schema. You can check both of these in phpMyAdmin, or issue these commands from mysql command line:
```sql
desc session;
show create table sessions;
```
### "DB_DataObject Error: DB Error: connect failed"
If you get this error on a new Drupal/CiviCRM installation, you may have skipped the step of running CiviCRM's installation script. You can not install CiviCRM using the standard Drupal module installer.
### "Failed to initialize storage module: user" fatal error message (new installs)
If you see this error, you may need to modify the session.save_handler method for your site. Check with your hosting provider for the recommended way to do this.
### WordPress menus are wrong
Try [rebuilding the WordPress menus](#rebuild-wp-menus).
### "Your PHP version is missing zip functionality"
If you get this error when installing or upgrading CiviCRM for Joomla, download and use the `civicrm-x.x.x-joomla-alt.zip` package.
## Solutions
### Cleanup Caches and Update Paths {:#clear-cache}
On this settings page you can:
* Clear the cache
* View and update the value that CiviCRM has determined for your Base Url and site name.
![Screenshot demonstrating the "Cleanup Caches" screen](../images/clean-up-caches.png)
Although you enter your Base URL in `civicrm.settings.php` the value shown here reflects additional attempts by CiviCRM to automatically detect the correct base url in various environments - for example in multilingual sites.
### Create a config file pointing to your Drupal sites directory {:#conf-drupal-sites}
If your CiviCRM codebase is not located in either `<drupal_root>/modules/civicrm` or `<drupal_root>/sites/all/modules` (for example, if you're using a symlink from there to your codebase) - you will need to create a local file in the top-level directory of your codebase which points to the location of your drupal sites directory.
```php
// Create a new file - settings_location.php
// Enter the following code (substitute the actual location of your
// <drupal root>/sites directory)
<?php
define( 'CIVICRM_CONFDIR', '/home/lobo/public_html/drupal/sites' );
?>
```
### Make CiviCRM available behind a NAT firewall {:#nat-firewall}
If CiviCRM is installed on a server behind a firewall with NAT, you'll need to add your **internal** IP address and host name to `/etc/hosts` (on Linux). Otherwise, the dashboard will time out and the Force Secure URLs option will have issues. The reasoning behind this is, the dashboard tries to connect to `http(s)://www.example.org` to load the dashboard, but times out since `example.org` is being resolved via the public IP address. Your server can't access this public IP address if it's behind a firewall with NAT.
### Rebuild CiviCRM menus {:#rebuild-civicrm-menus}
Sometimes it helps to rebuild the menu/admin dashboard by visiting the following URL:
`http://example.org/civicrm/menu/rebuild?reset=1`
### Rebuild database triggers {:#trigger-rebuild}
If you need to rebuild your database triggers, navigate to the following url:
`http://example.org/civicrm/menu/rebuild?reset=1&triggerRebuild=1`
Note the `&triggerRebuild=1` key-value pair.
### Rebuild WordPress menus {:#rebuild-wp-menus}
You can re-build the menu/admin dashboard by visiting the following url
`http://example.org/wp-admin/admin.php?page=CiviCRM&q=civicrm/menu/rebuild&reset=1`
### Reset config_backend
Having strange problems with Administrative settings forms after upgrade? Try deleting all files in the following directories:
* `sites/default/files/civicrm/templates_c/`
* `sites/default/files/civicrm/ConfigAndLog/Config.IDS.ini`
### Reset Your User Session {:#reset-session}
To reset your user session:
1. Temporarily enable CiviCRM debug features:
* Go to **Administer CiviCRM » System Settings » Debugging and Error Handling**
* Set **Enable Debugging** to Yes and click Save.
1. Click the Administer CiviCRM menu (or any other CiviCRM menu item). After the page is loaded, add an additional query string value (`sessionReset=2`) to the URL in your browser's location bar, and reload the page.
1. Now reset **Enable Debugging** to No and click Save.
!!! danger "Do Not Leave Debug Features Enabled for a Public Site"
Debugging should be disabled for publicly available sites as it may allow browsers to view system configuration information.
### Roll back to previous version of CiviCRM (from a backup)
Sometimes an upgrade fails and you need to get back to the last working version. You should have backups of the database saved as well as a backup of the civicrm files from the `/sites/all/modules/` directory. Here are the steps you need to take in order to roll back to the last working version before your upgrade:
* Go into maintenance mode and take the site offline.
* In the modules screen, disable all the CiviCRM modules EXCEPT the Core CiviCRM module. Make sure to take note of which CiviCRM modules you've disabled so you can enable them again after you restore the backups.
* Make sure to drop all the tables in the civicrm database that relate to civicrm. If you're sharing a database with Drupal, make sure to ONLY drop the tables that belong to CiviCRM and NOT the tables for Drupal. If Drupal's tables are in a separate database, then you should be safe as long as you don't touch any of the Drupal tables.
* Restore all the civicrm tables from your database backup back into the database.
* In the `/sites/all/modules` directory, make sure to delete the entire civicrm directory (`../sites/all/modules/civicrm`).
* Restore the civicrm directory in `/sites/all/modules/` from your files backup.
* CRUCIAL: Remove the `templates_c` directory from `../sites/default/files/civicrm/` (don't worry, CiviCRM will recreate these files when you reload the pages).
* Go back to Drupal's Modules screen and enable the CiviCRM modules you disabled.
* Bring the site back online by turning off Maintenance mode.
* Load up civicrm by going to `http://example.org/civicrm` (or wherever you have civicrm installed). This should have restored you back to the last working condition.
Sometimes it helps to [rebuild the CiviCRM menus](#rebuild-civicrm-menus).
### Update Base Directory and Base URL Settings {:#base-settings}
To update your Base Directory and Base URL Settings in the database, visit this settings page:
* **Administer CiviCRM > System Settings > Cleanup Caches and Update Paths**
## General advice
Try searching the [CiviCRM Stack Exchange](https://civicrm.stackexchange.com/tour) for solutions.
Try to replicate the problem on the CiviCRM sandboxes - see "Testing Sandboxes" on the [CiviCRM demo page](https://civicrm.org/demo). If you can demonstrate that the problem doesn't just exist for you, more community members will give assistance.
Post a question on [CiviCRM Stack Exchange](https://civicrm.stackexchange.com/tour). Be sure to include:
* your CiviCRM version
* which CMS you use
* your CMS version
Consider improving the question with screenshots and/or detailed error messages. Be sure to mention if the problem exists on the demo site.
## More Detailed Errors (Debugging and Backtrace) {:#debugging}
If you receive a CiviCRM fatal error, you can find a more detailed error in one of two ways.
CiviCRM fatal errors are characterized by a yellow background:
![Fatal error screenshot without debug/backtrace enabled](../images/fatal-error.jpg)
### Review the CiviCRM log
If you have direct access to the files on your server, the CiviCRM log can be found in the ConfigAndLog directory. [Directions to find the ConfigAndLog directory can be found here](https://civicrm.stackexchange.com/a/15932/12). Errors are labeled with timestamps, and include both debug and backtrace information.
### Using the built-in Debugging Tools
Go to **Administer menu > System Settings > Debugging and Error Handling**, select "Yes" to both "Enable Debugging" and "Display Backtrace", and press "Save". Repeat the steps that caused your error, and you'll see a much more detailed error.
!!! danger "Do NOT Leave Debug Turned On in Production Sites"
When debugging is turned on, some internal settings are visible to site visitors. For security purposes, it's best to avoid turning on debugging/backtrace on public sites whenever possible.
Example with debug/backtrace enabled:
![Fatal error screenshot with debug/backtrace enabled](../images/backtrace.png)
## Symptoms
* **Directory Cleanup** - Empties template cache and/or upload file folders.
* To empty template cache (civicrm/templates_c folder), add `&directoryCleanup=1`
* To remove temporary upload files (civicrm/upload folder), add `&directoryCleanup=2`
* To cleanup both, add `&directoryCleanup=3`
* **Stack Trace** - To display stack trace at the top of the page when an error occurs, set Enable Backtrace from **Administer » System Settings » Debugging** **and Error Handling**.
### "civicrm_strip_non_numeric does not exist"
This error occurs when your database has lost a MySQL function definition for `civicrm_strip_non_numeric`. It can happen when moving from one server to another with the wrong `mysqldump` parameters, or if you use phpMyAdmin or certain other tools to rename a database, since they copy most but not all of the contents of the database to a database with the new name before deleting the old one. [Re-build your database triggers](#trigger-rebuild) to fix the problem.
### "Could not find valid Key"
If you are getting this error when submitting a form (search or adding / editing records), check the following:
* Ensure cookies are enabled on browser. Like most web applications, CiviCRM can not function properly with cookies disabled.
* Ensure your configuration settings are using the same "machine name" for CiviCRM and your CMS. For example, you will have problems if CiviCRM is configured to use `http://example.com` as its `BASE_URL` and your CMS is using `http://www.example.com`. You can use an `.htaccess` entry to redirect to the configured URL if needed (i.e. push all users to `http://www.example.com` even if they hit `http://example.com`).
1. For Drupal sites, ensure that `uid = 0` exists in your Drupal users table. This is required for anonymous access to CiviCRM pages and forms to work properly.
1. For Drupal sites, ensure that Drupal sessions table uses UTF8 collation, AND that the session column in this table is of SQL type longtext in the schema. You can check both of these in phpMyAdmin, or issue these commands from mysql command line:
```sql
desc session;
show create table sessions;
```
### "DB_DataObject Error: DB Error: connect failed"
If you get this error on a new Drupal/CiviCRM installation, you may have skipped the step of running CiviCRM's installation script. You can not install CiviCRM using the standard Drupal module installer.
### "Failed to initialize storage module: user" fatal error message (new installs)
If you see this error, you may need to modify the session.save_handler method for your site. Check with your hosting provider for the recommended way to do this.
### Page doesn't reload and spinner shows when tryibng to re-create triggers, eventually showing "DB Error: unknown error"
There can be multiple reasons for this, but they usually relate to MySQL user or connection issues. Check the MySQL user exists, and that it can log in to the database from the server accessing MySQL with the password in civicrm.settings.php. You may want to check logs then. A solution on some systems with MySQL binary logging is to add log_bin_trust_function_creators = 1 to the mysqld config file.
### "Your PHP version is missing zip functionality"
If you get this error when installing or upgrading CiviCRM for Joomla, download and use the `civicrm-x.x.x-joomla-alt.zip` package.
### WordPress menus are wrong
Try [rebuilding the WordPress menus](#rebuild-wp-menus).
## Solutions
### Cleanup Caches and Update Paths {:#clear-cache}
On this settings page you can:
* Clear the cache
* View and update the value that CiviCRM has determined for your Base Url and site name.
![Screenshot demonstrating the "Cleanup Caches" screen](../images/clean-up-caches.png)
Although you enter your Base URL in `civicrm.settings.php` the value shown here reflects additional attempts by CiviCRM to automatically detect the correct base url in various environments - for example in multilingual sites.
### Create a config file pointing to your Drupal sites directory {:#conf-drupal-sites}
If your CiviCRM codebase is not located in either `<drupal_root>/modules/civicrm` or `<drupal_root>/sites/all/modules` (for example, if you're using a symlink from there to your codebase) - you will need to create a local file in the top-level directory of your codebase which points to the location of your drupal sites directory.
```php
// Create a new file - settings_location.php
// Enter the following code (substitute the actual location of your
// <drupal root>/sites directory)
<?php
define( 'CIVICRM_CONFDIR', '/home/lobo/public_html/drupal/sites' );
?>
```
### Make CiviCRM available behind a NAT firewall {:#nat-firewall}
If CiviCRM is installed on a server behind a firewall with NAT, you'll need to add your **internal** IP address and host name to `/etc/hosts` (on Linux). Otherwise, the dashboard will time out and the Force Secure URLs option will have issues. The reasoning behind this is, the dashboard tries to connect to `http(s)://www.example.org` to load the dashboard, but times out since `example.org` is being resolved via the public IP address. Your server can't access this public IP address if it's behind a firewall with NAT.
### Rebuild CiviCRM menus {:#rebuild-civicrm-menus}
Sometimes it helps to rebuild the menu/admin dashboard by visiting the following URL:
`http://example.org/civicrm/menu/rebuild?reset=1`
### Rebuild database triggers {:#trigger-rebuild}
If you need to rebuild your database triggers, navigate to the following url:
`http://example.org/civicrm/menu/rebuild?reset=1&triggerRebuild=1`
Note the `&triggerRebuild=1` key-value pair.
### Rebuild WordPress menus {:#rebuild-wp-menus}
You can re-build the menu/admin dashboard by visiting the following url
`http://example.org/wp-admin/admin.php?page=CiviCRM&q=civicrm/menu/rebuild&reset=1`
### Reset config_backend
Having strange problems with Administrative settings forms after upgrade? Try deleting all files in the following directories:
* `sites/default/files/civicrm/templates_c/`
* `sites/default/files/civicrm/ConfigAndLog/Config.IDS.ini`
### Reset Your User Session {:#reset-session}
To reset your user session:
1. Temporarily enable CiviCRM debug features:
* Go to **Administer CiviCRM » System Settings » Debugging and Error Handling**
* Set **Enable Debugging** to Yes and click Save.
1. Click the Administer CiviCRM menu (or any other CiviCRM menu item). After the page is loaded, add an additional query string value (`sessionReset=2`) to the URL in your browser's location bar, and reload the page.
1. Now reset **Enable Debugging** to No and click Save.
!!! danger "Do Not Leave Debug Features Enabled for a Public Site"
Debugging should be disabled for publicly available sites as it may allow browsers to view system configuration information.
### Roll back to previous version of CiviCRM (from a backup)
Sometimes an upgrade fails and you need to get back to the last working version. You should have backups of the database saved as well as a backup of the civicrm files from the `/sites/all/modules/` directory. Here are the steps you need to take in order to roll back to the last working version before your upgrade:
* Go into maintenance mode and take the site offline.
* In the modules screen, disable all the CiviCRM modules EXCEPT the Core CiviCRM module. Make sure to take note of which CiviCRM modules you've disabled so you can enable them again after you restore the backups.
* Make sure to drop all the tables in the civicrm database that relate to civicrm. If you're sharing a database with Drupal, make sure to ONLY drop the tables that belong to CiviCRM and NOT the tables for Drupal. If Drupal's tables are in a separate database, then you should be safe as long as you don't touch any of the Drupal tables.
* Restore all the civicrm tables from your database backup back into the database.
* In the `/sites/all/modules` directory, make sure to delete the entire civicrm directory (`../sites/all/modules/civicrm`).
* Restore the civicrm directory in `/sites/all/modules/` from your files backup.
* CRUCIAL: Remove the `templates_c` directory from `../sites/default/files/civicrm/` (don't worry, CiviCRM will recreate these files when you reload the pages).
* Go back to Drupal's Modules screen and enable the CiviCRM modules you disabled.
* Bring the site back online by turning off Maintenance mode.
* Load up civicrm by going to `http://example.org/civicrm` (or wherever you have civicrm installed). This should have restored you back to the last working condition.
Sometimes it helps to [rebuild the CiviCRM menus](#rebuild-civicrm-menus).
### Update Base Directory and Base URL Settings {:#base-settings}
To update your Base Directory and Base URL Settings in the database, visit this settings page:
* **Administer CiviCRM > System Settings > Cleanup Caches and Update Paths**
docs/general/unicode_pdf.md 0 → 100644
View file @ 45f46fb1
# Using your own font or CJK characters in PDF output
As of CiviCRM 6.0, most unicode characters will output correctly in PDFs. But if you need CJK characters DejaVu does not contain those, so you will need to install another font file such as SimSun using the steps below.
If you are still seeing question marks (?) in place of unicode characters, even for non-CJK characters, check that you don't have a `<font>` tag or `style` attribute in the html specifically setting a font that doesn't support unicode.
## Option A: Using web fonts
1. In your html template add a `<link>` tag like the following, e.g. for the Noto Sans SC font: `<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Noto+Sans+SC:wght@100..900">`
1. Specify the font using CSS in the templates where you use the CJK characters. You can use the Source button in CKEditor to do this and type it directly into the HTML: e.g. `<p style="font-family: Noto Sans SC;">的</p>`
## Option B: Storing fonts locally
1. While option A will cache a version of the file after the first download, it may not be available on the internet or may be a commercial font.
1. Create a folder in a location that won't get overwritten when you upgrade, e.g. sites/default/fonts for Drupal.
1. Copy the .ttf font file you want to use into that folder.
1. Run `php -r 'require_once "/path/to/civicrm/vendor/autoload.php"; $f = \FontLib\Font::load("/full/path/to/the/ttf/file"); $f->parse(); $f->saveAdobeFontMetrics("/full/path/to/output/ufm/file");'`
* e.g. `php -r 'require_once "/var/www/sites/all/modules/civicrm/vendor/autoload.php"; $f = \FontLib\Font::load("/var/www/sites/default/fonts/simsun.ttf"); $f->parse(); $f->saveAdobeFontMetrics("/var/www/sites/default/fonts/simsun.ufm");'`
1. Create a file in that folder called `installed-fonts.json` that looks like this:
```json
{
"simsun": {
"normal": "simsun"
}
}
```
1. Visit Administer - System Settings - Misc and in the field for DOMPDF Font Folder put the full path to the font folder you created in step 2.
1. Specify the font using CSS in the templates where you use the CJK characters. You can use the Source button in CKEditor to do this and type it directly into the HTML: e.g. `<p style="font-family: simsun;">的</p>`
1. Note any fonts you set up here are in addition to the ones distributed with dompdf/CiviCRM. You do not need to copy those core fonts over or add entries in this json file to use them.
docs/images/wpms/image-20201027174136563.png 0 → 100644
View file @ 45f46fb1
docs/images/wpms/image-20201027174136563.png

85.9 KiB

docs/images/wpms/image-20201027175354535.png 0 → 100644
View file @ 45f46fb1
docs/images/wpms/image-20201027175354535.png

11.4 KiB

docs/images/wpms/image-20201027175658226.png 0 → 100644
View file @ 45f46fb1
docs/images/wpms/image-20201027175658226.png

41.1 KiB

docs/images/wpms/image-20201027175824708.png 0 → 100644
View file @ 45f46fb1
docs/images/wpms/image-20201027175824708.png

30.9 KiB

docs/images/wpms/image-20201027175950175.png 0 → 100644
View file @ 45f46fb1
docs/images/wpms/image-20201027175950175.png

38.8 KiB

docs/images/wpms/image-20201027180035261.png 0 → 100644
View file @ 45f46fb1
docs/images/wpms/image-20201027180035261.png

28.6 KiB

docs/images/wpms/image-20201027180145841.png 0 → 100644
View file @ 45f46fb1
docs/images/wpms/image-20201027180145841.png

31.5 KiB

docs/images/wpms/image-20201027180252729.png 0 → 100644
View file @ 45f46fb1
docs/images/wpms/image-20201027180252729.png

30.9 KiB

docs/images/wpms/image-20201027180332753.png 0 → 100644
View file @ 45f46fb1
docs/images/wpms/image-20201027180332753.png

26.1 KiB