civibuild.md

civibuild

Creating a full development environment for CiviCRM requires a lot of work, e.g.,

• Downloading / installing / configuring a CMS (Backdrop, Drupal, Joomla, WordPress).
• Downloading / installing / configuring CiviCRM.
• Configuring Apache and MySQL.
• Configuring file permissions on data folders.
• Configuring a headless test database for phpunit.
• Configuring Selenium to connect to Civi.

The civibuild command automates this process. It includes different build-types that are useful for core development, such as drupal-clean (a barebones Drupal+Civi site) and wp-demo (a WordPress+Civi site with some example content).

Note: There are a number of build tools on the market which can, e.g., create a Drupal web site (like drush) or WordPress web site (like wp-cli). Civibuild does not aim to replace these. Unfortunately, such tools generally require extra work for a Civi developer environment. Civibuild works with these tools and and fills in missing parts.

Build Types

civibuild includes a small library of build scripts for different configurations.

For a list of available build-types as well as documentation on writing build scripts, see app/config within your buildkit installation.

For example, at time of writing, it includes:

• backdrop-clean: A bare, "out-of-the-box" installation of Backdrop+CiviCRM.
• backdrop-demo: A demo site running Backdrop and CiviCRM.
• backdrop-empty: An empty Backdrop site (without CiviCRM). Useful for testing tarball installation.
• drupal8-clean: A bare, "Out of the box" Installation of Drupal8+CiviCRM.
• drupal8-demo : A demo site running Drupal8 and CiviCRM.
• drupal-clean: A bare, "out-of-the-box" installation of Drupal+CiviCRM.
• drupal-demo: A demo site running Drupal and CiviCRM.
• drupal-empty: An empty Drupal site (without CiviCRM). Useful for testing tarball installation.
• joomla-empty: An empty Joomla site (without CiviCRM). Useful for testing tarball installation.
• wp-demo: A demo site running WordPress and CiviCRM.
• wp-empty: An empty WordPress site (without CiviCRM). Useful for testing tarball installation.
• hrdemo A demo site running Drupal, CiviCRM, and CiviHR.
• symfony: An experimental hybrid site running Drupal 7, Symfony 2, and CiviCRM.
• cxnapp: A self-signed CiviConnect app based on the reference implementation.
• messages: A backend service for delivering in-app messages (eg "Getting Started").
• extdir: A mock website akin to civicrm.org/extdir/ . Useful for testing the extension download process.
• 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.
• universe: A broad collection of publicly visible repos, extensions, infrastructure, etc.
• l10n: WIP - A build environment for creating translation files.
• joomla-demo: WIP/incomplete/broken.

Build types can be mixed/matched with different versions of Civi, e.g.,

$ civibuild create my-drupal-civi47 \
  --type drupal-demo \
  --civi-ver master \
  --url http://my-drupal-civi47.localhost
$ civibuild create my-drupal-civi46 \
  --type drupal-demo \
  --civi-ver 4.6 \
  --url http://my-drupal-civi46.localhost
$ civibuild create my-wordpress-civi4719 \
  --type wp-demo \
  --civi-ver 4.7.19 \
  --cms-ver 4.0 \
  --url http://my-wp-civi4719.localhost

The --civi-ver argument will accept any branch or version tag. Note: the 4.7 version is in the master branch..

You can also specify --patch with a pull request URL to apply those changes on top of your CiviCRM version.

Build Aliases

For developers who work with several CMSs and several versions of Civi, it's useful to have a naming convention and shorthand for the most common configurations. Civibuild includes aliases (in src/civibuild.aliases.sh) like "d44" and "wpmaster":

Create a build "d44" using build-type "drupal-demo" with Civi "4.4":

$ civibuild create d44 --url http://d44.localhost

Create a build "d45" using build-type "drupal-demo" with Civi "4.5":

$ civibuild create d45 --url http://d45.localhost

Create a build "wp45" using build-type "wp-demo" with Civi "4.5":

$ civibuild create wp45 --url http://wp45.localhost

Create a build "wpmaster" using build-type "wp-demo" with Civi's "master" branch:

$ civibuild create wpmaster --url http://wpmaster.localhost

These aliases exactly match the demo sites deployed under civicrm.org (e.g. "wp45" produces the demo site "wp45.demo.civicrm.org").

Upgrading a site you installed with civibuild {:#upgrade-site}

If you have a working civibuild site and you'd like to upgrade CiviCRM to the latest version, follow these steps:

Begin in the civicrm directory within your site {:#upgrade-site-begin}

cd ~/buildkit/build/dmaster/sites/all/modules/civicrm/

!!! note The path to this directory will vary depending on where you installed buildkit and what CMS your site uses.

Check the status of all git repos {:#upgrade-site-git-scan}

There are multiple git repos in your build (civicrm-core.git, civicrm-packages.git, etal). Before making a major switch, first double-check that all of these repos are in sane condition — i.e. there shouldn't be any uncommitted changes, and the repos should be on normal branches. For this purpose, use git-scan (installed with buildkit).

git scan status

!!! fail "Check for errors" If you see a message like "Fast-forwards are not possible" or "Modifications have not been committed", then you'll need to clean up these git repositories before proceeding.

Update the git repos {:#upgrade-site-git-scan-up}

To update to the latest version of a particular branch, use git scan up which will perform a standard "fast-forward merge" (git pull --ff-only) across all the repos:

git scan up

!!! tip If you didn't cleanup earlier, then "fast-forward" may not be possible. It takes some judgment to decide what to do — e.g. a "merge" versus "rebase". Rather than risk a wrong decision, git scan will skip these repos and display warnings instead.)

Alternatively, if you'd like to hop to a specific tag, you can use givi (a tool included with buildkit), but keep in mind that if you hop to a previous tag with code that expects a different database scheme, there will be no way to run database downgrades.

givi checkout 4.7.17