.gitattributes

+*.md text eol=lf

docs/drupal7/index.md

-## Scope of this guide and alternative installation methods
-
-This guide covers standard installation of CiviCRM for production use. For installing a development environment, refer to the [section on Buildkit in the Developer Documentation](https://docs.civicrm.org/dev/en/latest/tools/buildkit/).
-
-## Before installing
-
-1. Ensure that your system meets the [requirements](../general/requirements.md).
-1. Install Drupal 7 by referring to the [Drupal 7 Installation Guide](https://www.drupal.org/docs/7/install) if needed.
-
-## Determine Drupal Database Settings {:#db-settings}
-
-You will need to know the database settings for your Drupal installation prior to running the CiviCRM installer: You can look up these values in your Drupal `settings.php` file (located by default in your `<drupal_root>/sites/default directory`) be looking for the following code:
-
-```php
-$databases = array (
-  'default' =>
-  array (
-    'default' =>
-    array (
-      'database' => 'drupal',
-      'username' => 'dbuser',
-      'password' => 'dbpassword',
-      'host' => 'localhost',
-      'port' => '',
-      'driver' => 'mysql',
-      'prefix' => '',
-    ),
-  ),
-);
-```
-
-In the above example:
-
-| Setting                | Value      |
-| ---------------------- | ---------- |
-| Database Server        | localhost  |
-| Drupal Database Name   | drupal     |
-| Database User Name     | dbuser     |
-| Database User Password | dbpassword |
-
-## Tell Drupal where to find the CiviCRM Module {:#directory}
-
-First, download CiviCRM and install the files like you would any other module:
-
-* As administrator in Drupal, go to Modules, click on **Install New Module** , and it will ask you to fill in the URL of the module. It will then fetch it and install it for you. You will need to enable the **Update Manager** module in the Drupal modules page to see the **Install New Module** link.
-* Alternatively, you can upload and extract the file in `<DRUPAL ROOT>/sites/all/modules`
-
-The result will be that the CiviCRM directory will be at `<DRUPAL ROOT>/sites/all/modules/civicrm`
-
-The most up-to-date version of CiviCRM is always available from the [CiviCRM website](https://civicrm.org/download)
-
-**Do NOT** activate the module yet - that will happen automatically when you run the installer.
-
-## Install localization files (only for non-English sites) {:#i18n}
-
-If using CiviCRM in another language than English, see the [internationalisation and localisation](../general/i18n_l10n.md) page about how to install files for running CiviCRM in other languages.
-
-## Run the Installer {:#installer}
-
-The installer will verify that you've downloaded the correct version of CiviCRM, and will check your server environment to make sure it meets CiviCRM requirements. It will then create and populate a database for CiviCRM as well as create your CiviCRM settings file (civicrm.settings.php).
-
-* Login to your Drupal site with Administrator level permissions.
-* Point your web browser to the following URL:
-
-    `https://example.org/sites/all/modules/civicrm/install/index.php`
-
-* You should see the **CiviCRM Installer** screen.
-    * Initially, you will see a red bar with the message "These database details don't appear to be correct." This is expected as you haven't entered your database settings yet.
-    * If you see other errors, check the **Requirements** details at the bottom of the page for more information. You will need to correct any issues before continuing.
-* Fill in the CiviCRM Database Settings.
-
-    !!! tip "Where Should I Store CiviCRM Data?"
-        CiviCRM may be configured to use your existing Drupal database, or a separate (new) database. Using a separate database is generally preferred - as it makes backups and upgrades easier. The installer will create a new database for CiviCRM automatically if you enter a database name that doesn't already exist on your database server AND the database user you enter has permission to create databases. In case the installer does not automatically create a new database, simply create a new one following the same process as creating a new database for Drupal. Note that if you plan to use the Drupal Views module to display CiviCRM data within your Drupal pages, and if you are going to use separate databases for Drupal and CiviCRM, you need to ensure that your Drupal database user has `SELECT` permissions for your CiviCRM database.
-
-* Fill in the Drupal Database Settings for your existing Drupal database (as noted [above](#db-settings)).
-
-    !!! check "Loading Sample Data"
-        The Installer includes an option to load a set of sample contact, group, and relationship data by default. Sample data can provide a useful head-start in learning to use CiviCRM. However, if you do NOT want the sample data to be loaded, just uncheck **Load sample data** under **Other Settings**.
-
-* Select the appropriate language for the base installation. You will be able to add other languages after the installation for multi-lingual sites.
-* Click the **Check Requirements and Install CiviCRM** button.
-    * The installer will configure your databases, create the settings file and redirect you to your Drupal Home page.
-    * If you still see a red bar with the message "These database details don't appear to be correct." - check the Database Details section below your settings for specific errors and problems. Once you correct these problems, click "Recheck requirements" to verify your settings before continuing.
-    * If you are on a Windows machine and get the message:
-      > "The user account used by your web-server needs to be granted write access to the following directory in order to configure the CiviCRM settings file: `C:<DRUPAL ROOT>/sites/default/`"  
-      even after changing directory permission in Explorer, see [the permissions page](../general/permissions.md) for instructions on how to set permissions on Linux, MacOS and Windows.
-    * Once you see the green "You're ready to install!" message - you can click **Check Requirements and Install CiviCRM**
-
-## Review Permissions {:#permissions}
-
-!!! check ""
-    Note that Drupal tries to create the `/files/` directory (and make it writeable), but only when saving `admin/settings`. Same holds for `/temp` directory, and a `/uploads/` directory in the CiviCRM module root. On a brand-new Drupal install, this directory may be missing. Even on an existing installation, if file permissions are not set properly, the directory may be missing. If enabling the **CiviCRM** module generates errors regarding the files directory, you must create it (writeable) manually.
-
-* Go to the CiviCRM dashboard to see the CiviCRM menus:
-`https://example.org/civicrm` (or `https://example.org/index.php?q=civicrm` if you don't have Clean URLs enabled)
-
-* Go to **Administer » User management » Permissions**
-
-* Verify that the Roles that you want to have access to CiviCRM have the appropriate permissions checked. CiviCRM is installed with a number of fixed permissions (such as "edit contacts" and "administer CiviCRM").
-<!-- markdownlint-disable MD046 -->
-!!! tip "Permissions for the Anonymous Role"
-    Many sites want anonymous visitors to have access to certain CiviCRM functionality. These permissions are enabled during installation for the Anonymous role. You should review them and modify if needed based on your requirements:
-
-    * **access all custom data** : If you plan on collecting "custom" data from visitors in standalone forms or as they make a contribution - enable this permission.
-    * **access CiviMail subscribe/unsubscribe pages** : If you are planning on using CiviMail, enable this permission to allow anonymous users to subscribe and unsubscribe from mailing lists via the web.
-    * **access uploaded files** : If you plan on allowing visitors to upload or view photos or other files - enable this permission.
-    * **make online contributions** : If you plan on soliciting online contributions from visitors, enable this permission for the "anonymous" role.
-    * **profile listings and forms** : If you plan on collecting name and address or other information from visitors, enable this permission for the "anonymous" role.
-    * **view event info** and **register for events** : If you plan to use CiviEvent and want to allow un-authenticated visitors to view event information and register for events online - enable these permissions for the "anonymous" role.
-    * **view event participants** : Enable this permission to allow anonymous users to access participant listing pages for events.
-<!-- markdownlint-enable MD046 -->
-## Create CiviCRM Contacts for Existing Drupal Users {:#contacts-users}
-
-Once installed, CiviCRM keeps your Drupal Users synchronized with corresponding CiviCRM contact records. The 'rule' is that there will be a matched contact record for each Drupal user record. Conversely, only contacts who are authenticated users of your site will have corresponding Drupal user records.
-
-When CiviCRM is installed on top of an existing Drupal site, a special CiviCRM Administrative feature allows you to automatically create CiviCRM contacts for all existing Drupal users:
-
-* Login to your Drupal site with an administrator-level login
-* Click the **CiviCRM** link in the main navigation block
-* If your Drupal site makes use of the `db_prefix` setting (in `settings.php`), in the top bar click **Administer » System Settings » CMS Database Integration** , and update the box for the Drupal Users Table Name so that it includes the prefix.
-* Click **Administer** in the menu bar
-* Click **Users and Permissions** from the drop-down menu, then select **Synchronize Users to Contacts**
-
-## Review the Configuration Checklist {:#checklist}
-
-The **Configuration Checklist** provides a convenient way to work through the settings that need to be reviewed and configured for a new site. You can link to this checklist from the installation success page AND you can visit it at any time from **Administer** » **Administration Console** » **Configuration Checklist**.
-
-## Test-drive CiviCRM {:#test-drive}
-
-There should now be a **CiviCRM** link in your Drupal menu. Click that link and the CiviCRM Menu, Shortcuts, Search and New Individual Blocks should appear. You can now explore CiviCRM end-user features and begin configuring CiviCRM for your site/organization needs.
-
-## Using Encryption with MySQL
-
-If your MySQL database is hosted on a different machine than your web server, or if your host requires it, you can use TLS to encrypt the connection between the database and the web server.
-
-Full instructions on installing drupal are out of scope for this guide, but one method is to install into a test database first without MySQL encryption and then move the database to the live server and update settings.php to enable MySQL encryption.
-
-See [TLS for MySQL](/general/mysql_tls/) for introductory concepts and the settings for the CiviCRM database. For the Drupal database you have several options for updating settings.php:
-
-1. The simplest, which doesn't require a client certificate, but doesn't verify the server certificate.
-
-    ``` php
-    $databases = array (
-      'default' =>
-      array (
-        'default' =>
-        array (
-          'database' => 'drupal',
-          'username' => 'dbuser',
-          'password' => 'dbpassword',
-          'host' => 'db435.examplehost.com',
-          'port' => '',
-          'driver' => 'mysql',
-          'prefix' => '',
-          'pdo' => array(
-              PDO::MYSQL_ATTR_SSL_CA => TRUE,
-              PDO::MYSQL_ATTR_SSL_VERIFY_SERVER_CERT => FALSE,
-          ),
-        ),
-      ),
-    );
-    ```
-
-2. Verifies the server certificate, and doesn't require a client certificate.
-
-    !!! warning "Host name must match certificate name"
-        Note that the DATABASE SERVER certificate would have to have a CN (common name field) that matches exactly the `host` you are using in `$databases['default']['default']['host']`. So if the host is `db435.examplehost.com`, then that must be the name on the SERVER certificate.
-
-    ``` php
-    'pdo' => array(
-        // A certificate authority bundle.
-        // If you are using a self-signed server certificate in a development
-        // or testing environment, then this would be the same as the server
-        // certificate.
-        PDO::MYSQL_ATTR_SSL_CA => '/path/to/ca.crt',
-    ),
-    ```
-
-3. Client certificate/key pair (not self-signed), and do not verify the server certificate.
-
-    ``` php
-    'pdo' => array(
-        PDO::MYSQL_ATTR_SSL_VERIFY_SERVER_CERT => FALSE,
-        PDO::MYSQL_ATTR_SSL_KEY => '/path/to/your.key',
-        PDO::MYSQL_ATTR_SSL_CERT => '/path/to/your.crt',
-    ),
-    ```
-
-4. Client certificate/key pair (could be self-signed), and verify the server certificate.
-
-    ``` php
-    'pdo' => array(
-        // The SSL_CA can be the same as your.crt if self-signed, but note
-        // that it would also have to be a certificate authority for the
-        // server certificate. Self-signed would only be for local
-        // development testing.
-        PDO::MYSQL_ATTR_SSL_CA => '/path/to/ca.crt',
-        PDO::MYSQL_ATTR_SSL_KEY => '/path/to/your.key',
-        PDO::MYSQL_ATTR_SSL_CERT => '/path/to/your.crt',
-    ),
-    ```
-
-## Trouble-shooting Resources {:#troubleshooting}
-
-* Review the [Troubleshooting](../general/troubleshooting.md) page for help with problems you may encounter during the installation.
-* To check compatibility with other Drupal modules see: [Drupal modules incompatible with CiviCRM](https://docs.civicrm.org/sysadmin/en/latest/integration/drupal/incompatibilities/)

docs/drupal8/index.md

-## Scope of this guide and alternative installation methods
-
-This guide covers standard installation of CiviCRM for production use. For installing a development environment, refer to the [section on Buildkit in the Developer Documentation](https://docs.civicrm.org/dev/en/latest/tools/buildkit/).
-
-## Before installing
-
-1. Ensure that your system meets the [requirements](../general/requirements.md).
-1. Install Drupal 8 by referring to the [Drupal 8 Installation Guide](https://www.drupal.org/docs/8/install) if needed.
-
-!!! warning "Composer install required!"
-    This guide will assume that you have installed Drupal 8 using composer. At this time manual installation of Drupal 8 using zip or tarball install methods is not supported.
-
-## Downloading CiviCRM on Drupal 8 with Composer {:#downloading}
-
-To download CiviCRM on a Drupal 8 site we'll need to ask [Composer](https://www.getcomposer.org) to `require` the CiviCRM libraries. We do this by requiring the `civicrm-core`, `civicrm-drupal-8`, `civicrm-packages` and `civicrm-asset-plugin` libraries.
-
-<!-- markdownlint-disable MD046 -->
-!!! tip "Versions!"
-    It is **strongly** recommended that you provide a version when requiring these libraries, as such our example command below will include, as an example, the version `5.27.2`. Note that installing ESR versions onto CiviCRM has not been tested at this time and as such no instructions for doing so are provided.
-
-    Failure to provide a version will most likely result in you installing the `dev-master` version which is bleeding-edge code and may result in an unstable site/setup!
-
-!!! tip "Composer running out of memory?"
-    You may need to [increase composer's memory limit](https://getcomposer.org/doc/articles/troubleshooting.md#memory-limit-errors) in order to avoid out of memory errors.
-
-    Best practice is to use `composer require` locally or in dev/test and then deploy your `composer.lock` to staging and use `composer install` which requires less memory and implements the changes you've tested and committed to your repo!
-<!-- markdownlint-enable MD046 -->
-
-### Expert Mode - Just the command
-
-To require the CiviCRM libraries on a Drupal 8 site you can use the following one-line command:
-
-??? note "Enabling Patching for composer libraries"
-    You should make sure that before running this line that you either modify the composer.json file to include the parameter `"enable-patching": true` in the extra section or run `composer config 'extra.enable-patching' true` as per the [composer-patches documentation](https://github.com/cweagans/composer-patches#allowing-patches-to-be-applied-from-dependencies). This isn't necessary immediately but from CiviCRM 5.30 it will be required for CiviCRM to function correctly.
-
-* `composer require civicrm/civicrm-asset-plugin:'~1.0.0' civicrm/civicrm-{core,packages,drupal-8}:'~5.28'`
-
-### Guided Mode - More context and information
-
-!!! tip "Location, Location... Location"
-    You should always run `composer` commands from the top-level folder above the web and vendor folders, where in the same place as your `composer.json` file.
-
-??? note "Enabling Patching for composer libraries"
-    You should start by ensuring that patching is enabled for dependencies by altering composer.json and adding `"enable-patching": true` in the extra section or run `composer config 'extra.enable-patching' true` as per the [composer-patches documentation](https://github.com/cweagans/composer-patches#allowing-patches-to-be-applied-from-dependencies). This isn't necessary immediately but from CiviCRM 5.30 it will be required for CiviCRM to function correctly.
-
-You can also install CiviCRM by running these commands separately, this is what that looks like, along with a brief explanation of what each step is doing:
-
-1. Require the CiviCRM composer asset plugin which helps build a predictable structure for your CiviCRM codebase: `composer require civicrm/civicrm-asset-plugin:'~1.0.0'`
-1. Require the CiviCRM core code: `composer require civicrm/civicrm-core:'~5.28'`
-1. Require the CiviCRM third-party packages library: `composer require civicrm/civicrm-packages:'~5.28'`
-1. Require the CiviCRM Drupal 8 integration code: `composer require civicrm/civicrm-drupal8:'~5.28'`
-
-!!! note "pear/exception conflict"
-    If you get an error message from composer when trying to install CiviCRM that there is a conflict in requirements for the package pear/exception. Then run the following command: `composer require pear/exception 1.0.1 as 1.0.0` before trying to run the command in step 3 above.
-
-Optionally you can also require the [`cv`](https://github.com/civicrm/cv) command-line helper/interface for CiviCRM with:
-
-!!! note ""
-    **Composer installs of cv are currently broken** for now use the [manual install steps](https://github.com/civicrm/cv#download).
-
-* `composer require civicrm/cv` - This will place the cv binary in `./vendor/bin/cv` relative to your `composer.json` file.
-
-## Install localization files (for sites needing languages other than US-English) {:#i18n}
-
-!!! warning "I18n & L10n on Drupal 8"
-    If installing with the GUI it is currently only possible to install CiviCRM in English (US) on Drupal 8. Adding the language files involves breaking with Composer best practices by writing the contents of the `civicrm-l10n` tarball into `vendor/civicrm/civicrm-core` or configuring the `civicrm.l10n` directory path after you install and placing the contents of the `civicrm-l10n` tarball into the configured directory.
-
-!!! error "Here Be Dragons..."
-    The following steps are provided as an example - they are not supported or widely tested and may leave your site in a broken state. You use them at your own risk. No. Seriously...
-
-    You will also have to repeat these steps **every** time you upgrade CiviCRM.
-
-The warnings above notwithstanding to install CiviCRM on Drupal 8 requires the following additional steps to prepare:
-
-1. Add [`cv`](https://github.com/civicrm/cv) to your Drupal 8 Site with: `composer require civicrm/cv` (**composer installs of cv are currently broken** for now use the [manual install steps](https://github.com/civicrm/cv#download).)
-1. Grab the localisation (*l10n*) files and unpack the `l10n` and `sql` subfolders into `vendor/civicrm/civicrm-core/`
-    * You'll find the l10n files on the [CiviCRM Download](https://civicrm.org/download) page or from `https://download.civicrm.org/civicrm-VERSION-l10n.tar.gz` where `VERSION` is a recent version of CiviCRM.
-
-    **Example:**
-
-    <!-- markdownlint-disable MD046 -->
-    ``` bash
-    wget https://download.civicrm.org/civicrm-5.27.2-l10n.tar.gz
-    tar -zxvf civicrm-5.27.2-l10n.tar.gz
-    cd civicrm/
-    cp -R l10n/ ../vendor/civicrm/civicrm-core/
-    cp -R sql/ ../vendor/civicrm/civicrm-core/
-    cd ..
-    rm -rf civicrm/
-    ```
-    <!-- markdownlint-enable MD046 -->
-
-1. If you've done this correctly, you should end up with `vendor/civicrm/civicrm-core/l10n` and `vendor/civicrm/civicrm-core/sql/`
-    * You can remove any languages you don't need by deleting them before copying the `l10n` and `sql` folders.
-
-Now we move onto [Installing CiviCRM - Command line install](#installing-commandline)
-
-## Installing CiviCRM {:#installing}
-
-### GUI install {:#installing-gui}
-
-<!-- markdownlint-disable MD046 -->
-!!! warning "Write permissions"
-    It is critical that your web-server user is able to write to the `web/sites/default/` directory in order to create `civicrm.settings.php` and that you have an appropriate value for execution time(s) and memory limit(s) as any interruption to the installer can (and will) result in an unusable install and require remedial steps to correct or a full reinstall! By default on Drupal 8.8+ this directory path is not writable by default, before installing you should ensure you grant write access to your web server user. With, e.g: `sudo chmod u+w web/sites/default`.
-
-    For multisite installations you'll also need to ensure your web server user has write access to additional sites e.g: `sudo chmod u+w web/sites/site2.example.org`.
-<!-- markdownlint-enable MD046 -->
-
-* Login to your Drupal site with Administrator level permissions.
-* Proceed to **Manage >> Extend** or point your web browser to the following URL:
-
-    `https://example.org/admin/modules/`
-
-* Currently there is no interactive installer for CiviCRM on Drupal 8 and enabling the module in Drupal 8 will install CiviCRM into your existing Drupal 8 database.
-
-    !!! tip "Where Should I Store CiviCRM Data?"
-        [GUI installs](#installing-gui) of CiviCRM on Drupal 8 can only install into your existing Drupal 8 database. However using a separate database is generally preferred - as it makes backups and upgrades easier. If you want to install via the GUI **and** use a separate CiviCRM database you'd need to create the CiviCRM database manually and move the `civicrm_` tables into the new CiviCRM database, then update `civicrm.settings.php` with the new database details. If you want to install directly into a separate database see the [command line install](#installing-commandline) instructions.
-
-### Command line install {:installing-commandline}
-
-<!-- markdownlint-disable MD046 -->
-!!! note "Prerequisites"
-    The steps below assume that you have the prerequisites for a command line install, namely cv or some other tested command-line installer for Drupal 8 (**Hint:** There's only one of those at the moment and it's cv)
-
-!!! warning "Write permissions"
-    It is critical that your web-server user is able to write to the `web/sites/default/` directory in order to create `civicrm.settings.php` and that you have an appropriate value for execution time(s) and memory limit(s) as any interruption to the installer can (and will) result in an unusable install and require remedial steps to correct or a full reinstall! By default on Drupal 8.8+ this directory path is not writable by default, before installing you should ensure you grant write access to your web server user. With, e.g: `sudo chmod u+w web/sites/default`.
-
-    For multisite installations you'll also need to ensure your web server user has write access to additional sites e.g: `sudo chmod u+w web/sites/site2.example.org`.
-<!-- markdownlint-enable MD046 -->
-
-Make sure you're in the root directory for your Drupal 8 / CiviCRM site (the same folder/directory that holds `composer.json`).
-
-The essence of a cv install command looks like this `cv core:install -vv --cms-base-url="https://urltocms.example.org" --db="mysql://database:details@go/here:3306" --lang="en_GB"` there are many parameters available. <!-- META:To-Do Document cv usage -->
-
-For our CiviCRM install on Drupal 8 we want a command that looks like this:
-
-<!-- markdownlint-disable MD046 -->
-``` bash
-cv core:install -vv --db="DATABASE" --cms-base-url="URL" --lang="LANG"
-```
-<!-- markdownlint-enable MD046 -->
-
-Replace `cv` with the path to the cv phar on your system if applicable. The parts in `CAPS` above will need to be replaced with your site-specific information as follows:
-
-* `DATABASE` (required) is the [DSN](https://en.wikipedia.org/wiki/Data_source_name) for the database where you want CiviCRM installed.
-* `URL` (required) is the canonical URL to the root of your CMS site.
-* `LANG` (optional) is one of the supported languages for CiviCRM - it **must** exist in your `l10n` folder.
-
-## Review Permissions {:#permissions}
-
-!!! note ""
-    Drupal will create the `/files/` directory (and make it writeable), but only when saving `admin/settings`. Same holds for `/temp` directory, and a `/uploads/` directory in the CiviCRM module root. On a brand-new Drupal install, this directory may be missing. Even on an existing installation, if file permissions are not set properly, the directory may be missing. If enabling the **CiviCRM** module generates errors regarding the files directory, you must create it (writeable) manually.
-
-* Go to the CiviCRM dashboard to see the CiviCRM menus:
-`https://example.org/civicrm` (or `https://example.org/index.php?q=civicrm` if you don't have Clean URLs enabled)
-
-* Go to **Administer » User management » Permissions**
-
-* Verify that the Roles that you want to have access to CiviCRM have the appropriate permissions checked. CiviCRM is installed with a number of fixed permissions (such as "edit contacts" and "administer CiviCRM").
-
-<!-- markdownlint-disable MD046 -->
-!!! tip "Permissions for the Anonymous Role"
-    Many sites want anonymous visitors to have access to certain CiviCRM functionality. These permissions are enabled during installation for the Anonymous role. You should review them and modify if needed based on your requirements:
-
-    * **access all custom data** : If you plan on collecting "custom" data from visitors in standalone forms or as they make a contribution - enable this permission.
-    * **access CiviMail subscribe/unsubscribe pages** : If you are planning on using CiviMail, enable this permission to allow anonymous users to subscribe and unsubscribe from mailing lists via the web.
-    * **access uploaded files** : If you plan on allowing visitors to upload or view photos or other files - enable this permission.
-    * **make online contributions** : If you plan on soliciting online contributions from visitors, enable this permission for the "anonymous" role.
-    * **profile listings and forms** : If you plan on collecting name and address or other information from visitors, enable this permission for the "anonymous" role.
-    * **view event info** and **register for events** : If you plan to use CiviEvent and want to allow un-authenticated visitors to view event information and register for events online - enable these permissions for the "anonymous" role.
-    * **view event participants** : Enable this permission to allow anonymous users to access participant listing pages for events.
-<!-- markdownlint-enable MD046 -->
-
-## Create CiviCRM Contacts for Existing Drupal Users {:#contacts-users}
-
-Once installed, CiviCRM keeps your Drupal Users synchronized with corresponding CiviCRM contact records. The 'rule' is that there will be a matched contact record for each Drupal user record. Conversely, only contacts who are authenticated users of your site will have corresponding Drupal user records.
-
-When CiviCRM is installed on top of an existing Drupal site, a special CiviCRM Administrative feature allows you to automatically create CiviCRM contacts for all existing Drupal users:
-
-* Login to your Drupal site with an administrator-level login
-* Click the **CiviCRM** link in the main navigation block
-* If your Drupal site makes use of the `db_prefix` setting (in `settings.php`), in the top bar click **Administer » System Settings » CMS Database Integration** , and update the box for the Drupal Users Table Name so that it includes the prefix.
-* Click **Administer** in the menu bar
-* Click **Users and Permissions** from the drop-down menu, then select **Synchronize Users to Contacts**
-
-## Review the Configuration Checklist {:#checklist}
-
-The **Configuration Checklist** provides a convenient way to work through the settings that need to be reviewed and configured for a new site. You can link to this checklist from the installation success page and you can visit it at any time from **Administer** » **Administration Console** » **Configuration Checklist**.
-
-## Test-drive CiviCRM {:#test-drive}
-
-There should now be a **CiviCRM** link in your Drupal menu. Click that link and the CiviCRM Menu, Shortcuts, Search and New Individual Blocks should appear. You can now explore CiviCRM end-user features and begin configuring CiviCRM for your site/organization needs.
-
-## Using Encryption with MySQL
-
-If your MySQL database is hosted on a different machine than your web server, or if your host requires it, you can use TLS to encrypt the connection between the database and the web server.
-
-Full instructions on installing drupal are out of scope for this guide, but one method is to install into a test database first without MySQL encryption and then move the database to the live server and update settings.php to enable MySQL encryption.
-
-See [TLS for MySQL](/general/mysql_tls/) for introductory concepts and the settings for the CiviCRM database. For the Drupal database you have several options for updating settings.php:
-
-1. The simplest, which doesn't require a client certificate, but doesn't verify the server certificate.
-
-    ``` php
-    $databases = array (
-      'default' =>
-      array (
-        'default' =>
-        array (
-          'database' => 'drupal',
-          'username' => 'dbuser',
-          'password' => 'dbpassword',
-          'host' => 'db435.examplehost.com',
-          'port' => '',
-          'driver' => 'mysql',
-          'prefix' => '',
-          'pdo' => array(
-              PDO::MYSQL_ATTR_SSL_CA => TRUE,
-              PDO::MYSQL_ATTR_SSL_VERIFY_SERVER_CERT => FALSE,
-          ),
-        ),
-      ),
-    );
-    ```
-
-2. Verifies the server certificate, and doesn't require a client certificate.
-
-    !!! warning "Host name must match certificate name"
-        Note that the DATABASE SERVER certificate would have to have a CN (common name field) that matches exactly the `host` you are using in `$databases['default']['default']['host']`. So if the host is `db435.examplehost.com`, then that must be the name on the SERVER certificate.
-
-    ``` php
-    'pdo' => array(
-        // A certificate authority bundle.
-        // If you are using a self-signed server certificate in a development
-        // or testing environment, then this would be the same as the server
-        // certificate.
-        PDO::MYSQL_ATTR_SSL_CA => '/path/to/ca.crt',
-    ),
-    ```
-
-3. Client certificate/key pair (not self-signed), and do not verify the server certificate.
-
-    ``` php
-    'pdo' => array(
-        PDO::MYSQL_ATTR_SSL_VERIFY_SERVER_CERT => FALSE,
-        PDO::MYSQL_ATTR_SSL_KEY => '/path/to/your.key',
-        PDO::MYSQL_ATTR_SSL_CERT => '/path/to/your.crt',
-    ),
-    ```
-
-4. Client certificate/key pair (could be self-signed), and verify the server certificate.
-
-    ``` php
-    'pdo' => array(
-        // The SSL_CA can be the same as your.crt if self-signed, but note
-        // that it would also have to be a certificate authority for the
-        // server certificate. Self-signed would only be for local
-        // development testing.
-        PDO::MYSQL_ATTR_SSL_CA => '/path/to/ca.crt',
-        PDO::MYSQL_ATTR_SSL_KEY => '/path/to/your.key',
-        PDO::MYSQL_ATTR_SSL_CERT => '/path/to/your.crt',
-    ),
-    ```
-
-## D8 <-> CiviCRM Integration modules {:#integration-modules}
-
-### Webform CiviCRM module
-
-* [Project page on Drupal.org](https://www.drupal.org/project/webform_civicrm)
-* [Documentation on CiviCRM.org](https://docs.civicrm.org/webform-civicrm/en/latest)
-
-### CiviCRM Entity module
-
-* [Project page on Drupal.org](https://www.drupal.org/project/civicrm_entity)
-
-## Troubleshooting Resources {:#troubleshooting}
-
-* Review the [Troubleshooting](../general/troubleshooting.md) page for help with problems you may encounter during the installation.

docs/general/cli-cv.md

+<!-- markdownlint-disable MD046 -->
+
+???+ tldr "About this document"
+
+    This guide covers installation of CiviCRM on the command-line. It assumes that you previously completed these tasks:
+
+    1. Install a supported CMS
+    1. [Review the CiviCRM requirements](../general/requirements.md)
+    1. Download the CiviCRM code. (See "*Get the code*" for [Backdrop](../backdrop/index.md#download), [WordPress](../wordpress/index.md#download) or [Drupal](../drupal/index.md)).
+
+??? tldr "Limitations"
+
+    At time of writing, the CLI installer is primarily tested with Backdrop, Drupal 7/8/9, and WordPress.  It is primarily tested with
+    single-site deployments. For other configurations (e.g. Joomla; e.g. multisite), it may require extra variables/options/patches.
+
+<!-- markdownlint-enable MD046 -->
+
+The installer verifies requirements, prepares the database, and initializes the configuration file.
+
+Each Civi-CMS integration has an option to install through the web interface -- which is intended for new and casual administrators.
+
+For more advanced administrators, there is a general-purpose command-line interface (CLI) for installation. This is useful for:
+
+* Automating installation
+* Accessing uncommon or hidden options
+* Debugging or developing changes to the installer
+
+??? tip "Debugging and development"
+
+    If you are using the CLI for debugging or development, then the __CiviCRM Developer Guide__ has additional guidance.
+    See [Setup Reference: Overview](https://docs.civicrm.org/dev/en/latest/framework/setup/) and
+    [Setup Reference: Getting Started](https://docs.civicrm.org/dev/en/latest/framework/setup/getting-started/)
+
+## Download "cv"
+
+The CLI installer is part of [cv](https://github.com/civicrm/cv), a general-purpose tool for managing CiviCRM on the command-line.  `cv` is
+distributed in PHAR format, which is a portable executable file for PHP.  It should run in most Unix-like environments that support PHP.
+
+Simply download [cv.phar](https://download.civicrm.org/cv/cv.phar) and put it somewhere in the `PATH`. For example:
+
+```bash
+sudo curl -LsS https://download.civicrm.org/cv/cv.phar -o /usr/local/bin/cv
+sudo chmod +x /usr/local/bin/cv
+```
+
+## Change directory
+
+To run `cv`, you should navigate into the base folder of the CMS. For example:
+
+```bash
+cd /var/www/example.org
+```
+
+## Run the installer
+
+A typical installation command will look like this:
+
+```bash
+cv core:install --cms-base-url="URL" --lang="LANG"
+```
+
+For example:
+
+```
+$ cv core:install --cms-base-url="https://example.org" --lang="fr_CA"
+
+Found code for civicrm-core in /var/www/example.org/wp-content/plugins/civicrm/civicrm
+Found code for civicrm-setup in /var/www/example.org/wp-content/plugins/civicrm/civicrm/setup
+Creating file /var/www/example.org/wp-content/uploads/civicrm/civicrm.settings.php
+Creating civicrm_* database tables in hydrawpcms_p7urq
+```
+
+There are several available options for the installer. Expand the topics below for more details.
+
+<!-- FIXME: Options for multisite ... -->
+
+??? info "Option: CMS Base URL"
+
+    ```
+    cv core:install ... --cms-base-url="https://example.org"
+    ```
+
+    The "CMS Base URL" is the public URL of the website. It is required for most CLI installations.
+
+    Setting this option ensures that CiviCRM's background jobs (e.g. email-blasts and membership-reminders)
+    can generate correct URLs.
+
+??? info "Option: Database URL"
+
+     ```
+     cv core:install ... --db="mysql://user:pass@hostname:port/db"
+     ```
+
+     The "Database URL" points to the MySQL database where we will install CiviCRM.
+
+     By default, CiviCRM will use the same database as the CMS. However, some administrators prefer to use a separate database.
+     See [Requirements: MySQL: Connection](../general/requirements.md#mysql-connection) for more discussion.
+
+??? info "Option: Language"
+
+    ```
+    cv core:install ... --lang=fr_CA
+    ```
+
+    The "Language" is the primary language used by the organization.
+
+    Based on the language, the installer loads a set of *default configuration data*.  This includes common activity types ("Meeting" or
+    "Phone Call"), common location types ("Home" or "Office"), and so on.
+
+    __Note__: For a specific language to work, there *must* be corresponding data in the `l10n` folder.
+
+??? info "Option: Sample data"
+
+    ```
+    cv core:install ... -m loadGenerated=1
+    ```
+
+    The sample data provides a number of fake, auto-generated records -- i.e.  sample contacts, contributions, activities, etc.  The sample
+    data is useful for testing or reviewing CiviCRM.
+
+    __Note__: At time of writing, the sample data is only supported in the default locale, `en_US`.
+
+??? info "Option: Admin User (Standalone)"
+
+    ```
+    cv core:install ... -m extras.adminUser=USERNAME \
+      -m extras.adminPass=SECRET \
+      -m extras.adminEmail=ME@EXAMPLE.COM
+    ```
+
+    When installing CiviCRM Standalone, you should specify the credentials for the first administrative user.
+    If omitted, the credentials will be auto-generated and stored in the CiviCRM log.
+
+??? info "Option: Verbose output"
+
+    ```bash
+    ## Verbose
+    cv core:install ... -v
+
+    ## Very verbose
+    cv core:install ... -vv
+    ```
+
+    The "verbose" option  provides more details about how the installer works. Enabling the verbose option helps one identify problems.
+
+The installer may report a problem. Some common ones are:
+
+??? warning "Problem: CMS Base URL"
+
+    On most systems, the `--cms-base-url` cannot be detected automatically. You must explicitly set it.
+
+??? warning "Problem: File write permission"
+
+    The installer needs to create some files and folders. However, if the parent folder is locked-down, then you will need to relax permissions.
+
+    For example: in a Drupal site, the installer creates a file `web/sites/<sitename>/civicrm.settings.php`. You may need to mark
+    the parent folder (`web/sites/default` or `web/sites/example.org`) as writeable, e.g.:
+
+    ```bash
+    ## Grant write-access for the owner-user
+    chmod 755 web/sites/default
+
+    ## Grant write-access for all users
+    chmod 777 web/sites/default
+    ```
+
+??? warning "Problem: PHP or MySQL configuration"
+
+    The PHP or MySQL configuration may require an update - e.g. to expand the PHP memory limit, to enable a PHP extension, or to enlarge a MySQL buffer.
+    Common issues are discussed in the [Requirements](requirements.md).
+
+??? "Error: Call to undefined method Drupal::entityManager"
+    This error appears installing with the `--user` option under Drupal 9. Avoid this error simply by not using the `--user` option.
+
+For common problems, you can simply fix the problem and re-run the installer.
+
+For unusual problems, be sure to enable verbose output (`-v` or `-vv`). It may also help to [inspect the model, plugins, or requirements](https://docs.civicrm.org/dev/en/latest/framework/setup/getting-started/).
+
+## Configure the site
+
+After running `core:install`, you can login to the CMS, open CiviCRM, and configure additional details.  The [System Administrator
+Guide](https://docs.civicrm.org/sysadmin/en/latest/) has more advice on how to configure CiviCRM.
+
+If you are automating the installation, then you may wish to automate some common configuration steps, such as:
+
+??? info "Task: Manage extensions"
+
+    To view available extensions:
+
+    ```bash
+    cv ext:list
+    ```
+
+    To download extensions from the [Extension Directory](https://civicrm.org/extensions/):
+
+    ```bash
+    cv dl EXTENSION_1 EXTENSION_2 ...
+    ```
+
+    By default, it downloads stable releases. To download pre-releases (alphas/betas), use dev feed or an explicit URL:
+
+    ```bash
+    ## Download from the "dev" feed
+    cv dl --dev EXTENSION_1 EXTENSION_2 ...
+
+    ## Download from an explicit URL
+    cv dl EXTESION_KEY@ZIP_URL
+    ```
+
+    Alternatively, if you downloaded an extension by other means, then you may enable it:
+
+    ```bash
+    cv en EXTENSION_1 EXTENSION_2 ...
+    ```
+
+??? info "Task: Manage settings"
+
+    Many options are managed through the [Settings](https://docs.civicrm.org/dev/en/latest/framework/setting/) framework.
+    These may be configured in the CLI:
+
+    ```bash
+    ## List current settings
+    cv api setting.get
+
+    ## Update specific settings
+    cv api setting.create KEY_1=VALUE_1 KEY_2=VALUE_2 ...
+    ```
+
+??? info "Task: Clear caches"
+
+    ```bash
+    cv flush
+    ```
+
+<!--
+??? example "Example: Install Mosaico and Shoreditch"
+
+    Here's an example bringing the pieces together:
+
+    ```
+    cv dl --dev mosaico shoreditch
+    cv api setting.create theme_backend=shoreditch
+    ```
+-->

docs/general/i18n_l10n.md

-## Coming Soon
-
-!!! note ""
-    This page is a placeholder for content being migrated in from the old Wiki.
+## Using CivCRM in a language other than US-English
+
+CiviCRM uses US English by default but supports translation into a wide range of other languages with varying degrees of completeness.
+
+!!! note ""
+    If you want to help out with translations visit the [translation documentation](https://lab.civicrm.org/dev/translation/wikis).
+
+To enable use of CiviCRM in a new language translation you need to
+
+* download the translation files
+* install them in the appropriate directory
+* select the language in the Language settings
+
+The exact instructions on how to download and install the translations files differ between platforms:
+
+* [Backdrop](../backdrop/index.md#i18n)
+* [Drupal 9](../drupal/index.md#drupal9-i18n)
+* [Drupal 7](../drupal/index.md#drupal7-i18n)
+* [Joomla](../joomla/index.md#i18n)
+* [Wordpress](../wordpress/index.md#i18n)
+
+## Changing the default CiviCRM language after installation
+
+Once you have installed the translation files, you can change the language used by CiviCRM:
+
+* Go to **Administer > Localization > Languages, Currency, Location**
+* Select the new default language.
+* Update the default currency, money formatting options, default country, etc.
+
+You will also probably want to update the date and time formats:
+
+* Go to **Administer > Localization > Date Formats**
+
+Finally, you may notice that many other options in CiviCRM will not be correctly translated:
+
+* Individual prefixes (Mrs, M, etc)
+* Gender options (M, F, other)
+* Address Location Types
+* Some fieldsets in the "Edit Contact" screen
+
+These are known in CiviCRM as Option Values, and there are many of these.
+
+To avoid having to change every single setting, you can install the following extension: [fixoptiontranslations](https://lab.civicrm.org/extensions/fixoptiontranslations). Once the extension is enabled, all options will be translated. The extension can then be uninstalled and removed.
+
+## Updating translation files
+
+The easiest way to update your translations regularly is to use the [l10n update](https://github.com/cividesk/com.cividesk.l10n.update/) extension: 
+
+The "l10n update" extension will do a daily check to update the translation files for CiviCRM core, as well as for extensions. Every night, around 2 AM (North American Eastern Time), the CiviCRM website packages updated translation files. These are available at the following address: `https://download.civicrm.org/civicrm-l10n-core/mo/xx_XX/civicrm.mo` where `xx_XX` is an ISO language code corresponding to one CiviCRM has published translations for.
+
+For example, for Spanish CiviCRM core:
+
+```sh
+wget https://download.civicrm.org/civicrm-l10n-core/mo/es_ES/civicrm.mo
+```
+
+For the CDN Tax Receipts extension in Canadian French:
+
+```sh
+wget https://download.civicrm.org/civicrm-l10n-extensions/mo/cdntaxreceipts/fr_CA/cdntaxreceipts.mo
+```
+
+## Storing translation files in another directory
+
+By default, CiviCRM looks in `[civicrm.root]/l10n` for translation files. Since CiviCRM 5.23, there is a new setting available to store those files in another directory. This can be convenient when files are updated regularly, or when using the l10nupdate extension, which requires the files to be web-writable. More information, see [PR15408](https://github.com/civicrm/civicrm-core/pull/15408). As of this writing, this setting only applies to core translations, not extensions.
+
+## Native gettext
+
+`gettext` is the mechanism by which strings are translated. By default, CiviCRM uses the PHP-Gettext implementation. This implementation can cause a 20-30% performance loss.
+
+Since CiviCRM 4.2, it is possible to use native `gettext`. This may require some changes to your hosting environment and is therefore recommended mainly for sites hosted on dedicated environments (VPS or dedicated server, it may not work on shared hosting).
+
+To enable it:
+
+* PHP must have `gettext` support compiled in (it usually is the case, see `phpinfo()` for more information). Debian and Ubuntu include it by default.
+* The operating system must have the locale enabled. For example, on Linux-based systems, this is in `/etc/locale.gen`, or by typing this command:
+
+```sh
+locale -a
+```
+
+Debian/Ubuntu systems can enable locales by typing:
+
+```sh
+dpkg-reconfigure locales
+```
+
+!!! note
+    The "UTF-8" variant of the locale must be enabled. For example: "fr_FR.UTF-8".
+
+Apache or PHP-FPM must be restarted after adding a new locale. Finally, uncomment the following in civicrm.settings.php:
+
+```php
+define('CIVICRM_GETTEXT_NATIVE', 1);
+```

docs/general/permissions.md

-## Coming Soon
-
-!!! note ""
-    This page is a placeholder for content being created to help configure filesystem permissions for CiviCRM.
+## Coming Soon
+
+!!! note ""
+    This page is a placeholder for content being created to help configure filesystem permissions for CiviCRM.

docs/general/unicode_pdf.md

+# Using your own font or CJK characters in PDF output
+
+As of CiviCRM 6.0, most unicode characters will output correctly in PDFs. But if you need CJK characters DejaVu does not contain those, so you will need to install another font file such as SimSun using the steps below.
+
+If you are still seeing question marks (?) in place of unicode characters, even for non-CJK characters, check that you don't have a `<font>` tag or `style` attribute in the html specifically setting a font that doesn't support unicode.
+
+## Option A: Using web fonts
+
+1. In your html template add a `<link>` tag like the following, e.g. for the Noto Sans SC font: `<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Noto+Sans+SC:wght@100..900">`
+1. Specify the font using CSS in the templates where you use the CJK characters. You can use the Source button in CKEditor to do this and type it directly into the HTML: e.g. `<p style="font-family: Noto Sans SC;">的</p>`
+
+## Option B: Storing fonts locally
+
+1. While option A will cache a version of the file after the first download, it may not be available on the internet or may be a commercial font.
+1. Create a folder in a location that won't get overwritten when you upgrade, e.g. sites/default/fonts for Drupal.
+1. Copy the .ttf font file you want to use into that folder.
+1. Run `php -r 'require_once "/path/to/civicrm/vendor/autoload.php"; $f = \FontLib\Font::load("/full/path/to/the/ttf/file"); $f->parse(); $f->saveAdobeFontMetrics("/full/path/to/output/ufm/file");'`
+    * e.g. `php -r 'require_once "/var/www/sites/all/modules/civicrm/vendor/autoload.php"; $f = \FontLib\Font::load("/var/www/sites/default/fonts/simsun.ttf"); $f->parse(); $f->saveAdobeFontMetrics("/var/www/sites/default/fonts/simsun.ufm");'`
+1. Create a file in that folder called `installed-fonts.json` that looks like this:
+    ```json
+    {
+        "simsun": {
+            "normal": "simsun"
+        }
+    }
+    ```
+1. Visit Administer - System Settings - Misc and in the field for DOMPDF Font Folder put the full path to the font folder you created in step 2.
+1. Specify the font using CSS in the templates where you use the CJK characters. You can use the Source button in CKEditor to do this and type it directly into the HTML: e.g. `<p style="font-family: simsun;">的</p>`
+1. Note any fonts you set up here are in addition to the ones distributed with dompdf/CiviCRM. You do not need to copy those core fonts over or add entries in this json file to use them.