Skip to content
Snippets Groups Projects
Commit cce2f79f authored by homotechsual's avatar homotechsual
Browse files

First pass on Installation Guide

parent 3872e796
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 1381 additions and 0 deletions
docs/backdrop/index.md 0 → 100644
+ 131
− 0
View file @ cce2f79f
## 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.
## Trouble-shooting Resources {:#troubleshooting}
* Review the [Troubleshooting](../troubleshooting.md) page for help with problems you may encounter during the installation.
docs/drupal7/index.md 0 → 100644
+ 135
− 0
View file @ cce2f79f
## 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.
## 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 0 → 100644
+ 123
− 0
View file @ cce2f79f
## 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.
## 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 8 where to find the CiviCRM Module {:#directory}
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.1`. 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!
<!-- markdownlint-enable MD046 -->
To require the CiviCRM libraries on a Drupal 8 site you can use the following one-line command:
* `composer require civicrm/civicrm-asset-plugin:'~1.0.0' civicrm/civicrm-{core,packages,drupal-8}:'~5.27.1'`
## Install localization files (only for non-English sites) {:#i18n}
!!! warning "I18n & L10n on Drupal 8"
It's currently only possible to install CiviCRM in English (US) on Drupal 8 and 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.
## Run the Installer {:#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`.
* 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?"
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 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.
## 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.
## 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/general/i18n_l10n.md 0 → 100644
+ 4
− 0
View file @ cce2f79f
## Coming Soon
!!! note ""
This page is a placeholder for content being migrated in from the old Wiki.
docs/general/permissions.md 0 → 100644
+ 4
− 0
View file @ cce2f79f
## Coming Soon
!!! note ""
This page is a placeholder for content being created to help configure filesystem permissions for CiviCRM.
docs/general/requirements.md 0 → 100644
+ 201
− 0
View file @ cce2f79f
# 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.21 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 | compatible but **not recommended** due to to [PHP end-of life](http://php.net/eol.php) in Dec 2018 | 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.26 the minimum install version for CiviCRM is 5.5, users on versions before that are advised to upgrade their MySQL instance to a recommended version. CiviCRM may not run correctly on MySQL 5.5 and/or 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).)
docs/general/troubleshooting.md 0 → 100644
+ 174
− 0
View file @ cce2f79f
## 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**
docs/images/backtrace.png 0 → 100644
+ 0
− 0
View file @ cce2f79f
docs/images/backtrace.png

310 KiB

docs/images/clean-up-caches.png 0 → 100644
+ 0
− 0
View file @ cce2f79f
docs/images/clean-up-caches.png

35.3 KiB

docs/images/fatal-error.jpg 0 → 100644
+ 0
− 0
View file @ cce2f79f
docs/images/fatal-error.jpg

21.1 KiB

docs/images/wp-permalinks.png 0 → 100644
+ 0
− 0
View file @ cce2f79f
docs/images/wp-permalinks.png

20.4 KiB

