CiviCRM Standalone is under ___active development___, and it has [many open issues](https://lab.civicrm.org/dev/core/-/issues/?label_name%5B%5D=comp%3AStandalone).
You should regard this as a ___developer preview___. It is not yet supported for live sites.
CiviCRM Standalone is currently in beta release.
___As the code and documentation evolve, you may need to periodically delete and reinstall___.
Testing is encouraged, and your help identifying issues is greatly appreciated. Please [add issues that you find on the main issue tracker, using the comp:Standalone tag](https://lab.civicrm.org/dev/core/-/issues/?label_name%5B%5D=comp%3AStandalone).
Standalone is not yet supported for live sites.
???+ tldr "About this document"
This guide covers installation of CiviCRM standalone (without any co-located CMS). It assumes that you previously
This guide covers installation of CiviCRM Standalone (without a parent 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/).
## Step 1. Choose an install method
<aname="directory"></a><!-- old anchor -->
## Get the code {:#download}
There are currently four methods for installing CiviCRM Standalone.
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 "Option 1. Download a release tarball - most sites"
??? example "Download the starter template"
This is the recommended install method for most regular sites. The rest of this page assumes you installing this way.
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.__)
??? example "Option 2. Use composer - complex sites"
> (__The starter template is not well-suited to development. Developers should download CiviCRM directly.__)
Using composer allows more automated management of site installation and packages. It may be useful in some contexts, such as automated deployments. It requires shell access and is *not* recommended if you are new to CiviCRM.
To use the starter template, download [civicrm-standalone.git](https://github.com/civicrm/civicrm-standalone) and run `composer`:
??? example "Option 3. Using CiviCRM Buildkit - for developers"
After installation, you should see these files and folders:
If you are a developer contributing to CiviCRM Core, then it is recommend to use [CiviCRM Buildkit](https://docs.civicrm.org/dev/en/latest/tools/buildkit/) to create Standalone sites. The primary site template is called `standalone-clean`. A composer-style alternative is called `standalone-composer`.
```
/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
```
Using Buildkit is only recommended for test sites. If you are hoping to run CiviCRM Standalone in production in future, you should follow Option 1 or 2.
??? 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).
??? example "Option 4. Download with git - not recommended"
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:
You can also install CiviCRM Standalone by cloning the git repo directly. This is generally not recommended - if you need git it is probably easier to use Buildkit.
There is a new project to create a Docker image for CiviCRM Standalone. If you have used Docker before, this can be a quick way to get up and running. You can see progress on the project and find install instructions here: https://lab.civicrm.org/michaelmcandrew/civioneclick-docker
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)
```
For Buildkit, see the linked Buildkit documentation.
??? example "Download CiviCRM directly (PHP built-in web-server)"
For composer or git installs, see the Standalone Alternative Install Methods (*TODO*).
Primary development of CiviCRM focuses on [civicrm-core](https://github.com/civicrm/civicrm-core) and [civicrm-packages](https://github.com/civicrm/civicrm-packages).
For Docker, see the linked repository.
You can download these projects directly:
The rest of this page assumes you are installing from a release tarball (Option 1).
Choose the option that ends `*-NIGHTLY-standalone` and download it.
This folder contains configuration and data-files, so it is important for system-administration.
This is the very latest version available, but be warned, there may be bugs! 🐛
??? 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).
## Step 3. Deploy the code to your web server/hosting {:#download}
After the system has been fully installed and used, you can expect the folder to look like this:
The release contains all the code for your site in a compressed file.
| File/Folder | Environments | Description |
At this stage you need to extract the code and transfer it your web server.
If you are using web hosting, you may be able to upload the compressed file and then extract it, or extract it on your computer and then upload the extracted files. It depends a bit on your hosting configuration.
The key thing is to maintain the folder structure from the release archive. Your main folder should contain at least a `civicrm.standalone.php` file, as well as `core`, `public` and `private` subfolders.
You need to make sure this folder is in a place where your webserver can point to it. Take a note of this folder path (e.g. `/var/www/example.org` or `/mywebhost/user123124019231/sites/civicrm`), you'll need it later.
??? info "More detail: CiviCRM Standalone folder structure"
Standalone sites should have a main folder which in Standalone is known as the _"project root"_.
After the system has been fully installed and used, you can expect the contents of that folder to look like this:
| File/Folder | Contents |
| -- | -- | -- |
| `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 |
| `civicrm.standalone.php` | Standalone boot file. This identifies the Standalone Project Root, and identifies the locations of the CiviCRM code and settings files. |
| `core/` | Core source code for CiviCRM |
| `private/` | Private site files which should not be accessible over the web |
| `private/civicrm.settings.php` | Configuration file with low level settings for CiviCRM. |
| `private/log/` | Log files |
| `private/cache/` | Cache files for CiviCRM's template compiler |
| `private/l10n/` | Translation files |
| `private/attachment/` | Private files uploaded to your CiviCRM site - such as files uploaded to a specific contact |
| `public/` | Public site files which *should* be accessible over the web |
| `public/media/` | Public files uploaded to your site, like images that appear on a contribution page or in a mass email |
| `public/ang/` | Angular templates - e.g. for custom forms added to your site with FormBuilder |
| `ext/` | CiviCRM extensions you have added to your site |
<!-- 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:
## Step 4. Get translations if needed {:#i18n}
The default CiviCRM language is US English (`en_US`). You can select a different language or locale during the web installation step, and the chosen translations will be downloaded for you. You don't need to do anything now.
* "_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).
Alternatively, if you need the web installer in another language you can manually download all the translation files now.
## Get the translations {:#i18n}
Head to https://civicrm.org/download and choose "Internationalisation files" from the Download dropdown, then extract these in your `private/l10n` directory.
The basic CiviCRM release includes support for US English (`en_US`). To use another language or dialect you can select the locale during the setup when installing through the web user interface or by passing it in as a parameter to `cv` when installing via the command line.
The translation files will then be downloaded by the installer. There is no need anymore to download those files.
If you want the installer in the web user interface in another language you have to manually download the translation files first.
## Configure MySQL {:#mysql}
## Step 5. Configure MySQL {:#mysql}
CiviCRM stores data in MySQL (or, equivalently, MariaDB). You will need to provide a new database and determine key details:
...
...
@@ -178,7 +140,15 @@ CiviCRM stores data in MySQL (or, equivalently, MariaDB). You will need to provi
* MySQL username
* MySQL password
Here are some typical ways to setup a MySQL database.
??? example "_MySQL_: Set up a new database on your webhosting"
If you are using a webhost, they will often provide a UI for this, from which you can get these details.
Alternatively, they may provide _phpmyadmin_ or _cpanel_ access to your database server. You can find guides for these tools online, e.g. https://phppot.com/mysql/phpmyadmin-create-database/ or https://support.cpanel.net/hc/en-us/articles/360057550753-How-to-create-a-database-and-database-user-in-cPanel
<!-- Might be good to have more specific pointers for phpmyadmin or cpanel? -->
??? example "_MySQL_: Create database via command-line"
...
...
@@ -222,17 +192,23 @@ Here are some typical ways to setup a MySQL database.
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.
## Configure your webserver {:#webserver}
!!! tip "PHP's built-in HTTP server doesn't require configuration. If using it, then proceed to [Run the installer](#installer)."
Now you need to configure your webserver to point to your CiviCRM Standalone project folder.
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"
??? example "_Web hosting_: Point a new subdomain to your Standalone project folder"
If you are using web hosting and your release code is in e.g. `/mywebhost/user123/my-sites/civicrm`, then you should just need to point a domain or subdomain from your hosting to this directory.
You will need to make sure PHP is enabled, including the php modules detailed in the Installation Requirements. Your web host may provide a UI, or you may need to add a `php.ini` file specifying options.
You should specify that the `private` folder should *not* be web accessible.
??? example "_Apache_: Configure a virtual-host on Debian-based server"
If you created a folder like `/var/www/example.com/web`, then you probably need to configure the web-server to read this folder.
...
...
@@ -250,23 +226,31 @@ The exact steps vary based on your specific environment. Here are some typical t
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"
??? example "_nginx_: Configure a virtual-host on Debian-based server"
(*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 nginx virtual host config is in progress - check https://github.com/civicrm/civicrm-standalone for updates - contributions 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.
## Configure webserver permissions {:#webserver}
There are two important folders, `./data/` and `./web/upload/`. Here is a typical way to grant access for the group `www-data`:
Your webserver will need to be able to write to at least your `public` and `private` directories. If you wish to install extensions through the web UI on your site, the webserver will also need to write to the `ext` directory.
On many webhosts the webserver will be able to write to all directories, and you won't need to do anything.
If you have `ssh` access to your server, you may need to set the user permissions directly.
??? example "_Permissions_: Grant write access to `public`, `private` and `ext` directories on Linux server"
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 write to data folders. Typically you will want to grant access for the group `www-data` to `private`, `public` and `ext` folders.
```bash
cd /var/www/example.com
cd /var/www/example.com/web
chmod 2770 web/upload data
chmod g+rwX -R web/upload data
chgrp -R www-data web/upload data
chmod 2770 private public ext
chmod g+rwX -R private public ext
chgrp -R www-data private public ext
```
<!-- Should we recommend `setfacl` (Linux) and `chmod +a` (MacOS)? Or is this assuming that current-user is also in `www-data`? -->
...
...
@@ -278,17 +262,18 @@ The installer verifies requirements, prepares the database, and initializes the
??? example "Run installer via web UI"
1. Open the `/civicrm` page on your website. This may look like:
1. Head to 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.
* You will need to provide the details for the database you created earlier
* You also have to provide a username, password and e-mail address for the site adminstrator user. Note: this login is totally separate from the database username and password in step 1.
* *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.
* You can select another language if you want CiviCRM to be installed in another language then English. The installer will then download the translation files for you.
* You also have to provide a username, password and e-mail address for the administrator user.
* You can select another language if you want CiviCRM to be installed in another language then English US. The installer will then download the translation files for you.
* Finally, click "Install CiviCRM".
3. After installing, you should navigate to the login screen (`/civicrm/login`), e.g.
3. After installing, you should navigate to the login screen (`/civicrm/login`) to login with the credentials you chose earlier, e.g.
