CiviCRM Docker

This repository contains resources to run CiviCRM on Docker.

Container images are published to Docker Hub as part of CiviCRM's regular release process. Please note that images are only published for the latest version of CiviCRM. It may take up to 24 hours for the new image to be released.

If you are looking for a ready to use CiviCRM application, use civicrm/civicrm. If you are looking for an image that you can use as part of a customised Docker build process, use civicrm/civicrm-base.

If you are looking for CiviCRM on WordPress please see WORDPRESS.md.

There are currently no official images for CiviCRM with Joomla, Backdrop, or Drupal but we welcome contributions to add these images.

Quick start

Note: these instructions provide a minimal local environment for testing purposes. You will likely want to adapt this for running in production. The instructions assume you are comfortable working with docker and docker compose. If that's not the case, then see the resources below for a quick introduction:

• https://docs.docker.com/get-started/
• https://docs.docker.com/compose/gettingstarted

Running the image

Run the CiviCRM image with docker run --detach --publish 8000:80 civicrm/civicrm. You'll see CiviCRM's installation screen at http://localhost:8000 where you will be prompted for database credentials, etc.

Using docker compose

A more complete 'quick start' built with docker compose can be found in the example directory.

1. clone this repository git clone https://github.com/civicrm/civicrm-docker
2. change into the example directory cd civicrm-docker/example/civicrm
3. create an .env file with two environment variables:

# .env
MYSQL_PASSWORD=INSECURE_PASSWORD        # change these to
MYSQL_ROOT_PASSWORD=INSECURE_PASSWORD   # if you want to

4. start the compose project with docker compose up -d
5. wait for the database to initialise (you can check progress with docker compose logs -f).
6. install CiviCRM with docker compose exec -u www-data -e CIVICRM_ADMIN_USER=admin -e CIVICRM_ADMIN_PASS=password app civicrm-docker-install (note that we are passing in the admin username and password as environment variables here - you can change them if you want to).
7. visit http://localhost:8760 and log in using the credential supplied above.
8. when you are finished, bring the project down with docker compose down.

Environment variables

At a minimum, you should set the following environment variables:

• CIVICRM_DB_HOST
• CIVICRM_DB_PORT
• CIVICRM_DB_NAME
• CIVICRM_DB_USER
• CIVICRM_DB_PASSWORD
• CIVICRM_UF_BASEURL

Note that the CIVICRM_DB_* variables can be replaced with a single CIVICRM_DSN variable.

Experimental: you can override the default apache port (in the container) by setting APACHE_PORT.

Installation

The civicrm/civicrm image comes with a convenience script for installing a site: civicrm-docker-install. The script expects database credentials and the admin username (CIVICRM_ADMIN_USER) and password (CIVICRM_ADMIN_PASS) to be set as environment variables.

It calls the standard CiviCRM installation process. See build/civicrm/civicrm-docker-install for more details and the docker compose instructions above for an example of how you might call this script.

See also https://docs.civicrm.org/installation/en/latest/standalone/ for more details on the CiviCRM Standalone installation.

Volumes

The /var/www/html/public, /var/www/html/private and /var/www/html/ext directories should be persisted. See the example/civicrm/compose.yaml file for an example.

Tags

You can use tags to specify a CiviCRM version and php version, for example:

civicrm/civicrm:6.0-php8.3

CiviCRM version

Unless you specify a specific version you will always get the latest stable release of CiviCRM. This is the default and recommended option.

You can pin to a specific major release of CiviCRM by using the appropriate tag e.g. 6 pins to the latest release of CiviCRM 6.x.x. This will receive all minor and patch releases for this major release.

Similarly you can pin to a specific minor release of CiviCRM. For example, 6.0 will receive all patch releases for the 6.0 minor version. Please note that images are only built for the latest version of CiviCRM, so if you pin to a minor version of CiviCRM you will not receive any updates when the next minor version is released. This means that packages in the image (e.g. PHP and Apache) will no longer receive updates. For this reason pinning to a minor version is not recommended.

CiviCRM ESR is not currently supported but please get in touch if you'd be interested in adding this.

PHP version

Images are published for all supported versions of PHP. Specify a php version with a tag like php8.3.

Skip the tag to default to the the most recent version recommended by CiviCRM.

Building images

If you have specific needs that are not catered for by the pre-built images that are published on Docker Hub, you may want to build an image locally using the Dockerfiles in the build directory.

The build/civicrm directory

The build/civicrm Dockerfile is suitable for the most straight forward deployments. You must pass one of either CIVICRM_VERSION or CIVICRM_DOWNLOAD_URL and the PHP_VERSION as build arguments:

