Nothing Special   »   [go: up one dir, main page]
Skip to content

Install CiviCRM (Standalone)

Beta release

CiviCRM Standalone is currently in beta release.

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.

Standalone is not yet supported for live sites.

About this document

This guide covers installation of CiviCRM Standalone (without a parent CMS). It assumes that you previously reviewed the CiviCRM requirements.

Step 1. Choose an install method

There are currently five options for installing CiviCRM Standalone. If in doubt, Option 1 is the recommended method for most sites.

Option 1. Download a release tarball - most sites

This is the recommended install method for most regular sites. The rest of this page assumes you installing this way.

Option 2. Use composer - complex sites

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.

Option 3. Using CiviCRM Buildkit - for developers

If you are a developer contributing to CiviCRM Core, then it is recommend to use CiviCRM Buildkit to create Standalone sites. The primary site template is called standalone-clean. A composer-style alternative is called standalone-composer.

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.

Option 4. Download with git - not recommended

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.

Option 5. Using Docker - new

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 on the project repo

The rest of this page assumes you are installing from a release tarball (Option 1).

Step 2. Download a release

The next step is to get the CiviCRM code. You can choose which version you want to install.

This month's release

The latest monthly release is available from the main release page.

As Standalone is still in beta, there is not much advantage to running this month's release over the next Release Candidate (RC).

Download this month's release

Next month's release

Next month's release is available to download from the latest releases page.

Choose the option that ends *-RC-standalone and download it.

Testing the RC will help improve the stability of the next month's release.

Download next month's release

Bleeding edge nightly build

You can also download that night's build from the latest releases page.

Choose the option that ends *-NIGHTLY-standalone and download it.

This is the very latest version available, but be warned, there may be bugs! 🐛

Download last night's release

Step 3. Deploy the code to your web server/hosting

The release contains all the code for your site in a compressed file.

At this step 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.

Note: you should point a domain or subdomain directly at the Standalone project root. Installing to a URL subdirectory (e.g. https://mysite.com/projects/standalone) is not currently supported.

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

Step 4. Get translations if needed

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.

Alternatively, if you need the web installer in another language you can manually download all the translation files now.

Head to https://civicrm.org/download and choose "Internationalisation files" from the Download dropdown, then extract these into your core directory. The extracted files should end up in core/l10n and core/sql.

Step 5. 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
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

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)

Step 6. Configure your webserver

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:

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.

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.

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 server

(*Example nginx virtual host config is in progress - check https://github.com/civicrm/civicrm-standalone for updates - contributions welcome! *)

Step 7. Configure webserver permissions

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.

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.

cd /var/www/example.com/web

chmod 2770 private public ext
chmod g+rwX -R private public ext
chgrp -R www-data private public ext

Step 8. 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. 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 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 US. The installer will then download the translation files for you.
    • Finally, click "Install CiviCRM".
  3. After installing, you should see a confirmation page confirming installation has completed correctly.
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).

Log in and review users and permissions

You should now be able to log in to your site at e.g. https://your-site.test/civicrm/login. Use the administrator username and password you created during install.

Head to Adminster >> Users and Permissions to configure users and roles for your site.

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

Start exploring your new CiviCRM Standalone site. Please report any issues you find in the Issue Tracker: https://lab.civicrm.org/dev/core/-/issues/?label_name%5B%5D=comp%3AStandalone

Addenda

Troubleshooting

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