Skip to content
Snippets Groups Projects
Commit d3ae4dd1 authored by totten's avatar totten
Browse files

Merge branch 'standalone' into 'master' 

Add installation docs for CiviCRM Standalone

See merge request !56
parents 8bb11c02 ae3f6f41
No related branches found
No related tags found
1 merge request!56Add installation docs for CiviCRM Standalone
Hide whitespace changes
Inline Side-by-side
docs/general/cli-cv.md
+ 11
− 0
View file @ d3ae4dd1
......@@ -120,6 +120,17 @@ There are several available options for the installer. Expand the topics below f
__Note__: At time of writing, the sample data is only supported in the default locale, `en_US`.
??? info "Option: Admin User (Standalone)"
```
cv core:install ... -m extras.adminUser=USERNAME \
-m extras.adminPass=SECRET \
-m extras.adminEmail=ME@EXAMPLE.COM
```
When installing CiviCRM Standalone, you should specify the credentials for the first administrative user.
If omitted, the credentials will be auto-generated and stored in the CiviCRM log.
??? info "Option: Verbose output"
```bash
......
docs/standalone/index.md 0 → 100644
+ 324
− 0
View file @ d3ae4dd1
???+ error "Active development"
CiviCRM Standalone is under ___active development___, and it has [many open issues](https://lab.civicrm.org/dev/core/-/issues/2998).
You should regard this as a ___developer preview___. It is not yet supported for live sites.
___As the code and documentation evolve, you may need to periodically delete and reinstall___.
???+ tldr "About this document"
This guide covers installation of CiviCRM standalone (without any co-located CMS). It assumes that you previously
[reviewed the CiviCRM requirements](../general/requirements.md).
??? tldr "Alternative: Civibuild for developers"
If you plan to develop patches for CiviCRM, then please read the [Developer Guide](https://docs.civicrm.org/dev/en/latest) for information about [Buildkit](https://docs.civicrm.org/dev/en/latest/tools/buildkit/) and [civibuild](https://docs.civicrm.org/dev/en/latest/tools/civibuild/).
<a name="directory"></a><!-- old anchor -->
## Get the code {:#download}
CiviCRM Standalone is available via `git`. As a project in active development, it is best to download the current developmental branch (`master`).
Here are a few alternative ways to download the `git` code and the dependencies:
??? example "Download the starter template"
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.__)
To use the starter template, download [civicrm-standalone.git](https://github.com/civicrm/civicrm-standalone) and run `composer`:
```bash
git clone https://github.com/civicrm/civicrm-standalone /var/www/example.com
cd /var/www/example.com
composer install
```
After installation, you should see these files and folders:
```
/var/www/example.com/ Project root
+ civicrm.config.php.standalone Project flag file
+ composer.json Configure which packages to download
+ data/ Private data files (e.g. application logs)
+ web/ Public HTTP root
+ web/assets/ Published JS/CSS/image assets (copied from source-code)
+ web/upload/ Public data files (e.g. image-attachments for newsletters)
+ vendor/ All downloaded source code
```
??? example "Download CiviCRM directly (Standard 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).
You can deploy these directly on a standard web-server (such as Apache HTTPD or nginx HTTPD). For example, many
Apache deployments store sites in `/var/www/{DOMAIN-NAME}`. You may download like so:
```bash
mkdir -p /var/www/example.com/web
cd /var/www/example.com/web
git clone https://github.com/civicrm/civicrm-core core
git clone https://github.com/civicrm/civicrm-packages core/packages
cd core
composer install
```
All major source-code lives in the `core` folder. Additionally, you will need to deploy a few files specifically to the web-server.
```bash
./tools/standalone/bin/scaffold /var/www/example.com
```
After installation, you should see these files and folders:
```
/var/www/example.com/ Project root
+ civicrm.config.php.standalone Project flag file
+ data/ Private data files (e.g. application logs)
+ web/ Public HTTP root
+ web/core/ All downloaded source code
+ web/upload/ Public data files (e.g. image-attachments for newsletters)
```
??? 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).
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
composer install
```
This provides all major source-code. However, we also need to create data-folders and
start the PHP built-in web-server. This command will do both:
```bash
./tools/standalone/bin/serve
```
After installation, you should see these files and folders:
```
/home/myuser/src/civicrm/ All downloaded source code
+ srv/ All runtime service files
+ civicrm.config.php.standalone Project flag file
+ data/ Private data files (e.g. application logs)
+ web/ Public HTTP root
+ web/core/ Virtualized alias for ~/src/civicrm
+ web/upload/ Public data files (e.g. image-attachments for newsletters)
```
After downloading the code, take note of the _standalone service root_. In the examples above, this folder was called:
* `/var/www/example.com` ("_Download the starter template_")
* `/var/www/example.com` ("_Download CiviCRM directly (Standard web-server)_")
* `/home/myuser/src/civicrm/srv` ("_Download CiviCRM directly (PHP built-in web-server)_")
This folder contains configuration and data-files, so it is important for system-administration.
??? 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
(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 |
| -- | -- | -- |
| `civicrm.config.php.standalone` | All | Project flag file. The file can be empty. Helps sysadmin tools identify project. |
| `data/` | All | Private data files |
| `data/civicrm.settings.php` | All | Configuration file for CiviCRM. |
| `data/ConfigAndLog/` | All | Application logs |
| `data/templates_c/` | All | Compilation cache |
| `web/` | All | Public HTTP root |
| `web/assets/` | Varies | JS/CSS/image assets from CiviCRM. Appears in the starter template. See also: [civicrm-asset-plugin](https://lab.civicrm.org/dev/civicrm-asset-plugin). |
| `web/core/` | Varies | All source code for CiviCRM. Appears in direct installations. May be physical or logical. |
| `web/upload/` | All | Public data files |
<!-- FIXME: Describe more items from `web/upload/` -->
??? info "More detail: Comparison of deployment types"
At time of writing, CiviCRM Standalone is a new way to install -- and the primary audience will be existing developers (who
have previously used other CiviCRM deployment types). To get situated, here are a few quick comparisons:
* "_Download the starter template_" is similar to D8/D9/D10. `civicrm-standalone` is analogous to `drupal/recommended-project`.
* All these projects use `composer` for top-level administration by site-builders.
* All these projects store source code in a private `vendor` folder.
* 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.
* "_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*).
??? example "Run installer via web UI"
1. Open the `/civicrm` page on your website. This may look like:
* `https://example.com/civicrm`
* `http://localhost:8000/civicrm`
* `http://example.127.0.0.1.nip.io:8001/civicrm`
2. The CiviCRM installer will open.
* *If there are unmet requirements*, the installer will list them. Consult the [Requirements](../general/requirements.md) documentation for additional advice.
* *If all the requirements are met*, proceed through the questionnaire.
* Finally, click "Install CiviCRM".
3. After installing, you should navigate to the login screen (`/civicrm/login`), e.g.
* `https://example.com/civicrm/login`
* `http://localhost:8000/civicrm/login`
* `http://example.127.0.0.1.nip.io:8001/civicrm/login`
??? example "Run installer via command-line"
CiviCRM has a command-line administration tool, `cv`, which can perform installation. For a local dev site, a typical install command might be:
```bash
cd /path/to/standalone-service-root
cv core:install -v \
--cms-base-url=http://localhost:8000 \
--db=mysql://USER:PASS@HOST:PORT/DATABASE \
-m extras.adminUser=USERNAME \
-m extras.adminPass=SECRET \
-m extras.adminEmail=ME@EXAMPLE.COM
```
For full details, see [command-line installer](../general/cli-cv.md).
The installer will verify that you've downloaded the correct version of CiviCRM, and will check your server environment to make sure it meets CiviCRM requirements. It will then create and populate a database for CiviCRM as well as create your CiviCRM settings file (civicrm.settings.php).
<!-- Do we need to suggest reviewing permissions at the start -- given that we control defaults and given that there's a general checklist? -->
## Review the checklist {:#checklist}
The **Configuration Checklist** provides a convenient way to work through the settings that need to be reviewed and configured for a new site. You can link to this checklist from the installation success page AND you can visit it at any time from **Administer** » **Administration Console** » **Configuration Checklist**.
## Test-drive CiviCRM {:#test-drive}
There should now be a **CiviCRM** link in your 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.
## Addenda
### Troubleshooting {:#troubleshooting}
* Review the [Troubleshooting](../general/troubleshooting.md) page for help with problems you may encounter during the installation.
mkdocs.yml
+ 1
− 0
View file @ d3ae4dd1
......@@ -31,6 +31,7 @@ nav:
- Install CiviCRM on Drupal: drupal/index.md
- Install CiviCRM on Joomla: joomla/index.md
- Install CiviCRM on WordPress: wordpress/index.md
- "Install CiviCRM (Standalone)": standalone/index.md
- General:
- Requirements: general/requirements.md
- Permissions: general/permissions.md
......
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