Skip to content

Install CiviCRM (Standalone)

Active development

CiviCRM Standalone is under active development, and it has many open issues. 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.

About this document

This guide covers installation of CiviCRM standalone (without any co-located CMS). It assumes that you previously reviewed the CiviCRM requirements.

Alternative: Civibuild for developers

If you plan to develop patches for CiviCRM, then please read the Developer Guide for information about Buildkit and civibuild.

Get the code

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:

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 and run composer:

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
Download CiviCRM directly (Standard web-server)

Primary development of CiviCRM focuses on civicrm-core and 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:

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.

./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)
Download CiviCRM directly (PHP built-in web-server)

Primary development of CiviCRM focuses on civicrm-core and civicrm-packages.

You can download these projects directly:

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:

./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.

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.
web/core/ Varies All source code for CiviCRM. Appears in direct installations. May be physical or logical.
web/upload/ All Public data files
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 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

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

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.

MySQL: Create database via command-line

Open the mysql command-line interface. You may need to run one of these commands:

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__):

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)

Configure HTTP

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.

PHP's built-in HTTP server doesn't require configuration. If using it, then proceed to Run the installer.

The exact steps vary based on your specific environment. Here are some typical tasks for common environments:

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. (This example is for Drupal, but similar steps should work for CiviCRM Standalone - simply adjust the DocumentRoot and ServerName.)

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...)

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:

cd /var/www/example.com

chmod 2770 web/upload data
chmod g+rwX -R web/upload data
chgrp -R www-data web/upload data

Run the 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).

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 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.
    • 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
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:

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.

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).

Review the 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

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

  • Review the Troubleshooting page for help with problems you may encounter during the installation.