From ae3f6f410ff184214f7681976fda3677f343c2f4 Mon Sep 17 00:00:00 2001
From: Tim Otten <totten@civicrm.org>
Date: Tue, 18 Jul 2023 01:14:52 -0700
Subject: [PATCH] docs/standalone/index.md - Add sections about MySQL and HTTPD
---
docs/standalone/index.md | 121 +++++++++++++++++++++++++++++++++++----
1 file changed, 111 insertions(+), 10 deletions(-)
diff --git a/docs/standalone/index.md b/docs/standalone/index.md
index 819aa10..6de8423 100644
--- a/docs/standalone/index.md
+++ b/docs/standalone/index.md
@@ -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:
You can download these projects directly:
```bash
+ mkdir -p ~/src
git clone https://github.com/civicrm/civicrm-core ~/src/civicrm
git clone https://github.com/civicrm/civicrm-packages ~/src/civicrm/packages
cd ~/src/civicrm
@@ -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.
* `https://example.com/civicrm/login`
--
GitLab