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
  • JonGold/installation
29 results
Show changes
Commits on Source (128)
28 additional commits have been omitted to prevent performance issues.
Expand all Hide whitespace changes
Inline Side-by-side
Showing
with 754 additions and 722 deletions
docs/backdrop/index.md
View file @ 45f46fb1
......@@ -5,6 +5,10 @@
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/).
......@@ -158,9 +162,9 @@ There should now be a **CiviCRM** link in your Backdrop menu. Click that link an
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.
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 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 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.
......@@ -170,7 +174,7 @@ See [TLS for MySQL](../general/mysql_tls.md) for introductory concepts and the s
array (
'default' =>
array (
'database' => 'drupal',
'database' => 'backdrop',
'username' => 'dbuser',
'password' => 'dbpassword',
'host' => 'db435.examplehost.com',
......
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.
???+ tldr "About this document"
This guide covers standard installation of CiviCRM on an existing Drupal site. Before starting, you must have completed these tasks:
1. [Installed Drupal](https://www.drupal.org/docs/installing-drupal) and...
1. [Reviewed the CiviCRM requirements](../general/requirements.md)
## Get the code for Drupal 10 {:#drupal10-download}
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.
If `composer` is properly installed, then these example commands will add latest CiviCRM version to D10:
```
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
```
This guide covers standard installation of CiviCRM on an existing Drupal 9 site. It assumes that you previously completed these tasks:
??? 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).
### Install CiviCRM without any translations {#drupal10-installation}
To install CiviCRM without any translations we use the command line tool `cv` and we assume you already have an empty database.
1. Install Drupal 9, and...
1. [Review the CiviCRM requirements](../general/requirements.md)
Change the following in the command below:
??? tldr "Alternative: Civibuild for developers"
* `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
If you plan to develop patches for CiviCRM on Drupal 9, then please read the [Developer Guide](https://docs.civicrm.org/dev/en/latest) for information about [Buildkit](https://docs.civicrm.org/dev/en/latest/tools/buildkit/) and [civibuild](https://docs.civicrm.org/dev/en/latest/tools/civibuild/).
```
cv core:install --cms-base-url="https://d10.example.org" --db="mysql://database_user:database_pass@localhost:3306/civicrm_database"
```
<a name="downloading"></a><!-- old anchor -->
## Get the code {:#download}
### Install a translated CiviCRM {:#drupal10-i18n}
Drupal 9 (D9) sites are typically administered with [Composer](https://www.getcomposer.org). Composer is a *dependency management* tool which can add, upgrade, and remove software *packages* for your site.
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.
......@@ -72,11 +121,22 @@ If `composer` is properly installed, then these example commands will add CiviCR
```
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"
......@@ -86,6 +146,21 @@ If you'd like more details to understand these commands or common errors, then p
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"
For any package in `composer`, there may be several available versions. Some have an official, well-defined name
or number (e.g. `v1.2.3`), and these are called "stable" versions. Other versions have an interim name or number
(e.g. `v1.2.alpha1` or `dev-master`) indicating that additional testing is appropriate.
As a general rule, a new `composer` deployment will (and should) only use "stable" versions. CiviCRM, too, is
generally built around "stable" dependencies. However, in some exceptional cases, CiviCRM requires an interim
release of some libraries.
`composer.json` has two options which affect this: [minimum-stability](https://getcomposer.org/doc/04-schema.md#minimum-stability) sets an
absolute baseline, and [prefer-stable](https://getcomposer.org/doc/04-schema.md#prefer-stable) expresses a general preference.
Setting `minimum-stability` to `dev` enables to installation to proceed when there are exceptional cases. Setting
`prefer-stable` to `true` means that `composer` will use stable releases whenever it can.
??? info "More detail: Compilation tasks"
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`.
......@@ -112,9 +187,7 @@ If you'd like more details to understand these commands or common errors, then p
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`).
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:
......@@ -138,7 +211,7 @@ Optionally you can also require the [`cv`](https://github.com/civicrm/cv) comman
-->
## Get the translations {:#i18n}
### Get the translations for Drupal 9 {:#drupal9-i18n}
!!! warning "I18n & L10n on Drupal 9"
If installing with the GUI it is currently only possible to install CiviCRM in English (US) on Drupal 9. Adding the language files involves breaking with Composer best practices by writing the contents of the `civicrm-l10n` tarball into `vendor/civicrm/civicrm-core` or configuring the `civicrm.l10n` directory path after you install and placing the contents of the `civicrm-l10n` tarball into the configured directory.
......@@ -148,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.
......@@ -174,7 +247,7 @@ The warnings above notwithstanding to install CiviCRM on Drupal 9 requires the f
Now we move onto [Installing CiviCRM - Command line install](#installing-commandline)
<a name="installing"></a><a name="installing-gui"></a><a name="installing-commandline"></a>
## Run the installer {:#installer}
### Run the installer for Drupal 9 {:#drupal9-installer}
The installer verifies requirements, prepares the database, and initializes the configuration file. You may run the installer through the web interface (*which is simpler*) or the command-line interface (*which has more options*).
......@@ -191,7 +264,7 @@ The installer verifies requirements, prepares the database, and initializes the
If you need to configure any of these options, then use the command-line installer.
??? warning "Write permissions"
It is critical that your web-server user is able to write to the `web/sites/default/` directory in order to create `civicrm.settings.php` and that you have an appropriate value for execution time(s) and memory limit(s) as any interruption to the installer can (and will) result in an unusable install and require remedial steps to correct or a full reinstall! By default on Drupal 8.8+ this directory path is not writable by default, before installing you should ensure you grant write access to your web server user. With, e.g: `sudo chmod u+w web/sites/default`.
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`.
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`.
......@@ -200,13 +273,119 @@ The installer verifies requirements, prepares the database, and initializes the
`https://example.org/admin/modules/`
3. Find "CiviCRM" and enable it.
4. At the bottom, click "Save Configuration". (Note: This may take a few moments to execute.)
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.)
??? 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).
## Get the code for Drupal 7 {:#drupal7-download}
The [CiviCRM download page](https://civicrm.org/download) provides a pre-built archive for use with Drupal 7. A
typical archive file is ~20mb and looks like `civicrm-X.Y.Z-drupal.tar.gz`. It contains a folder named `civicrm/`.
In Drupal 7, there is a folder for storing add-on modules: `DRUPAL_ROOT/sites/all/modules`.
Our goal is to download the archive and extract into this folder. Here are a few example ways to download and extract:
??? example "Download via web-browser"
This method does not require shell access on the server. You may adapt based your server's arrangement.
* On the [CiviCRM download page](https://civicrm.org/download), click the link for CiviCRM / Drupal 7. Save the file locally.
* Extract the archive locally. For example, in a Linux workstation, one might say:
```bash
cd ~/Downloads
tar xvzf civicrm-X.Y.Z-drupal.tar.gz
```
* Observe the new folder `civicrm/`.
* Using your favor file-transfer system (SSH/SFTP, `rsync`, `git`, `mv`, etc), transfer the `civicrm/` folder
to `DRUPAL_ROOT/sites/all/modules`.
??? example "Download via curl + tar"
This method require shell access to the Drupal server.
* On the [CiviCRM download page](https://civicrm.org/download), note the current version.
* In the shell, navigate to the Drupal module folder (*adjust as appropriate*):
```bash
cd DRUPAL_ROOT/sites/all/modules
```
* In the shell, run the `curl` and `tar` commands. Adjust the version `X.Y.Z` to the appropriate value.
```bash
curl -L "https://download.civicrm.org/civicrm-X.Y.Z-drupal.tar.gz" | tar xvz
```
??? example "Download via Drupal web UI"
This is the easiest way for a new administrator. However, it may not work in all deployments or
all versions. For
example, if the Drupal server has a locked-down configuration, then it may encounter permission errors
or timeouts. The only way to find out is to try.
* On the [CiviCRM download page](https://civicrm.org/download), right-click the link for CiviCRM / Drupal 7. Copy the URL.
* Login to your Drupal site with *administrator* permissions.
* Navigate to **Modules >> Install new module**.
* Paste the URL
* Click "Install"
??? warning "This may not work with CiviCRM 5.13-5.30"
In CiviCRM versions 5.13 - 5.30, the prebuilt tarball included a symlink which is not accepted by
the Drupal 7 installer. This should work again in 5.31.
<!-- TODO: After 5.31 has been out for a while, we can move this option higher up and remove/downgrade the notice. -->
??? warning "The "Upload"/"Browse" option is unlikely to work."
The **Install new module** page provides another option for uploading the archive from your local computer.
In a default PHP configuration, the upload limits are too conservative to accept the CiviCRM archive.
In all cases, the final outcome should be the creation of a new folder
```
DRUPAL_ROOT/sites/all/modules/civicrm
```
### Get the translations for Drupal 7 {:#drupal7-i18n}
The basic CiviCRM release includes support for US English (`en_US`). To use another language or dialect, please [download and extract the translation files](../general/i18n_l10n.md).
### Run the installer for Drupal 7 {:#drupal7-installer}
The installer verifies requirements, prepares the database, and initializes the configuration file. You may run the installer through the web interface (*which is simpler*) or the command-line interface (*which has more options*).
??? example "Run installer via Drupal 7 web UI"
1. Enable the "CiviCRM" module
* Login to your Drupal site with *administrator* permissions.
* Navigate to the "Modules" page (`admin/modules`).
* Find "CiviCRM" and enable it.
* At the bottom, click "Save Configuration".
2. After enabling, the status message will display a link to "configure CiviCRM". Click it.
??? question "What if I didn't notice the link?"
Use the URL bar. Navigate to the `civicrm` page (e.g. `https://example.com/civicrm`).
3. The CiviCRM installer will open.
* *If there are unmet requirements*, the installer will list them. Consult the [Requirements](../general/requirements.md) documentation for additional advice.
* *If all the requirements are met*, proceed through the brief questionnaire.
* *If you have [a separate MySQL database for CiviCRM](../general/requirements.md#mysql-connection)*, then locate "Environment: CiviCRM Database". Click the edit icon and enter the [database URL](../general/requirements.md#mysql-connection).
* Finally, click "Install CiviCRM".
??? example "Run installer via the command-line"
CiviCRM has a command-line administration tool, `cv`, which can perform installation. For details, see [command-line installer](../general/cli-cv.md).
# Troubleshooting {:#troubleshooting}
* Review the [Troubleshooting](../general/troubleshooting.md) page for help with problems you may encounter during the installation.
# Post-installation {:#post-install}
Recommended steps to perform after installing CiviCRM on Drupal.
## Review the permissions {:#permissions}
!!! note ""
......@@ -260,7 +439,7 @@ If your MySQL database is hosted on a different machine than your web server, or
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.
......@@ -329,13 +508,9 @@ See [TLS for MySQL](/general/mysql_tls/) for introductory concepts and the setti
__Webform CiviCRM module__
* [Project page on Drupal.org](https://www.drupal.org/project/webform_civicrm)
* [Documentation on CiviCRM.org](https://docs.civicrm.org/webform-civicrm/en/latest)
* [Webform project page on drupal.org](https://www.drupal.org/project/webform_civicrm)
* [Webform documentation on civicrm.org](https://docs.civicrm.org/webform-civicrm/en/latest)
__CiviCRM Entity module__
* [Project page on Drupal.org](https://www.drupal.org/project/civicrm_entity)
### Troubleshooting {:#troubleshooting}
* Review the [Troubleshooting](../general/troubleshooting.md) page for help with problems you may encounter during the installation.
docs/drupal7/index.md deleted 100644 → 0
View file @ 0088bea4
???+ tldr "About this document"
This guide covers standard installation of CiviCRM on an existing Drupal 7 site. It assumes that you previously completed these tasks:
1. [Install Drupal 7](https://www.drupal.org/docs/7/install), and...
1. [Review the CiviCRM requirements](../general/requirements.md)
??? tldr "Alternative: Civibuild for developers"
If you plan to develop patches for CiviCRM on Drupal 7, then please use the [Developer Guide](https://docs.civicrm.org/dev/en/latest) for information about [Buildkit](https://docs.civicrm.org/dev/en/latest/tools/buildkit/) and [civibuild](https://docs.civicrm.org/dev/en/latest/tools/civibuild/).
<a name="directory"></a><!-- old anchor -->
## Get the code {:#download}
The [CiviCRM download page](https://civicrm.org/download) provides a pre-built archive for use with Drupal 7. A
typical archive file is ~20mb and looks like `civicrm-X.Y.Z-drupal.tar.gz`. It contains a folder named `civicrm/`.
In Drupal 7, there is a folder for storing add-on modules: `DRUPAL_ROOT/sites/all/modules`.
Our goal is to download the archive and extract into this folder. Here are a few example ways to download and extract:
??? example "Download via web-browser"
This method does not require shell access on the server. You may adapt based your server's arrangement.
* On the [CiviCRM download page](https://civicrm.org/download), click the link for CiviCRM / Drupal 7. Save the file locally.
* Extract the archive locally. For example, in a Linux workstation, one might say:
```bash
cd ~/Downloads
tar xvzf civicrm-X.Y.Z-drupal.tar.gz
```
* Observe the new folder `civicrm/`.
* Using your favor file-transfer system (SSH/SFTP, `rsync`, `git`, `mv`, etc), transfer the `civicrm/` folder
to `DRUPAL_ROOT/sites/all/modules`.
??? example "Download via curl + tar"
This method require shell access to the Drupal server.
* On the [CiviCRM download page](https://civicrm.org/download), note the current version.
* In the shell, navigate to the Drupal module folder (*adjust as appropriate*):
```bash
cd DRUPAL_ROOT/sites/all/modules
```
* In the shell, run the `curl` and `tar` commands. Adjust the version `X.Y.Z` to the appropriate value.
```bash
curl -L "https://download.civicrm.org/civicrm-X.Y.Z-drupal.tar.gz" | tar xvz
```
??? example "Download via Drupal web UI"
This is the easiest way for a new administrator. However, it may not work in all deployments or
all versions. For
example, if the Drupal server has a locked-down configuration, then it may encounter permission errors
or timeouts. The only way to find out is to try.
* On the [CiviCRM download page](https://civicrm.org/download), right-click the link for CiviCRM / Drupal 7. Copy the URL.
* Login to your Drupal site with *administrator* permissions.
* Navigate to **Modules >> Install new module**.
* Paste the URL
* Click "Install"
??? warning "This may not work with CiviCRM 5.13-5.30"
In CiviCRM versions 5.13 - 5.30, the prebuilt tarball included a symlink which is not accepted by
the Drupal 7 installer. This should work again in 5.31.
<!-- TODO: After 5.31 has been out for a while, we can move this option higher up and remove/downgrade the notice. -->
??? warning "The "Upload"/"Browse" option is unlikely to work."
The **Install new module** page provides another option for uploading the archive from your local computer.
In a default PHP configuration, the upload limits are too conservative to accept the CiviCRM archive.
In all cases, the final outcome should be the creation of a new folder
```
DRUPAL_ROOT/sites/all/modules/civicrm
```
## Get the translations {:#i18n}
The basic CiviCRM release includes support for US English (`en_US`). To use another language or dialect, please [download and extract the translation files](../general/i18n_l10n.md).
## Run the installer {:#installer}
The installer verifies requirements, prepares the database, and initializes the configuration file. You may run the installer through the web interface (*which is simpler*) or the command-line interface (*which has more options*).
??? example "Run installer via Drupal 7 web UI"
1. Enable the "CiviCRM" module
* Login to your Drupal site with *administrator* permissions.
* Navigate to the "Modules" page (`admin/modules`).
* Find "CiviCRM" and enable it.
* At the bottom, click "Save Configuration".
2. After enabling, the status message will display a link to "configure CiviCRM". Click it.
??? question "What if I didn't notice the link?"
Use the URL bar. Navigate to the `civicrm` page (e.g. `https://example.com/civicrm`).
3. The CiviCRM installer will open.
* *If there are unmet requirements*, the installer will list them. Consult the [Requirements](../general/requirements.md) documentation for additional advice.
* *If all the requirements are met*, proceed through the brief questionnaire.
* *If you have [a separate MySQL database for CiviCRM](../general/requirements.md#mysql-connection)*, then locate "Environment: CiviCRM Database". Click the edit icon and enter the [database URL](../general/requirements.md#mysql-connection).
* Finally, click "Install CiviCRM".
??? example "Run installer via the command-line"
CiviCRM has a command-line administration tool, `cv`, which can perform installation. For details, see [command-line installer](../general/cli-cv.md).
## Review the permissions {:#permissions}
!!! check ""
Note that Drupal tries to create the `/files/` directory (and make it writeable), but only when saving `admin/settings`. Same holds for `/temp` directory, and a `/uploads/` directory in the CiviCRM module root. On a brand-new Drupal install, this directory may be missing. Even on an existing installation, if file permissions are not set properly, the directory may be missing. If enabling the **CiviCRM** module generates errors regarding the files directory, you must create it (writeable) manually.
* Go to the CiviCRM dashboard to see the CiviCRM menus:
`https://example.org/civicrm` (or `https://example.org/index.php?q=civicrm` if you don't have Clean URLs enabled)
* Go to **Administer » User management » Permissions**
* Verify that the Roles that you want to have access to CiviCRM have the appropriate permissions checked. CiviCRM is installed with a number of fixed permissions (such as "edit contacts" and "administer CiviCRM").
<!-- markdownlint-disable MD046 -->
!!! tip "Permissions for the Anonymous Role"
Many sites want anonymous visitors to have access to certain CiviCRM functionality. These permissions are enabled during installation for the Anonymous role. You should review them and modify if needed based on your requirements:
* **access all custom data** : If you plan on collecting "custom" data from visitors in standalone forms or as they make a contribution - enable this permission.
* **access CiviMail subscribe/unsubscribe pages** : If you are planning on using CiviMail, enable this permission to allow anonymous users to subscribe and unsubscribe from mailing lists via the web.
* **access uploaded files** : If you plan on allowing visitors to upload or view photos or other files - enable this permission.
* **make online contributions** : If you plan on soliciting online contributions from visitors, enable this permission for the "anonymous" role.
* **profile listings and forms** : If you plan on collecting name and address or other information from visitors, enable this permission for the "anonymous" role.
* **view event info** and **register for events** : If you plan to use CiviEvent and want to allow un-authenticated visitors to view event information and register for events online - enable these permissions for the "anonymous" role.
* **view event participants** : Enable this permission to allow anonymous users to access participant listing pages for events.
<!-- markdownlint-enable MD046 -->
## Synchronize the users {:#contacts-users}
Once installed, CiviCRM keeps your Drupal Users synchronized with corresponding CiviCRM contact records. The 'rule' is that there will be a matched contact record for each Drupal user record. Conversely, only contacts who are authenticated users of your site will have corresponding Drupal user records.
When CiviCRM is installed on top of an existing Drupal site, a special CiviCRM Administrative feature allows you to automatically create CiviCRM contacts for all existing Drupal users:
* Login to your Drupal site with an administrator-level login
* Click the **CiviCRM** link in the main navigation block
* If your Drupal site makes use of the `db_prefix` setting (in `settings.php`), in the top bar click **Administer » System Settings » CMS Database Integration** , and update the box for the Drupal Users Table Name so that it includes the prefix.
* Click **Administer** in the menu bar
* Click **Users and Permissions** from the drop-down menu, then select **Synchronize Users to Contacts**
## Review the checklist {:#checklist}
The **Configuration Checklist** provides a convenient way to work through the settings that need to be reviewed and configured for a new site. You can link to this checklist from the installation success page AND you can visit it at any time from **Administer** » **Administration Console** » **Configuration Checklist**.
## Test-drive CiviCRM {:#test-drive}
There should now be a **CiviCRM** link in your Drupal menu. Click that link and the CiviCRM Menu, Shortcuts, Search and New Individual Blocks should appear. You can now explore CiviCRM end-user features and begin configuring CiviCRM for your site/organization needs.
## Addenda
### TLS for MySQL
If your MySQL database is hosted on a different machine than your web server, or if your host requires it, you can use TLS to encrypt the connection between the database and the web server.
Full instructions on installing drupal are out of scope for this guide, but one method is to install into a test database first without MySQL encryption and then move the database to the live server and update settings.php to enable MySQL encryption.
See [TLS for MySQL](../general/mysql_tls.md) for introductory concepts and the settings for the CiviCRM database. For the Drupal database you have several options for updating settings.php:
1. The simplest, which doesn't require a client certificate, but doesn't verify the server certificate.
``` php
$databases = array (
'default' =>
array (
'default' =>
array (
'database' => 'drupal',
'username' => 'dbuser',
'password' => 'dbpassword',
'host' => 'db435.examplehost.com',
'port' => '',
'driver' => 'mysql',
'prefix' => '',
'pdo' => array(
PDO::MYSQL_ATTR_SSL_CA => TRUE,
PDO::MYSQL_ATTR_SSL_VERIFY_SERVER_CERT => FALSE,
),
),
),
);
```
2. Verifies the server certificate, and doesn't require a client certificate.
!!! warning "Host name must match certificate name"
Note that the DATABASE SERVER certificate would have to have a CN (common name field) that matches exactly the `host` you are using in `$databases['default']['default']['host']`. So if the host is `db435.examplehost.com`, then that must be the name on the SERVER certificate.
``` php
'pdo' => array(
// A certificate authority bundle.
// If you are using a self-signed server certificate in a development
// or testing environment, then this would be the same as the server
// certificate.
PDO::MYSQL_ATTR_SSL_CA => '/path/to/ca.crt',
),
```
3. Client certificate/key pair (not self-signed), and do not verify the server certificate.
``` php
'pdo' => array(
PDO::MYSQL_ATTR_SSL_VERIFY_SERVER_CERT => FALSE,
PDO::MYSQL_ATTR_SSL_KEY => '/path/to/your.key',
PDO::MYSQL_ATTR_SSL_CERT => '/path/to/your.crt',
),
```
4. Client certificate/key pair (could be self-signed), and verify the server certificate.
``` php
'pdo' => array(
// The SSL_CA can be the same as your.crt if self-signed, but note
// that it would also have to be a certificate authority for the
// server certificate. Self-signed would only be for local
// development testing.
PDO::MYSQL_ATTR_SSL_CA => '/path/to/ca.crt',
PDO::MYSQL_ATTR_SSL_KEY => '/path/to/your.key',
PDO::MYSQL_ATTR_SSL_CERT => '/path/to/your.crt',
),
```
### Troubleshooting {:#troubleshooting}
* Review the [Troubleshooting](../general/troubleshooting.md) page for help with problems you may encounter during the installation.
* To check compatibility with other Drupal modules see: [Drupal modules incompatible with CiviCRM](https://docs.civicrm.org/sysadmin/en/latest/integration/drupal/incompatibilities/)
docs/drupal8/index.md deleted 100644 → 0
View file @ 0088bea4
This diff is collapsed.
docs/general/cli-cv.md
View file @ 45f46fb1
......@@ -6,7 +6,7 @@
1. Install a supported CMS
1. [Review the CiviCRM requirements](../general/requirements.md)
1. Download the CiviCRM code. (See "*Get the code*" for [Backdrop](../backdrop/index.md#download), [Drupal 7](../drupal7/index.md#download), [Drupal 8](../drupal8/index.md#download), [Drupal 9](../drupal8/index.md#download), or [WordPress](../wordpress/index.md#download)).
1. Download the CiviCRM code. (See "*Get the code*" for [Backdrop](../backdrop/index.md#download), [WordPress](../wordpress/index.md#download) or [Drupal](../drupal/index.md)).
??? tldr "Limitations"
......@@ -120,6 +120,17 @@ There are several available options for the installer. Expand the topics below f
__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
......@@ -158,6 +169,9 @@ The installer may report a problem. Some common ones are:
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/).
......
docs/general/i18n_l10n.md
View file @ 45f46fb1
## Coming Soon
## 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 ""
This page is a placeholder for content being migrated in from the old Wiki.
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/requirements.md
View file @ 45f46fb1
......@@ -9,9 +9,9 @@ If you are curious what technologies other organizations are using to run CiviCR
A recommended server environment should typically meet these guidelines:
* __Operating system__: Linux
* __CMS__: Backdrop, Drupal 7, Drupal 8/9, Joomla, or WordPress
* __PHP__: 7.2, 7.3, 7.4 -- with configuration and extension requirements. Php 8 is supported from 5.40.
* __MySQL__: MySQL 5.7.5+ or MariaDB 10.0.0.2+ -- with configuration requirements
* __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.
......@@ -25,56 +25,54 @@ If your server meets all of the requirements described on this page, CiviCRM *sh
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).
### Optional Libraries
Some people report better performance in some circumstances when rendering PDF files (e.g. reports or invoices). CiviCRM has a configuration option to use a system binary for WKHTMLtoPDF. [https://wkhtmltopdf.org/](https://wkhtmltopdf.org/) You can find this setting under "System Settings" > "Misc".
Another reason to use it is that is solves [the issue](unicode_pdf.md) of how to handle unicode fonts needed for some languages.
## 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 8/9](../drupal8/index.md)
* [Drupal 7](../drupal7/index.md)
* [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](../joomla/index.md) 3.x.x is required.
* [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) 4.9 or newer is required.
* [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. Using PHP 7.1 (or lower) on the command line and using PHP 7.2 (or higher) on the web server can cause issues.
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 on the command line and the web server.
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
| | CiviCRM 5.39 ESR | CiviCRM 5.x.x stable |
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.1 | **incompatible** | **incompatible** as not yet confirmed to work on test matrix |
| PHP 8.0 | compatible however not **recommended** yet until the extension ecosystem catches up. | compatible from CiviCRM 5.39 however not **recommended** yet until the extension ecosystem catches up. |
| PHP 7.4 | compatible and **recommended** | compatible and **recommended** |
| 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 | **incompatible** as of 5.35.0 |
| PHP 7.0 | **incompatible** | **incompatible** as of 5.25.0 |
| PHP 5.6 | **incompatible** | **incompatible** |
| 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:
......@@ -89,7 +87,8 @@ It is also important to ensure that the same PHP extensions/modules are loaded o
| 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 - current | 7.3 | 7.4 |
| 5.46 - 5.69 | 7.3 | 7.4 |
| 5.70 - 5.81 | 7.4 | 8.1 |
### PHP Extensions
......@@ -103,20 +102,12 @@ To install these extensions, you will typically install a separate package withi
* [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 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. From CiviCRM 5.34 onwards MCrypt is no longer needed.
!!! 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
The following PHP directives is the recommended minimum. These are defined in the [php.ini file](https://www.php.net/manual/ini.list.php).
......@@ -139,7 +130,7 @@ 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.
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:
......@@ -148,11 +139,12 @@ Your MySQL version should be **5.7.5 or greater** or MariaDB **10.0.2 or greater
| ------------------------ | --------------------- | ------------------------- | ----------------------- | ------------------- |
| 5.26 - 5.27 | 5.5 | 5.7 | | |
| 5.28 - 5.33 | 5.6.5 | 5.7 | | 10.4 |
| 5.34 - Current | 5.7 | 5.7 | 10.0.2 | 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), [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), All versions of [Drupal 9](https://www.drupal.org/docs/9/system-requirements/database-server) support MySQL 8, Current versions of WordPress and [Joomla](https://docs.joomla.org/Joomla_and_MySQL_8) appear to be compatible with 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}
......@@ -199,6 +191,7 @@ Additional URL parameters may be added to support [MySQL with TLS](mysql_tls.md)
* 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.
......@@ -234,7 +227,9 @@ Additional URL parameters may be added to support [MySQL with TLS](mysql_tls.md)
skip-log-bin
```
#### MySQL Time
### 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:
......@@ -242,9 +237,74 @@ CiviCRM performs various operations based on dates and times – for example, de
* 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/PHP Time Mismatch Warning - WordPress
!!! 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:
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`.
* 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
......
docs/general/troubleshooting.md
View file @ 45f46fb1
......@@ -71,14 +71,18 @@ If you get this error on a new Drupal/CiviCRM installation, you may have skipped
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
### Page doesn't reload and spinner shows when tryibng to re-create triggers, eventually showing "DB Error: unknown error"
Try [rebuilding the WordPress menus](#rebuild-wp-menus).
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}
......
docs/general/unicode_pdf.md
View file @ 45f46fb1
# Using non-latin characters in PDF output
# Using your own font or CJK characters in PDF output
There are certain places in CiviCRM where PDF output will contain `?` instead of the appropriate character because the DejaVu unicode font files have been removed from the DOMPDF library. For example CiviCRM uses DOMPDF when producing PDF copies of CiviReports, but it uses a different library (TCPDF) for Mailing Labels, which does have the DejaVu fonts.
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.
In Drupal 8/9, the entire DOMPDF library is downloaded during install, so it will work with most unicode characters as-is. 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.
Note when testing to see if you've succeeded, use letters that are entirely outside the character set included in the basic font files, e.g. use cyrillic letters such as `д`. Several letters like `ü` will work either way so aren't a good test.
## Option A: Using web fonts
??? example "Option A: Install the unicode font files for DOMPDF"
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>`
1. Download the dompdf zip file from the [github repository](https://github.com/dompdf/dompdf/releases).
1. Create a folder in a location that won't get overwritten when you upgrade, e.g. sites/default/fonts for Drupal.
1. Extract all the DejaVu files, including the DejaVu-XXX.ufm files as well as the .ttf files, from the lib/fonts subfolder in the zip file into the folder you created.
1. In the folder you created, create a file called `dompdf_font_family_cache.php` and put this in it. Don't replace `$fontDir` with anything leave it as that variable.
```
<?php return [
'dejavu sans' => [
'bold' => $fontDir . '/DejaVuSans-Bold',
'bold_italic' => $fontDir . '/DejaVuSans-BoldOblique',
'italic' => $fontDir . '/DejaVuSans-Oblique',
'normal' => $fontDir . '/DejaVuSans',
],
'dejavu sans mono' => [
'bold' => $fontDir . '/DejaVuSansMono-Bold',
'bold_italic' => $fontDir . '/DejaVuSansMono-BoldOblique',
'italic' => $fontDir . '/DejaVuSansMono-Oblique',
'normal' => $fontDir . '/DejaVuSansMono',
],
'dejavu serif' => [
'bold' => $fontDir . '/DejaVuSerif-Bold',
'bold_italic' => $fontDir . '/DejaVuSerif-BoldItalic',
'italic' => $fontDir . '/DejaVuSerif-Italic',
'normal' => $fontDir . '/DejaVuSerif',
],
];
```
1. Visit Administer - System Settings - Misc and in the field for `DOMPDF Font Folder` put the full path to the font folder you created.
1. When composing the PDF, if you have pasted from Microsoft Word into CKEditor it might set a specific font and then you will still see `?` in the output. You can click the Source button on the CKEditor toolbar to check - look for e.g. `<p style="font-family: Arial;">`.
## Additional steps for CJK or an alternate unicode font
1. You will need to use the `load_font` utility from https://github.com/dompdf/utils. Download and extract it into some temporary folder.
1. Edit [the require line](https://github.com/dompdf/utils/blob/d9049f5b5df23b4e97b332a81205b5bb5ae1fbcc/load_font.php#L3) near the top of the `load_font.php` file and set it to the path to your CiviCRM installation's `vendor/autoload.php`.
1. Uncomment and edit [the $fontDir line](https://github.com/dompdf/utils/blob/d9049f5b5df23b4e97b332a81205b5bb5ae1fbcc/load_font.php#L9) near the top of the `load_font.php` file and set it to the fonts folder you created earlier for DejaVu.
1. Copy the .ttf font file you want to use into the folder where `load_font.php` is.
1. Run `php load_font.php font_name font_file.ttf`, where you replace the last two as appropriate for the font you are installing, e.g. `php load_font.php SimSun simsun.ttf`.
1. Note this will overwrite the `dompdf_font_family_cache.php` file you created earlier for DejaVu, so to also have DejaVu you will now need to edit the file and copy the php array from earlier back in.
1. Now you no longer need the `load_font` utility or its folder and can delete it.
1. Unlike with DejaVu which CiviCRM sets as the default font, you will need to specify the font when composing the PDF in the places 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>`
## Option B: Storing fonts locally
??? example "Option B: Install wkhtmltopdf instead"
This may also have an advantage for reports that cause DOMPDF to run out of memory. A possible disadvantage is the output may not be exactly the same or as well tested with CiviCRM as DOMPDF since it is not the default. You only need to do this once.
1. Your operating system's package manager may already make it available to install. If not then go to https://wkhtmltopdf.org and download the file for your operating system.
1. Note the full path to the executable binary.
1. In CiviCRM go to Administer - System Settings - Misc.
1. A couple lines down there is a setting `Path to wkhtmltopdf executable`.
1. Fill it in, e.g. `/usr/local/bin/wkhtmltopdf`
1. Click the Save button.
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/planning/cms.md
View file @ 45f46fb1
......@@ -4,7 +4,8 @@ CiviCRM works with several popular open source Content Management Systems (CMS).
* Backdrop CMS
* Drupal 7
* Drupal 8
* Drupal 9 (Reached [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 10
* Joomla
* WordPress
......@@ -29,8 +30,8 @@ Support for running CiviCRM with WordPress was added in 2012, which allowed Word
Broadly there are some differences which arise because of distinctive features/norms in each CMS community, e.g.
* In WordPress, it's pretty common to embed content in your web-pages using short-codes. CiviCRM has several short-codes in WP.
* In Backdrop CMS/Drupal 7/Drupal 8, it's pretty common to embed content in your web-pages using blocks. CiviCRM has several blocks in Drupal.
* In Backdrop CMS/Drupal 7/Drupal 8, CiviCRM makes use of the CMS's "roles" and "permissions" using the CMS's interfaces and approaches, and there are modules to synchronize CiviCRM groups and membership types to them.
* In Backdrop CMS/Drupal 7/Drupal 9/Drupal 10, it's pretty common to embed content in your web-pages using blocks. CiviCRM has several blocks in Drupal.
* In Backdrop CMS/Drupal 7/Drupal 9/Drupal 10, CiviCRM makes use of the CMS's "roles" and "permissions" using the CMS's interfaces and approaches, and there are modules to synchronize CiviCRM groups and membership types to them.
* In Joomla/WordPress, "roles" and "permissions" can also be managed using the CMS's interfaces and approaches, and there are plugins to synchronize groups and membership types to them.
## Installation Process
......@@ -43,7 +44,7 @@ The core system is the same across all CMS options, but occasionally there are b
The size of the install base shown [on the CiviCRM Stats site](https://stats.civicrm.org/?tab=sites) also affects how well reported issues are and how quickly fixes are tested and merged. While trends are subject to change, as of 2019, Joomla shows the least growth and WordPress the most.
Therefore it may take a bit longer to identify/resolve bugs in the BackDrop, Drupal8, Joomla and WordPress integrations but automated testing on these platforms is being continually improved.
Therefore it may take a bit longer to identify/resolve bugs in the BackDrop, Drupal, Joomla and WordPress integrations but automated testing on these platforms is being continually improved.
The following chapters in this section go into more detail about what is offered for each CMS.
......@@ -58,7 +59,7 @@ You may also choose a CMS because you already know how to use it or it is alread
**Drupal** is the most flexible and has the best integration with CiviCRM. If you have complex CMS needs or envisage a lot of interaction between users on your website and your CRM, then Drupal might be the CMS for you. The main negative is that this flexibility makes it harder for new site builders to get to grips with.
**Backdrop CMS** is very similar to Drupal 7, with many improvements making it slick and lightweight. It started as a fork (that is, a copy) of Drupal 7, aimed at users for whom Drupal 8 was likely to be too complex either to use, or to migrate to from Drupal 7. Drupal 7 modules and themes require modifications to work with Backdrop CMS, though many have already been ported and are actively maintained.
**Backdrop CMS** is very similar to Drupal 7, with many improvements making it slick and lightweight. It started as a fork (that is, a copy) of Drupal 7, aimed at users for whom Drupal 9 or Drupal 10 was likely to be too complex either to use, or to migrate to from Drupal 7. Drupal 7 modules and themes require modifications to work with Backdrop CMS, though many have already been ported and are actively maintained.
**Joomla** isn't as popular as WordPress, though it is more popular than Drupal. Joomla is easier to learn than Drupal. The amount of integration available is lower than then when using Drupal.
......
docs/standalone/index.md 0 → 100644
View file @ 45f46fb1
!!! tip "New release"
Standalone is a new way to use CiviCRM. You can help continue to improve it by reporting any issues you experience [on the issue tracker](https://lab.civicrm.org/dev/core/-/issues/?label_name%5B%5D=comp%3AStandalone).
???+ tldr "About this document"
This guide covers installation of CiviCRM Standalone (without a parent CMS). It assumes that you previously
[reviewed the CiviCRM requirements](../general/requirements.md).
## Step 1. Choose an install method
There are currently five options for installing CiviCRM Standalone. If in doubt, Option 1 is the recommended method for most sites.
??? example "Option 1. Download a release tarball - most sites"
This is the recommended install method for most regular sites. The rest of this page assumes you are installing this way.
??? example "Option 2. Use composer - complex sites"
Using composer allows more automated management of site installation and packages. It may be useful in some contexts, such as automated deployments. It requires shell access and is *not* recommended if you are new to CiviCRM.
??? example "Option 3. Using CiviCRM Buildkit - for developers"
If you are a developer contributing to CiviCRM Core, then it is recommend to use [CiviCRM Buildkit](https://docs.civicrm.org/dev/en/latest/tools/buildkit/) to create Standalone sites. The primary site template is called `standalone-clean`. A composer-style alternative is called `standalone-composer`.
Using Buildkit is only recommended for test sites. If you are hoping to run CiviCRM Standalone in production in future, you should follow Option 1 or 2.
??? example "Option 4. Download with git - not recommended"
You can also install CiviCRM Standalone by cloning the git repo directly. This is generally not recommended - if you need git it is probably easier to use Buildkit.
??? example "Option 5. Using Docker"
If you have used Docker before, this can be a quick way to get up and running. You can find install instructions [on the project repo](https://github.com/civicrm/civicrm-docker)
The rest of this page assumes you are installing from a release tarball (Option 1).
## Step 2. Get the code {:#download}
The latest release is available from [the main release page](https://civicrm.org/download). Select "Download CiviCRM 5.x.x" from the download options.
[Download this month's release](https://download.civicrm.org/latest/civicrm-STABLE-standalone.tar.gz)
The release contains all the code for your site in a compressed tarball file (`.tar.gz`).
??? error "Pre-release versions"
Pre-release versions are available to download from [the latest releases page](https://download.civicrm.org/latest/).
Choose the option that ends `*-RC-standalone` for the latest Release Candidate (RC) for next month's release. Testing the RC will help improve the stability of the next month's release.
Choose the option that ends `*-NIGHTLY-standalone` for the latest Nightly Build. This is the very latest version available, but be warned, there may be bugs! 🐛
## Step 3. Deploy the code to your web server/hosting {:#download}
At this step you need to extract the code and transfer it your web server.
If you are using web hosting, you may be able to upload the compressed file and then extract it, or extract it on your computer and then upload the extracted files. It depends a bit on your hosting configuration.
The key thing is to maintain the folder structure from the release archive. Your main folder should contain at least a `civicrm.standalone.php` file, as well as `core`, `public` and `private` subfolders.
You need to make sure this folder is located somewhere your webserver can point to it. Take a note of this folder path (e.g. `/var/www/example.org` or `/mywebhost/user123124019231/sites/civicrm`) as you will need it later.
Note: you should point a domain or subdomain directly at the Standalone project root. Installing to a URL subdirectory (e.g. https://mysite.com/projects/standalone) is not currently supported.
??? info "More detail: CiviCRM Standalone folder structure"
Standalone sites should have a main folder which in Standalone is known as the _"project root"_.
After the system has been fully installed and used, you can expect the contents of that folder to look like this:
| File/Folder | Contents |
| -- | -- |
| `civicrm.standalone.php` | Standalone boot file. This identifies the Standalone Project Root, and identifies the locations of the CiviCRM code and settings files. |
| `core/` | Core source code for CiviCRM |
| `private/` | Private site files which should not be accessible over the web |
| `private/civicrm.settings.php` | Configuration file with low level settings for CiviCRM. |
| `private/log/` | Log files |
| `private/cache/` | Cache files for CiviCRM's template compiler |
| `private/l10n/` | Translation files |
| `private/attachment/` | Private files uploaded to your CiviCRM site - such as files uploaded to a specific contact |
| `public/` | Public site files which *should* be accessible over the web |
| `public/media/` | Public files uploaded to your site, like images that appear on a contribution page or in a mass email |
| `public/ang/` | Angular templates - e.g. for custom forms added to your site with FormBuilder |
| `ext/` | CiviCRM extensions you have added to your site |
<!-- FIXME: Describe more items from `web/upload/` -->
## Step 4. Get translations if needed {:#i18n}
The default CiviCRM language is US English (`en_US`). You can select a different language or locale during the web installation step, and the chosen translations will be downloaded for you. You don't need to do anything now.
Alternatively, if you need the web installer in another language you can manually download all the translation files now.
Head to https://civicrm.org/download and choose "Internationalisation files" from the Download dropdown, then copy the `l10n` directory from the download into the `private` directory of your site (so you should end up with folders like `private/l10n/es_ES`).
## Step 5. Configure MySQL {:#mysql}
CiviCRM stores data in MySQL (or, equivalently, MariaDB). You will need to provide a new database and determine key details:
* MySQL hostname/IP (*and, optionally, port number*)
* MySQL database name
* MySQL username
* MySQL password
??? example "_MySQL_: Set up a new database on your webhosting"
If you are using a webhost, they will often provide a UI for this, from which you can get these details.
Alternatively, they may provide _phpmyadmin_ or _cpanel_ access to your database server. You can find guides for these tools online, e.g. https://phppot.com/mysql/phpmyadmin-create-database/ or https://support.cpanel.net/hc/en-us/articles/360057550753-How-to-create-a-database-and-database-user-in-cPanel
<!-- Might be good to have more specific pointers for phpmyadmin or cpanel? -->
??? example "_MySQL_: Create database via command-line"
Open the `mysql` command-line interface. You may need to run one of these commands:
```bash
mysql
mysql -u root
mysql -u root -p
mysql -u root -p --host=db.example.com --port=3306
```
This should display a welcome message:
```
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 6879
Server version: 8.0.29 Source distribution
Copyright (c) 2000, 2022, Oracle and/or its affiliates.
Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective
owners.
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
mysql>
```
Now, you can configure a database (`civicrm`), user (`civicrm`), and password (`__TOP_SECRET__`):
```sql
mysql> CREATE DATABASE civicrm CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
Query OK, 1 row affected (0.00 sec)
mysql> CREATE USER 'civicrm'@'localhost' IDENTIFIED BY '__TOP_SECRET__';
Query OK, 0 rows affected (0.01 sec)
mysql> GRANT ALL on civicrm.* to 'civicrm'@'localhost';
Query OK, 0 rows affected (0.01 sec)
```
## Step 6. Configure your webserver {:#webserver}
Now you need to configure your webserver to point to your CiviCRM Standalone project folder.
The exact steps vary based on your specific environment. Here are some typical tasks for common environments:
??? example "_Web hosting_: Point a new subdomain to your Standalone project folder"
If you are using web hosting and your release code is in e.g. `/mywebhost/user123/my-sites/civicrm`, then you should just need to point a domain or subdomain from your hosting to this directory.
You will need to make sure PHP is enabled, including the php modules detailed in the Installation Requirements. Your web host may provide a UI, or you may need to add a `php.ini` file specifying options.
You should specify that the `private` folder should *not* be web accessible.
??? example "_Apache_: Configure a virtual-host on Debian-based server"
If you created a folder like `/var/www/example.com/web`, then you probably need to configure the web-server to read this folder.
The essence is to create a configuration file underneath `/etc/apache2/sites-*` with a `<VirtualHost>` declaration, such as:
```
<VirtualHost *:80>
ServerAdmin me@example.com
DocumentRoot /var/www/example.com/web
ServerName example.com
...
</VirtualHost>
```
For a complete example, see [Installing virtual hosts for Drupal sites](https://www.drupal.org/node/111238). (This example is for Drupal,
but similar steps should work for CiviCRM Standalone - simply adjust the `DocumentRoot` and `ServerName`.)
??? example "_nginx_: Configure a virtual-host on Debian-based server"
An example starting point for nginx virtual host configuration is available in the [CiviCRM Standalone repository](https://github.com/civicrm/civicrm-standalone).
## Step 7. Configure webserver permissions {:#webserver}
Your webserver will need to be able to write to at least your `public` and `private` directories. If you wish to install extensions through the web UI on your site, the webserver will also need to write to the `ext` directory.
On many webhosts the webserver will be able to write to all directories, and you won't need to do anything.
If you have `ssh` access to your server, you may need to set the user permissions directly.
??? example "_Permissions_: Grant write access to `public`, `private` and `ext` directories on Linux server"
In most Linux distributions, the web server runs with a special user+group (such as `www-data` or `www`).
You must specifically grant access for this user to write to data folders. Typically you will want to grant access for the group `www-data` to `private`, `public` and `ext` folders.
```bash
cd /var/www/example.com/web
chmod 2770 private public ext
chmod g+rwX -R private public ext
chgrp -R www-data private public ext
```
<!-- Should we recommend `setfacl` (Linux) and `chmod +a` (MacOS)? Or is this assuming that current-user is also in `www-data`? -->
<!-- These are the configs I've liked: https://github.com/amp-cli/amp/blob/0.7.3/app/defaults/services.yml#L189-L199 -->
## Step 8. 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 web UI"
1. Head to the `/civicrm` page on your website. This may look like:
* `https://example.com/civicrm`
* `http://localhost:8000/civicrm`
* `http://example.127.0.0.1.nip.io:8001/civicrm`
2. The CiviCRM installer will open.
* You will need to provide the details for the database you created earlier
* You also have to provide a username, password and e-mail address for the site adminstrator user. Note: this login is totally separate from the database username and password in step 1.
* *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 questionnaire.
* You can select another language if you want CiviCRM to be installed in another language then English US. The installer will then download the translation files for you.
* Finally, click "Install CiviCRM".
3. After installing, you should see a confirmation page confirming installation has completed correctly.
??? example "Run installer via command-line"
CiviCRM has a command-line administration tool, `cv`, which can perform installation. For a local dev site, a typical install command might be:
```bash
cd /path/to/standalone-service-root
cv core:install -v \
--cms-base-url=http://localhost:8000 \
--db=mysql://USER:PASS@HOST:PORT/DATABASE \
-m extras.adminUser=USERNAME \
-m extras.adminPass=SECRET \
-m extras.adminEmail=ME@EXAMPLE.COM
```
For full 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).
<!-- Do we need to suggest reviewing permissions at the start -- given that we control defaults and given that there's a general checklist? -->
## Log in and review users and permissions {:#users}
You should now be able to log in to your site at e.g. `https://your-site.test/civicrm/login`. Use the administrator username and password you created during install.
Head to **Adminster** >> **Users and Permissions** to configure users and roles for your site.
## 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}
Start exploring your new CiviCRM Standalone site. Please report any issues you find in the Issue Tracker: https://lab.civicrm.org/dev/core/-/issues/?label_name%5B%5D=comp%3AStandalone
## Addenda
### Troubleshooting {:#troubleshooting}
* Review the [Troubleshooting](../general/troubleshooting.md) page for help with problems you may encounter during the installation.
mkdocs.yml
View file @ 45f46fb1
site_name: CiviCRM Installation Guide
site_url: https://docs.civicrm.org/installation/en/stable/
site_url: https://docs.civicrm.org/installation/en/latest/
repo_url: https://lab.civicrm.org/documentation/docs/installation/
edit_uri: https://lab.civicrm.org/documentation/docs/installation/-/edit/master/docs/
site_description: This guide is aimed at CiviCRM users and implementors who would like to learn how to install and setup CiviCRM.
......@@ -28,10 +28,10 @@ markdown_extensions:
nav:
- Home: index.md
- Install CiviCRM on Backdrop: backdrop/index.md
- Install CiviCRM on Drupal 7: drupal7/index.md
- 'Install CiviCRM on Drupal 8/9': drupal8/index.md
- Install CiviCRM on Drupal: drupal/index.md
- Install CiviCRM on Joomla: joomla/index.md
- Install CiviCRM on WordPress: wordpress/index.md
- "Install CiviCRM (Standalone)": standalone/index.md
- General:
- Requirements: general/requirements.md
- Permissions: general/permissions.md
......
redirects/.gitkeep 0 → 100644
View file @ 45f46fb1
redirects/internal.txt 0 → 100644
View file @ 45f46fb1
drupal7 drupal