@@ -26,7 +26,7 @@ Here are a few alternative ways to download the `git` code and the dependencies:
The starter template is useful for demoing CiviCRM Standalone. It defines a template for creating a new web-site, including the skeletal
file-structure and a list of recommended packages.
> (__In the future, this will be recommended for building live sites. It allows maximum flexibility for adding and updating sub-packages.__)
> (__The starter template is not well-suited to development. Developers should download CiviCRM directly.__)
...
...
@@ -85,8 +85,6 @@ Here are a few alternative ways to download the `git` code and the dependencies:
+ web/upload/ Public data files (e.g. image-attachments for newsletters)
```
Finally, you may need to update the local HTTPD to read content from `/var/www/example.com/web`.
??? example "Download CiviCRM directly (PHP built-in web-server)"
Primary development of CiviCRM focuses on [civicrm-core](https://github.com/civicrm/civicrm-core) and [civicrm-packages](https://github.com/civicrm/civicrm-packages).
...
...
@@ -94,6 +92,7 @@ Here are a few alternative ways to download the `git` code and the dependencies:
@@ -129,9 +128,9 @@ This folder contains configuration and data-files, so it is important for system
??? info "More detail: Structure of the standalone service root"
In every deployment, one folder is designated as the _standalone service root_. The internal structure is largely the same
In every deployment, one folder is designated as the _standalone service root_. The internal structure is largely the same
(with a few variations).
After the system has been fully installed and used, you can expect the folder to look like this:
| File/Folder | Environments | Description |
...
...
@@ -159,16 +158,118 @@ This folder contains configuration and data-files, so it is important for system
* All these projects use [civicrm-asset-plugin](https://lab.civicrm.org/dev/civicrm-asset-plugin) to publish assets.
* "_Download CiviCRM directly_" is similar to D7/WP/BD and `cividist`.
* All these projects store source code in a public folder.
* We've never supported "_PHP built-in web-server_" before. This is new.
* Defining this for each CMS is more work (and not really our remit). With standalone, this is easier to do (and it's within our remit).
* There is no system-level httpd. There is no `/var/www`. You can put files anywhere you want (eg in your `$HOME`).
* "_PHP built-in web-server_" is a new style which we haven't supported before.
* There is no system-level httpd. There is no `/var/www`. You can put the source anywhere (eg in `$HOME/src`).
* In lieu of `/var/www/example.com`, we have `CIVICRM/srv`.
* Defining this for each CMS is more work (and not really our remit). With standalone, this is easier to do (and it's within our remit).
## Get the translations {:#i18n}
The basic CiviCRM release includes support for US English (`en_US`). To use another language or dialect, please [download and extract the translation files](../general/i18n_l10n.md).
## Configure MySQL {:#mysql}
CiviCRM stores data in MySQL (or, equivalently, MariaDB). You will need to provide a new database and determine key details:
* MySQL hostname/IP (*and, optionally, port number*)
* MySQL database name
* MySQL username
* MySQL password
Here are some typical ways to setup a MySQL database.
??? example "_MySQL_: Create database via command-line"
Open the `mysql` command-line interface. You may need to run one of these commands:
```bash
mysql
mysql -u root
mysql -u root -p
mysql -u root -p --host=db.example.com --port=3306
```
This should display a welcome message:
```
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 6879
Server version: 8.0.29 Source distribution
Copyright (c) 2000, 2022, Oracle and/or its affiliates.
Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective
owners.
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
mysql>
```
Now, you can configure a database (`civicrm`), user (`civicrm`), and password (`__TOP_SECRET__`):
```sql
mysql> CREATE DATABASE civicrm CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
Query OK, 1 row affected (0.00 sec)
mysql> CREATE USER 'civicrm'@'localhost' IDENTIFIED BY '__TOP_SECRET__';
Query OK, 0 rows affected (0.01 sec)
mysql> GRANT ALL on civicrm.* to 'civicrm'@'localhost';
Query OK, 0 rows affected (0.01 sec)
```
<!-- Feel free to add links for phpmyadmin docs or cpanel docs or somesuch... -->
## Configure HTTP {:#webserver}
If you are using a standard web-server (Apache/nginx) provided by Debian, Red Hat, or a similar Linux distribution, then you must configure it.
!!! tip "PHP's built-in HTTP server doesn't require configuration. If using it, then proceed to [Run the installer](#installer)."
The exact steps vary based on your specific environment. Here are some typical tasks for common environments:
??? example "_Apache_: Configure a virtual-host on Debian-based platform"
If you created a folder like `/var/www/example.com/web`, then you probably need to configure the web-server to read this folder.
The essence is to create a configuration file underneath `/etc/apache2/sites-*` with a `<VirtualHost>` declaration, such as:
```
<VirtualHost *:80>
ServerAdmin me@example.com
DocumentRoot /var/www/example.com/web
ServerName example.com
...
</VirtualHost>
```
For a complete example, see [Installing virtual hosts for Drupal sites](https://www.drupal.org/node/111238). (This example is for Drupal,
but similar steps should work for CiviCRM Standalone - simply adjust the `DocumentRoot` and `ServerName`.)
??? example "_nginx_: Configure a virtual-host on Debian-based platform"
(*At time of writing, I haven't seen an nginx config for standalone. But it's probably not hard for an nginx expect to write one... patch welcome...*)
??? example "_Permissions_: Grant write access to `./data/` and `./web/upload/`"
In most Linux distributions, the web server runs with a special user+group (such as `www-data` or `www`). You must specifically grant access for
this user to manage data folders.
There are two important folders, `./data/` and `./web/upload/`. Here is a typical way to grant access for the group `www-data`:
```bash
cd /var/www/example.com
chmod 2770 web/upload data
chmod g+rwX -R web/upload data
chgrp -R www-data web/upload data
```
<!-- Should we recommend `setfacl` (Linux) and `chmod +a` (MacOS)? Or is this assuming that current-user is also in `www-data`? -->
<!-- These are the configs I've liked: https://github.com/amp-cli/amp/blob/0.7.3/app/defaults/services.yml#L189-L199 -->
## Run the installer {:#installer}
The installer verifies requirements, prepares the database, and initializes the configuration file. You may run the installer through the web interface (*which is simpler*) or the command-line interface (*which has more options*).
...
...
@@ -181,7 +282,7 @@ The installer verifies requirements, prepares the database, and initializes the
* `http://example.127.0.0.1.nip.io:8001/civicrm`
2. The CiviCRM installer will open.
* *If there are unmet requirements*, the installer will list them. Consult the [Requirements](../general/requirements.md) documentation for additional advice.
* *If all the requirements are met*, proceed through the brief questionnaire.
* *If all the requirements are met*, proceed through the questionnaire.
* Finally, click "Install CiviCRM".
3. After installing, you should navigate to the login screen (`/civicrm/login`), e.g.