docs/joomla/index.md 0 → 100644
+ 72
− 0
View file @ cce2f79f
## 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 Joomla by referring to the [Joomla Installation Guide](https://docs.joomla.org/J3.x:Installing_Joomla) if needed.
!!! note "Path for Joomla"
The rest of these instructions assume that you have Joomla installed in `/var/www/JOOMLA_ROOT`. Adjust paths as needed.
## Download and Un-tar CiviCRM Code {:#download}
All CiviCRM code and packages used by CiviCRM (such as PEAR libraries) are included in the compressed CiviCRM distribution files ('tarballs'). Follow these steps to download and install the codebase:
* Download the appropriate tarball file from the [CiviCRM website](https://civicrm.org/download) within your browser. Tarball file-names include the CiviCRM version. For example, `civicrm-x.x.x-joomla.zip`. If you have command line access to your server, use `wget` and the URL of the file to pull a copy directly to your server. Then you can skip the next step.
* Upload this file to a folder in your root Joomla directory. Recommended location: `JOOMLA_ROOT/tmp/`.
* Unzip the package, which will create a directory called: `com_civicrm`. On cPanel, you can use the File Manager's Extract function to unzip the file you uploaded.
Note: when installing a new version over an old one, please first check [troubleshooting resources](#troubleshooting) below.
## Run the Installer {:#installer}
* Login to your Joomla Administrator site.
* Go to **Extensions >> Install/Uninstall**.
* Use **Install from Directory** and enter the full path to the un-zipped com_civicrm directory, which should be something like: `JOOMLA_ROOT/tmp/com_civicrm` . In most Joomla installations, the root directory and /tmp/ folder will already populate the "install from directory" field. You must simply add the /com_civicrm/ subfolder at the end. Click Install. If that doesn't work:
* put the full file system path to the `com_civicrm`, something like `/var/www/JOOMLA_ROOT/tmp/com_civicrm/`.
* You should see "Component successfully installed" message.
!!! warning
If you get the following error when installing or upgrading CiviCRM for Joomla - you can downloading the alternate Joomla install file - `civicrm-x.x.x-joomla-alt.zip` - which doesn't require built-in unzip functionality on your server. Then repeat the install steps starting with [running the installer](#installer).
> Your PHP version is missing zip functionality. Please ask your system administrator / hosting provider to recompile PHP with zip support.
Note that missing PHP Zip functionality *will* prevent CiviCRM from installing extensions via the GUI.
## Create CiviCRM Contacts for Existing Joomla Users {:#contacts-users}
Once installed, CiviCRM keeps your Joomla Users synchronized with corresponding CiviCRM contact records. The 'rule' is that there will be a matched contact record for each Joomla user record. Conversely, only contacts who are authenticated users of your site will have corresponding Joomla user records.
When CiviCRM is installed on top of an existing Joomla site, a special CiviCRM Administrative feature allows you to automatically create CiviCRM contacts for all existing Joomla users:
* Login to your Joomla site with an administrator-level login
* Click the **Components > CiviCRM > CiviCRM Home** link in the main navigation block
* Click **Administer > Users and Permissions > Synchronize Users-to-Contacts**
## Troubleshooting Resources {:#troubleshooting}
* If the CiviCRM component does not install correctly (for example you get a blank screen instead of the confirmation page), delete the `~/components/com_civicrm` and `~/administrator/components/com_civicrm` and `~/media/civicrm directories` manually and then try each of the following before attempting to reinstall:
* In your `php.ini` file or in `.htaccess` file in the Joomla root folder (if your server allows it), increase the `max_execution_time` to `600` and memory limit to more than 64M. Add the following to the `.htaccess` file in your Joomla root folder
<!-- markdownlint-disable MD046 -->
``` htaccess
php_value memory_limit 128M
php_value register_globals off
php_value max_execution_time 600
```
If you can't change the `.htaccess` file you can add a php.ini (or `.user.ini`) file in Joomla root folder or all directories, depending on your web server or hosting company.
``` ini
memory_limit = 128M
register_globals = off
max_execution_time = 600
```
<!-- markdownlint-enable MD046 -->
* CiviCRM is packaged with all the libraries (PEAR etc) that it uses. However a misconfigured or overly restrictive `open_basedir` directive on your web server might interfere with CiviCRM's ability to access some required files or directories. To turn `open_basedir` off, add this to your `vhost.conf` file: `php_admin_value open_basedir none` or ask your host to either turn it off or ensure that it is not preventing access to required directories (e.g. if you move configuration files or temp folders outside your web root). The configuration of sub domains might cause related issues: try installing in the main domain root or a sub folder instead.
* If CiviCRM screens are not displaying properly and/or javascript widgets are not functioning, check your CiviCRM Resource URL (Administer >> System Settings >> Resource URLs). For Joomla installs, it should be something like: `http://example.org/administrator/components/com_civicrm/civicrm`
* Review the [Troubleshooting](../general/troubleshooting.md) page for help with problems you may encounter during the installation.
docs/planning/cms.md 0 → 100644
+ 72
− 0
View file @ cce2f79f
In general you should probably choose a CMS because you already know how to use it or it is already used by your organisation. Each CMS has different advantages and disadvantages and different people will give you views on which is better. This chapter is aimed at giving you the requisite information to choose the best CMS for you.
CiviCRM works with several popular open source Content Management Systems (CMS).
* Backdrop CMS
* Drupal 7
* Drupal 8
* Joomla
* WordPress
There are lots of resources that help guide organizations in their selection of the best CMS for their content strategy and website.
The choice of which CMS to use with CiviCRM is generally appropriately determined by factors other than differences in how CiviCRM integrates with each CMS. For example, your website may already be built using one of these CMS and there may be no need to go to the expense and hassle of reimplementing it in a different CMS. Or your CMS project may have good reasons for preferring one CMS over another. This page discusses how there may be some factors relating to your use of CiviCRM that may affect or be crucial to your decision on which CMS to use, even if many organizations find these points do not play a significant role.
Before starting a project you should consider how you plan to use CiviCRM both now and in the future. Two big questions are:
1. How much information from CiviCRM do we want to display on our website (e.g. A live list of our current members)?
2. What information, collected through our website, do we want to store in CiviCRM (e.g. Family data from a public form with the family relationships automatically added).
This is known as integration. The type of integration you require may help you determine which is the best CMS for you.
## Availability of Extensions
There are historical reasons why different CMS options have different levels of integration with CiviCRM. In 2005, CiviCRM launched without its own extension mechanism, but it was possible to write custom integrations in the form of Drupal modules or Joomla plugins, the two CMSes supported at that time. Partly as a result of the ethos of the Drupal community members participating in the CiviCRM ecosystem, a larger variety of Drupal modules to integrate with CiviCRM were created and matured.
Support for running CiviCRM with WordPress was added in 2012, which allowed WordPress plugins to implement custom integrations. 2012 also saw CiviCRM roll out its own native extension system: flexible, cross-CMS support aiming to reduce the development and maintenance effort involved in creating customizations to extend and modify core CiviCRM functionality. In recent years a large number of CiviCRM native extensions have been released, though there continue to be CMS-specific integrations, particularly around permissions and forms. So the reasons for choosing one CMS over another based on the available functionality and integration levels continue to decline.
## Integration Features
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 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
The installers are a bit different - web-based installation is easier in Joomla, but it's more flexible in Drupal or WordPress. Command line based installation is easier in Drupal or WordPress.
## Testing
The core system is the same across all CMS options, but occasionally there are bugs in the CMS integration code. For historical reasons, the most robust automated testing is performed on Drupal7 though as of 2019 there are very active WordPress manual testers and a growing numbers of WordPress tests are being added.
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.
The following chapters in this section go into more detail about what is offered for each CMS.
Before starting a project you should consider how you plan to use CiviCRM both now and in the future. Two big questions are:
* How much information from CiviCRM do we want to display on our website (e.g. A live list of our current members)
* What information, collected through our website, do we want to store in CiviCRM (e.g. Family data from a public form with the family relationships automatically added).
This is known as integration. How much integration you require will help you determine which is the best CMS for you.
You may also choose a CMS because you already know how to use it or it is already used by your organisation. Each CMS has different advantages and disadvantages and different people will give you views on which is better. This chapter gives a quick introduction to each of them.
**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.
**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.
**WordPress** is by a wide margin the most popular of the four options. It is considered to be very easy to build sites using WordPress, especially for people that are not familiar with web technology. A lot of people know WordPress as a blogging platform rather than a CMS, but it is becoming more powerful and flexible with each release. The amount of integration available is lower than when using Drupal.
Differences at a CMS level are mentioned elsewhere through this guide.
## Users and Contacts
* Anonymous site visitors and those with a website login are website **Users**
* Individuals and organisations with a CiviCRM record are **Contacts**
docs/planning/demo.md 0 → 100644
+ 30
− 0
View file @ cce2f79f
## Demonstration sites
CiviCRM hosts several demo sites - there is at least one for each of the supported **Content Management Systems** (CMS) - Backdrop, Drupal 7, Joomla, and WordPress. The demo sites present a working copy of the latest master of CiviCRM with sample data. You can use them to play around with CiviCRM, but be aware that they are publicly viewable so you shouldn't enter personal data.
!!! note
These sites run on `master` for the most part (some CMSs are harder to automate!)
the code is bleeding edge and the "official" demo sites are intended for issue reproduction
and testing purposes - whilst they do demonstrate the functionality of CiviCRM this is not their
primary purpose and they should be considered **sandboxes** rather than demos.
A list of the available demos can be found at [https://civicrm.org/demo](https://civicrm.org/demo).
As these are public demo sites, you may from time to time find that they are configured unexpectedly, miss some functionality, or appear in different languages as they are explored by other users such as yourself.
The demo sites also have some limitations - you can't send emails from them, nor set permissions for Drupal users or do a full exploration of online payment options.
If you are having trouble working on a demo site, contact the CiviCRM [Core Team](https://civicrm.org/teams/core-team). If you want a more controlled environment for exploring CiviCRM, you're ready for your own test site!
## A local test installation
You can download and set up a local version of CiviCRM on your local computer rather than on a server on the Internet. You'll still access it through a browser, but it will only be visible on your computer. The advantage of a test installation is that you can configure CiviCRM, and experiment with your data. This works if you're familiar with configuring a webhosting environment but it does require a measure of technical knowledge.
## CiviCRM Spark
If you're not comfortable with setting up a webhosting environment, a quick option is to sign up for [CiviCRM Spark](https://civicrm.org/spark). This hosted CiviCRM platform is provided by CiviCRM LLC and helps sustain CiviCRM
development.
## Contact a supplier
If you'd prefer to have guidance at this early stage, consider getting in touch with a CiviCRM provider who can advise you on the best way to achieve what you need. The CiviCRM website has a [find an expert](https://civicrm.org/partners-contributors) feature which can help you find the right people to work alongside.
docs/planning/hosting.md 0 → 100644
+ 52
− 0
View file @ cce2f79f
Before installing CiviCRM, careful consideration must be given to where it will be hosted. The main options with an outline of the situations in which you would want to choose them, and the advantages and disadvantages of doing so are outlined below:
## CiviCRM Spark {:#spark}
[CiviCRM Spark](https://civicrm.org/spark) is a quick and secure way to get started with CiviCRM. It allows you to get your own installation of CiviCRM up-and-running in minutes. Spark is ideal for organizations of any size wanting to test and trial CiviCRM, or for smaller organizations and activities with up to 2000 contacts.
## Recommended hosting providers and implementers {:#experts}
There are [implementers and experts](https://civicrm.org/providers) in the CiviCRM community able to manage the hosting and/or installation for you. If requested, they may also be available to manage a local implementation and configuration on your premises.
## Internal hosting
If you have an internal IT department or staff members with a technical background, you may wish to host CiviCRM internally. To do this, you will likely need:
* Servers or dedicated PC hardware available to run as a web server, 24x7.
* A space on premises to permanently store the hardware, possibly air conditioned.
* An un-interrupted power supply (UPS) to ensure the server is still available during power outages.
* An internet connection suitable for hosting a website (static IP, sufficient bandwidth, etc).
If hosting internally, it is important to note that the system will be dependent on internet connectivity to your server, and that in event of an outage only external users and visitors will lose access. This might prevent visitors accessing contribution forms or widgets embedded on external sites.
Other considerations are the secure partitioning of this internally-hosted website from other services on the same machine, security of network, and other factors including the cost of management and maintenance. It's recommended to have some expert guidance on doing this right.
## External hosting
With internal expertise you could manage the install and configuration in-house, but host CiviCRM with an external provider. In this instance, we recommended you rent a VPS (Virtual Private Server) to ensure you have complete control of all packages and libraries (e.g. PHP, MySQL, etc), and are therefore able to configure it to your specific requirements.
Many shared hosts restrict the level of access you have, and may not support CiviCRM if you are unable to install the required pre-requisites. Shared hosts can also be prone to performance issues, as the hardware is shared between a group of customers with varying usage levels; if one customer's website suddenly receives a large spike in traffic, every website on that server could experience a lengthy outage.
Disadvantages aside, leasing space on a shared host is typically cheaper than a VPS, and both are subscription services on a monthly or annual basis (discounts may be available for longer leases.
**We advise that you trial run any service for a short-term before committing to a longer period.**
## Existing hosting
If you are already using a website host, contact your provider to determine whether they support the packages and libraries required by CiviCRM. If they do not, there are two options available to you:
### Migrate to another host
If your current host cannot accommodate CiviCRM you may want to consider migrating your CMS to a new host before installing CiviCRM. Depending on the CMS you are using, the process of moving from one host to another may be fairly straightforward. You are in a good position to transfer to another host if you can:
1. request that your users **stop creating and updating content** during the migration,
2. **export and import** all of the content from/to the chosen CMS,
3. **edit your DNS records** to switch the 'pointers' to your website from the old host to the new host
### Run the website and CiviCRM in parallel, on different servers
If you cannot move your website to a different host, you could purchase a second account on a host capable of running CiviCRM, and run the two systems alongside each other.
In this instance, you would use a CNAME DNS record to point to a second copy of the CMS and CiviCRM on the other host (e.g. `civicrm.example.org`), and link to it from your website, perhaps in form of a log-in button.
Aside from paying a second bill, one of the limitations to this approach is the need to clone the style of your website on the second host to give the visitor the illusion that they are in the same place. If changes to the style are changed, the work must be duplicated.
docs/planning/index.md 0 → 100644
+ 68
− 0
View file @ cce2f79f
This chapter covers some basic strategies for identifying your organizational needs, and how they could be met by CiviCRM. It doesn't go into detail about CiviCRM functionality or how CiviCRM stores data - you will find that in other chapters. Instead, we encourage you to first take a step back and think about your organisation.
Building internal support for a new Constituent Relationship Management (CRM) solution is a complex task can yield great rewards if done right.
Some organizations are comfortable appointing a team to do this internally while others rely on outside consultants. Following are our recommendations for how best to evaluate your organization’s needs and build internal support.
## Goal
To start with, take a minute to articulate the goal of adopting a CRM. For example:
> Investing in our organization’s database of 12,000 constituents will allow our team to better focus on raising funds and awareness to fulfill our mission now and in the future.
## Evaluation
Evaluate your organization's specific CRM needs by interviewing key stakeholders. This might include development, communications, marketing, events and programs staff as well as board members.
**Help them identify the constituents** they interact with on a routine basis and to articulate key challenges in managing constituent information (collecting, updating, sharing and using contact information).
**Identify specific inefficiencies** that could be addressed by a comprehensive CRM solution.
**Enumerate the resulting lost productivity**. For example:
* **Incoherent view of our constituents.**: *We are unable to see a holistic record of our constituents eg: who is a donor, volunteer and e-newsletter subscriber.*
* **Inability to include all prospective donors in all outreach efforts.**: *With fractured constituent lists we are unable to include all constituents in our efforts to raise funds, awareness and promote events.*
* **Inefficient use of staff.**: *Staff time is not used well when re-keying information originally received digitally, importing, exporting and de-duping records.*
* **Lack of communication.**: *We struggle to communicate consistently across departments about their various interactions with the same constituent.*
* **Data vulnerability.**: *When contact data is distributed across systems, it is a challenge to reliably protect our complete dataset against loss and we challenges ensuring data is secure when held in multiple systems.*
**Lastly, inventory current data sources** that could be consolidated
and shared across departments. For example:
| Owner | Department | Count | Constituents | Description / filename |
|--------|------------|--------|---------------------------|------------------------ |
| Kris | Comms | 245 | short-lead media contacts | comms campaigns / comms2010.doc |
| Katie | Dev | 79,000 | donors | donors active since 2005 / donors2005-2010.xls |
| Martha | Marketing | 233 | corporate partners | active partners / (Outlook) |
| Dan | Marketing | 134 | grassroots partners | all grassroots partners / grasspartners05-10 (Google docs) |
| Carole | Volunteers | 3450 | volunteers | all MLK day volunteers, skills / mlk_volunteers_10.xls |
This initial inventory will help you identify common sources, but when consolidating or migrating data you should plan for discovery of other existing sources in your organization along the way!
## Benefits
Enumerate the specific benefits of investing in a holistic CRM solution. For example:
* **Accessible to the entire staff** from inside and outside the office (with granular permissions from entry level to super-users).
* **Holistic record for each constituent** showing all their contact information and interactions with our organization.
* **Dynamic creation of constituent groups** allowing us to create groups of constituents based on criteria such as ‘all donors of over $100 in Massachusetts’ or ‘all donors whose gifts have amounted to major gifts this year’.
* **Dynamic creation of top donor and other reports**
* **Constituents' self-service creation and management** of their contact/contribution/subscription/activity records.
## Recommendations
In recommending your CRM solution enumerate and compare its features and costs to other market solutions. Share case studies of other organizations who use the recommended solution.
**Implementation costs**: Include a budget for implementation that contemplates:
* discovery and project management
* data clean up, consolidation and migration
* system configuration
* post implementation training and documentation
**Maintenance costs**: Include a budget for ongoing maintenance that contemplates:
* pro-active server maintenance
* incremental data backups
* operating system and software upgrades
* ongoing training
docs/planning/transition.md 0 → 100644
+ 86
− 0
View file @ cce2f79f
Here you'll find information on the phases of a typical CiviCRM project.
We have outlined things that are typically encountered in a CiviCRM project and provided pointers on some things to watch out for, but don't rely on this guide for a complete project management solution! Consider seeking expert guidance through the process if you can.
First, some pop philosophy courtesy of Cynthia Tarasco:
"Life is a series of making decisions. Some decisions are easy because they do not require a substantial investment of time or money. Deciding which flavor ice cream to buy fits into this category: if you get vanilla today you can always get chocolate tomorrow. Other decisions are much more difficult because they require substantial investments of resources, and you will be living with your choice for the foreseeable future. Adopting a new CRM fits into this category, so planning and project management are vital."
When you start out on a new CiviCRM project you should spend time thinking about:
* the people who will be involved in the project
* what the business goals of using CiviCRM are
* how you will approach the initial development
* what ongoing support you will need
* the costs associated with hosting and your IT infrastructure
* training and documentation
* change management
## People and the project team
Including a representative range of people from the different parts of your organisation will help with delivery of your project. A mixture of management and day-to-day staff helps the team to keep an eye on the big picture as well as ensure that the project is ultimately useful to front-line staff.
You'll be exploring new territory with your CiviCRM installation and this can sometimes be stressful. It might be helpful to share this project's management with others who can give you a different perspective and moral support when you need it!
Managing a CiviCRM project will require a major time investment from people within your organisation, even if you employ an external consultant. Organisations often underestimate the amount of time that will be required from their staff in implementing an IT project - such as training, modifying existing processes and providing new or updated information to relevant people. It's not something that can be tacked on to the end of an already busy schedule and this should be taken into consideration.
## Goals
You should have a clear idea of your goals for implementing CiviCRM. This could be goals such as: *reduce administrative work in managing events by 25%_ or _increase donations by 25% with the same staff*. The goals should be SMART (specific, measurable, attainable, relevant, timely)!
These business goals will help you in directing and managing your project. For example, if the project group wants some customization that requires budget and effort, your business goals will help you decide one way or the other. The business goals will help you to focus on why you are implementing CiviCRM and what you want to achieve in the long run.
## Development
It often makes sense to break development up into smaller more manageable sections, which can be implemented in discrete stages or iterations. A common first phase of development is to choose something simple to implement in CiviCRM, or specific functionality for a team who can then act as CiviCRM evangelists within the organisation.
Implementing in stages allows staff to get used to changes gradually without feeling overwhelmed, and gives the developer or implementer the ability to be responsive to feedback from users during the development process.
Another reason that people choose to develop iteratively is that it is very hard for users to correctly or fully articulate their requirements at the start of the project. Giving users hands-on experience of an early version of the system helps them understand how it works and what is possible. They can then provide valuable feedback and might articulate requirements that they haven't thought of previously.
Implementing your CMS (Drupal, WordPress or Joomla!) either before or after implementing CiviCRM is another convenient way to split up a CiviCRM project. As well as the normal advantages of breaking up the development into manageable chunks, this helps staff understand the important differences between a CMS and a CRM.
### Pilot projects
Pilot projects help to reduce risk during a project implementation. For example, rather than moving your organisation's entire event management infrastructure to CiviCRM, run one pilot event using CiviCRM and evaluate it. You can then incorporate the learning back into the development process.
## Ongoing support and development
It is a mistake to think about a CiviCRM project as a one-off development that will meet the needs of your organisation for the foreseeable future. Organisations constantly change and evolve and your CRM should evolve with you. If not, it will eventually become out-of-sync with the organisation.
Once you have been using CiviCRM for a while and staff are comfortable with it, you will likely want to take advantage of other functionality. Each improvement or new piece of functionality that you decide to implement in CiviCRM will take resources, so you'll need to plan for these.
Even if your organisational needs don't change, there are ongoing support implications, including:
* keeping your site up-to-date with security patches
* upgrading to the latest version of CiviCRM (CiviCRM is improving all the time and your users will thank you for the improved usability and functionality each time you upgrade, not to mention that accessing community support is easier on the latest version and we may ask you to upgrade before helping!)
* upgrading the CMS
* hosting
## Training
Training is a significant aspect of most CiviCRM projects. Your training could take many shapes and sizes depending on your users, but it often makes sense to spend resources on formal and reusable training resources (user guides, lesson plans and so on).
CiviCRM's range of functionality can be overwhelming at first (especially to the less technically-minded). Remember that staff who were not involved in the project's early stages will need to have concepts explained clearly to them - things that are obvious to you may be quite unfamiliar to others.
Trying to cover everything in one training session probably won't be effective; your staff will need time to digest the new ideas. Instead, hold smaller training sessions that introduce concepts and specific functionality, followed by periods of testing, piloting and feedback. Tailor your training for your audience: not everyone needs to sit through a two-hour training session on how to manage events if there is a single person responsible for event management and planning. Where possible, involve staff in training other staff members as this increases the sense of ownership and helps to embed learning.
Training will be ongoing. New staff will need to be trained, users familiar with the system benefit from learning about more advanced topics, and staff will need further training when there are significant upgrades or new functionality added. If you plan to use CiviCRM for any large or mission-critical events, allow adequate time for additional staff training and testing.
## Hosting and infrastructure
Hosting is a key aspect of any CiviCRM project. You will need to provide maintenance of the server on which CiviCRM is stored, and have someone available to fix problems that inevitably occur from time to time. If your site needs to be accessible 24 hours a day, you should have a support agreement with your hosting provider to ensure this. Ensure that your budget is sufficient for appropriate hosting, and that effective backup procedures, data security measures, and policies are in place.
Keep in mind that in the hosting provider world, you get what you pay for. In many cases, cheap hosting providers keep their prices down by limiting the services or flexibility they provide. CiviCRM doesn't work well on poor hosting, and under-budgeting for hosting may lead to other problems. Similarly, make sure that the computers your staff are using are powerful enough to provide a good experience with CiviCRM.
## Change management
Introducing a new (or the first) CRM will cause changes in work flow and processes at your organisation. These changes may be organizational, practical or technical. Either way, a lot of change at the same time can be difficult and stressful.
To mitigate this, give staff time to accept and support each change so that they share in ownership of the new system rather than feeling as if something has been forced on them. Focus on simple tasks at the beginning of deployment and introduce more difficult tasks as staff understanding of the system grows. Show staff how the new system will make their work easier and where their feedback has been incorporated.
Good planning can minimise the risks around change, but it is important to be flexible within your plan; unforeseen things do occur, and a rigid plan could prevent you from reaching the best solution.
## Choosing a consultant/service provider
For many projects having a trusted outside partner is very important. Outside partners are experts in CiviCRM and will listen to you to learn about your organization and how to best match your needs to CiviCRM. There are many [providers](https://civicrm.org/partners-contributors) that participate in the CiviCRM community and can help you with your implementation.
docs/wordpress/index.md 0 → 100644
+ 184
− 0
View file @ cce2f79f
## 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 WordPress by referring to the [WordPress Installation Guide](https://wordpress.org/support/article/how-to-install-wordpress/) if needed.
!!! note "Path for WordPress"
The rest of these instructions assume that you have WordPress installed in `/var/www/wordpress`. Adjust paths as needed.
## Download and Un-zip CiviCRM Code
All CiviCRM code and packages used by CiviCRM (such as PEAR libraries) are included in the compressed CiviCRM distribution files ('zips'). Follow these steps to download and install the codebase:
* Download the appropriate zip file from the [CiviCRM website](https://civicrm.org/download) with your browser. The zip file-names include the CiviCRM version. For example, **civicrm-x.x.x-wordpress.zip.**
* Copy or ftp the zip file to your WordPress installation's `/wp-content/plugins` directory. You may have to change the "File Permissions" setting of `/wp-content/plugins/civicrm` directory to allow for "Write" Access. Just remember to change it back to default when done.
* You can upload the zip file that was downloaded via your WordPress admin panel at `wp-admin/plugin-install.php`
* Create the `<wordpress path>/wp-content/plugins/files/` directory and ensure it is writable. CiviCRM for versions 4.6 and prior uses this directory for temporary and uploaded files.
!!! information "Downloading Directly to Your Server with wget"
If you have command-line access, you may prefer to download the zip file directly to your server using wget:
1. Move into WordPress's plugin directory
``` bash
cd /var/www/wordpress/wp-content/plugins
```
1. wget the file (modify this line to use the current zip file name for the version you want)
``` bash
wget https://download.civicrm.org/civicrm-x.x.x-wordpress.zip
```
* Extract (aka: unzip, unpack) the codebase into the wordpress/wp-content/plugins directory.
1. Move to the wordpress/wp-content/plugins directory (if not already there)
<!-- markdownlint-disable MD046 -->
``` bash
cd /var/www/wordpress/wp-content/plugins
```
<!-- markdownlint-enable MD046 -->
1. Un-zip the file (modify this line with the actual downloaded filename)
<!-- markdownlint-disable MD046 -->
``` bash
unzip civicrm_download_file.zip
```
<!-- markdownlint-enable MD046 -->
* You should now have a `/var/www/wordpress/wp-content/plugins/civicrm` directory containing `civicrm.php`, `README.txt` and another civicrm directory (which in turn contains bin, CRM, sql, templates, etc.).
## 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.
## Enable CiviCRM plugin and run 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 WordPress site with Administrator level permissions.
* Go to plugins page: `https://example.org/wp-admin/plugins.php`.
* Click the **Activate** link to activate the CiviCRM plugin.
* Then go to **Settings > CiviCRM Installer**: `https://example.org/wp-admin/options-general.php?page=civicrm-install`
* In version 4.7 and above you will see a link on the wp-admin page to the Installer screen
* You should see the **CiviCRM Installer** screen.
* If you see any errors, check the **Requirements** details at the bottom of the page for more information. You will need to correct any issues before continuing.
* CiviCRM Database Settings.
* Initially, the installer will default to using the existing WP database for the CiviCRM data. You can change this if you require.
!!! tip "Where Should I Store CiviCRM Data?"
CiviCRM may be configured to use your existing WordPress 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 WordPress.
* Fill in the WordPress Database Settings for your existing WordPress database. CiviCRM will fill in the WP database settings, you can change these if you want to use a separate database.
!!! tip "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 will redirect to success message.
* 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:<wordpress path>/wp-content/plugins/civicrm/`"
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**
## Locate and Backup the CiviCRM settings file
After installation, a configuration file will have been created by CiviCRM at: `<wordpress>/wp-content/uploads/civicrm/civicrm.settings.php`
It is critical you make a copy of this file and save as a backup in a safe location. This file contains passwords and other critical information, take precautions to secure the copy from prying eyes.
Should an upgrade fail, you will need this backup copy to restore your site.
## Enabling Cleaner URLs for WordPress
* Starting in Version 5.13.x CiviCRM now can support "Clean URLs" for WordPress front-end (user-facing) pages.
* By default CiviCRM URLs are in the format of `https://example.org/civicrm?page=CiviCRM&q=civicrm/contribute/transact&reset=1&id=1` for a Contribution Page. With clean URLs enabled:
* A Contribution Page will have the format of `https://example.org/civicrm/contribute/transact/?reset=1&id=1`.
* Profile Pages can be accessed at `https://example.org/civicrm/profile/edit/?gid=1&reset=1` or `https://example.org/civicrm/profile/create/?gid=1&reset=1`.
* Listings would be at `https://example.org/civicrm/profile/?gid=1&reset=1`.
* The User's Contact Dashboard can be accessed at `https://example.org/civicrm/user/?reset=1`.
* To Enable Cleaner URLs , start by backing up your `civicrm.settings.php` file as detailed in the "Locate and Backup the CiviCRM settings file" section above.
* Then find this section of code in `civicrm.settings.php` On a default install it should be around line 480
<!-- markdownlint-disable MD046 -->
``` php
if (!defined('CIVICRM_CLEANURL')) {
if ( function_exists('variable_get') && variable_get('clean_url', '0') != '0') {
define('CIVICRM_CLEANURL', 1 );
}
elseif ( function_exists('config_get') && config_get('system.core', 'clean_url') != 0) {
define('CIVICRM_CLEANURL', 1 );
}
else {
define('CIVICRM_CLEANURL', 0);
}
}
```
<!-- markdownlint-enable MD046 -->
* Replace the above code with:
<!-- markdownlint-disable MD046 -->
``` php
if (!defined('CIVICRM_CLEANURL')) {
// check for Drupal clean URLs
if ( function_exists('variable_get') && variable_get('clean_url', '0') != '0') {
define('CIVICRM_CLEANURL', 1 );
}
elseif ( function_exists('config_get') && config_get('system.core', 'clean_url') != 0) {
define('CIVICRM_CLEANURL', 1 );
}
// check for WordPress clean URLs
elseif( function_exists('get_option') && get_option('permalink_structure') != '' ) {
define('CIVICRM_CLEANURL', 1 );
}
else {
define('CIVICRM_CLEANURL', 0 );
}
}
```
<!-- markdownlint-enable MD046 -->
* You will need to go to **Settings >> CMS Database Integration** `https://example.org/wp-admin/admin.php?page=CiviCRM&q=civicrm/admin/setting/uf&reset=1` and make sure the base page points to an existing WP page (usually /civicrm)
* You will need to flush rewrite rules in WordPress for clean URLs to work. Visit the Permalinks settings page to trigger this Go to **Settings >> Permalinks** The URL will be `https://example.org/wp-admin/options-permalink.php`
. ![WordPress Permalink settings.](../images/wp-permalinks.png)
* Now Cleaner URLs will be enabled. Enabling Cleaner URLs does not change how shortcodes work in CiviCRM and existing "Old" style URLs will still work
## Create CiviCRM Contacts for Existing WordPress Users
Once installed, CiviCRM keeps your WordPress Users synchronized with corresponding CiviCRM contact records. The 'rule' is that there will be a matched contact record for each WordPress user record. Conversely, only contacts who are authenticated users of your site will have corresponding WordPress user records.
When CiviCRM is installed on top of an existing WordPress site, a special CiviCRM Administrative feature allows you to automatically create CiviCRM contacts for all existing WordPress users:
* Login to your WordPress site with an administrator-level login
* Click the **CiviCRM** link in the main navigation block
* (If your WordPress 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 WordPress 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
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
There should now be a **CiviCRM** link in your WordPress 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.
## Troubleshooting Resources {:#troubleshooting}
* Review the [troubleshooting](../general/troubleshooting.md) page for help with problems you may encounter during the installation.
mkdocs.yml 0 → 100644
+ 45
− 0
View file @ cce2f79f
site_name: 'CiviCRM Installation Guide'
site_url: 'https://docs.civicrm.org/installation/en/stable/'
repo_url: 'https://lab.civicrm.org/documentation/docs/installation'
repo_name: GitLab
site_description: 'This guide is aimed at CiviCRM users and implementors who would like to learn how to install and setup CiviCRM.'
site_author: 'The CiviCRM community'
theme:
name: material
icon:
repo: fontawesome/brands/gitlab
markdown_extensions:
- attr_list
- admonition
- def_list
- codehilite:
guess_lang: false
- toc:
permalink: true
- pymdownx.superfences
- pymdownx.inlinehilite
- pymdownx.tilde
- pymdownx.betterem
- pymdownx.mark
nav:
- Home: index.md
- Install CiviCRM on Backdrop: backdrop/index.md
- Install CiviCRM on Drupal 7: drupal7/index.md
- Install CiviCRM on Drupal 8: drupal8/index.md
# - Install CiviCRM on Drupal 9: drupal9/index.md
- Install CiviCRM on Joomla: joomla/index.md
- Install CiviCRM on WordPress: wordpress/index.md
- General:
- Requirements: general/requirements.md
- Permissions: general/permissions.md
- Internationalisation: general/i18n_l10n.md
- Troubleshooting: general/troubleshooting.md
- Planning:
- Identifying your needs: planning/index.md
- Trying a demo: planning/demo.md
- Hosting: planning/hosting.md
- Choosing a CMS: planning/cms.md
- Transitioning to CiviCRM: planning/transition.md
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment