civibuild: Options¶

The civibuild create command accepts several options for configuring. You can find some documentation about these options with the built-in help screen.

civibuild create --help

For this page, we dive into the most important options.

Build Name¶

Every build has a short, symbolic name. Note how the name appears in the file-paths, URLs, and database credentials.

civibuild create NAME

[[Show site summary (NAME/default)]]
 - CMS_ROOT: /Users/myuser/buildkit/build/NAME/web
 - CMS_URL: http://NAME.my-domain.org
 - CMS_DB_DSN: mysql://NAMEcms_17djk:XXXXXXXXXXXX@127.0.0.1:3307/NAMEcms_68tee?new_link=true

Any short alphanumeric expression can be used as a name. However, there are some conventions -- it is common to choose a NAME which matches a well-known alias or build-type.

Build Alias¶

An alias is a special name. It provides a short-hand for a longer civibuild command.

For example, the alias d10-master implies --type drupal10-demo and --civi-ver master. Therefore, these two commands are equivalent:

## Short command. Use an alias.
civibuild create d10-master

## Long command. Set options explicitly
civibuild create d10-master --type drupal10-demo --civi-ver master

Here are a few common aliases:

Description	Command
Standalone CiviCRM with master branch	`civibuild create master`
Standalone CiviCRM with current release-candidate	`civibuild create rc`
Standalone CiviCRM with current stable branch	`civibuild create stable`
Standalone CiviCRM with last public ESR variant	`civibuild create esr`
Backdrop CMS with CiviCRM master branch	`civibuild create bmaster`
Drupal 10.x with CiviCRM master branch	`civibuild create d10-master`
Drupal 9.x with CiviCRM master branch	`civibuild create d9-master`
Drupal 7.x with CiviCRM master branch	`civibuild create d7-master`
WordPress with CiviCRM master branch	`civibuild create wpmaster`

For a full list of aliases, see civibuild.aliases.sh.

Build Type¶

The build-type determines how to dowload files, where to place them, and how to perform installation.

For example, consider the build-type drupal10-clean. This downloads and installs Drupal 10.x and CiviCRM. As is customary for Drupal 10.x, it will use composer to download all modules and libraries. Perform installation with drush CLI.

Most build-types have two words:

The first word indicates the application-framework/CMS, such as:
- drupal10-* (CiviCRM with Drupal 10)
- wp-* (CiviCRM with WordPress)
- standalone-* (CiviCRM Standalone, with no CMS)
The second word indicates a general theme, such as:
- *-clean (a basic "out-of-the-box" configuration of CiviCRM)
- *-demo (a more opinionated configuration with extra extensions and settings)
- *-empty (a barebones configuration without CiviCRM)

Here are some more common build-types:

Framework/CMS	Build Types
Backdrop	🟢 `backdrop-clean` 🟢 `backdrop-demo` 🟡 `backdrop-empty`
Drupal 10	🟣 `drupal10-clean` 🟣 `drupal10-demo` 🟣 `drupal10-dev` 🟣 `drupal10-dod` 🟡 `drupal10-empty`
Drupal 9	🟣 `drupal9-clean` 🟣 `drupal9-demo` 🟣 `drupal9-dev` 🟡 `drupal9-empty`
Drupal 7	🟢 `drupal-clean` 🟢 `drupal-demo` 🟡 `drupal-empty`
Joomla 5	🟡 `joomla5-empty`
Joomla 4	🟡 `joomla-empty`
Standalone	🟢 `standalone-clean` 🟣 `standalone-composer`
WordPress	🟢 `wp-clean` 🟢 `wp-demo` 🟡 `wp-empty`
Special	🟡 `dist`: A website containing nightly builds akin to dist.civicrm.org. Useful for preparing CiviCRM tarballs. 🟡 `distmgr`: A service which manages redirects and report-backs for the download site. 🟡 `messages`: A backend service for delivering in-app messages (eg "Getting Started"). 🟡 `universe`: A broad collection of publicly visible repos, extensions, infrastructure, etc.

(🟢=CiviCRM via git clone. 🟣=CiviCRM via composer require. 🟡=No CiviCRM)

For a full list of current build-types, see app/config/.

To create a new build type, see Custom Build Types.

CiviCRM Version¶

Use the --civi-ver parameter to install a specific version. The following are valid versions:

Any git branch on civicrm-core.git (such as master or 6.4)
Any git tag on civicrm-core.git (such as 6.3.0 or 5.81.2)
Any of the following reserved words:
- stable (the current stable release branch, at time of creation)
- rc (the current release-candidate, at time of creation)
- esr (the latest public iteration of the ESR branch, at time of creation)

HTTP URL¶

Each CiviCRM instance needs a base URL.

In "Full Stack" solutions (such as nix, Docker, or Virtual Desktop), the URL is pre-configured. These solutions expect HTTPD to listen on 127.0.0.1 -- beyond that, they need no configuration.

In other cases, you should set the URL manually. Common scenarios would be:

Running buildkit on a virtual machine (with a private IP like 192.168.1.2)
Running buildkit on a remote server (with a public IP)
Using a generic ("half-stack") installation

To set the URL as a CLI option, pass --url:

civibuild create example --url 'http://example.localhost'
civibuild create example --url 'http://example.local.civi.bid:8001'
civibuild create example --url 'http://example.192-168-1-2.civi.bid:8001'

Be sure to choose a URL that will work with your DNS and HTTP settings. (Otherwise, you may need to update DNS and HTTP manually.)

Tip: Manually entering the --url may become tiresome. To update the default URL, see civibuild: Settings.

Patches¶

When creating a build, you can apply one (or more) pull-requests using the --patch option. For example:

(1) This will setup CiviCRM standalone (master branch) with one patch for civicrm-core:

civibuild create master --patch https://github.com/civicrm/civicrm-core/pull/1234

(2) This will setup WordPress with CiviCRM 6.4 and two patches:

civibuild create example \
  --type wp-clean \
  --civi-ver 6.4 \
  --patch 'https://github.com/civicrm/civicrm-core/pull/1234' \
  --patch 'https://github.com/civicrm/civicrm-packages/pull/5678'

The --patch option supports the primary CiviCRM git projects (civicrm-core, civicrm-packages, civicrm-backdrop, civicrm-drupal, civicrm-drupal-8, and civicrm-wordpress).