• CIVICRM_VERSION specifies a (stable) CiviCRM version
• CIVICRM_DOWNLOAD_URL specifies the tarball to download. Useful to build release candidates and nightly releases. This argument overrides CIVICRM_VERSION.
• PHP_VERSION specifies the PHP version. Useful if you want to build using a PHP version that we are not building images for.

For example:

Build an image using CiviCRM 6.0 and PHP version 8.3:

docker build build/civicrm --build-arg CIVICRM_VERSION=6.0 --build-arg PHP_VERSION=8.3 -t my-custom-build

Build an image with the latest nightly version of CiviCRM:

docker build build/civicrm --build-arg CIVICRM_DOWNLOAD_URL=https://download.civicrm.org/latest/civicrm-NIGHTLY-standalone.tar.gz --build-arg PHP_VERSION=8.3 -t my-civi/civicrm

Build an image with the latest nightly version of CiviCRM and a specific release of PHP. In this case, we'll need to build the intermediary images.

The build.php can help with this:

./build.php --php-version=8.3 --image-prefix=my-civi --skip-push

If you run docker image ls "my-civi/*" after this, you will see something like this:

REPOSITORY             TAG            IMAGE ID       CREATED           SIZE
my-civi/civicrm        6              91d9a3048d81   1 minutes ago     694MB
my-civi/civicrm        6-php8.3       91d9a3048d81   1 minutes ago     694MB
my-civi/civicrm        6.0            91d9a3048d81   1 minutes ago     694MB
my-civi/civicrm        6.0-php8.3     91d9a3048d81   1 minutes ago     694MB
my-civi/civicrm        6.0.3          91d9a3048d81   1 minutes ago     694MB
my-civi/civicrm        6.0.3-php8.3   91d9a3048d81   1 minutes ago     694MB
my-civi/civicrm        latest         91d9a3048d81   1 minutes ago     694MB
my-civi/civicrm        php8.3         91d9a3048d81   1 minutes ago     694MB
my-civi/civicrm-base   latest         29f972ae8200   3 minutes ago     561MB
my-civi/civicrm-base   php8.3         29f972ae8200   3 minutes ago     561MB
my-civi/common-base    latest         29f972ae8200   7 minutes ago     561MB
my-civi/common-base    php8.3         29f972ae8200   7 minutes ago     561MB

Custom builds

If you have a custom build process, for example if you have a special way to download CiviCRM, or want to install CiviCRM extensions in the image, consider using civicrm/civicrm-base as your base image.

For example:

FROM civicrm/civicrm-standalone-base:php8.3

RUN curl https://whizzy.com/download/whizzy.tar.gz && \
  tar -xf whizzy.tar.gz

Image architecture

flowchart BT
    C[civicrm]
    B[civicrm-base] --> C
    A[common-base] --> B
    E[wordpress]
    D[wordpress-base] --> E
    A --> D

Loading

Management

The ./build.php script can be used to build images.

Calling ./build.php without any arguments will build the latest stable version of CiviCRM and push it to docker hub.

If you are publishing official images on Docker Hub, make sure to run it in an environment that can publish multiplatform images, and can push to the CiviCRM docker account.

Command options are as follows:

• --image-prefix= - a custom prefix for generated images (defaults to civicrm)
• --image-filter= - only build the specified images (comma seperated list)
• --php-version= - build only the specified php versions (comma seperated list, defaults to all supported versions)
• --civicrm-version= - build a specific CiviCRM version (defaults to the latest stable release)
• --download-url= - a specific tarball to download
• --download-prefix= - replaces the https://download.civicrm.org/ part of each image's download URL, keeping the civicrm-<version>-<flavour> filename. Unlike --download-url this gives each image the right archive, so a whole image set can be built from an alternative source in one run
• --builder= - the docker build builder to use
• --platform= - the platforms to build for
• --skip-push - build the images but do not push them to Docker Hub
• --no-cache - do not use a cache when building the images
• --dry-run - just output the commands that would be executed
• --step - run one step at a time

Note: before running ./build.php, you will need to install the required dependencies with composer install (see https://getcomposer.org/ for more details).

No warranty: running it is up to you

This setup comes without any warranty, and we accept no liability for its use. You run it at your own risk.

Keeping it up to date is your job. Nothing updates itself: CiviCRM security releases reach your server only when you upgrade it. Follow CiviCRM's security announcements to know when one is due. The server's operating system, Docker, MariaDB and the firewall are yours to maintain as well.

It is also deliberately basic: there is no backup, restore or monitoring. For more complex needs, work with an experienced hosting partner who takes care of all of this for you.