Many of these tools are commonly used by web developers, so you may have already installed a few. Even so, it's generally easier to install the full collection — installing each individually takes a lot of work.
This is the same collection of tools which manages the test/demo/release infrastructure for civicrm.org.
If you have a new installation of Ubuntu 12.04 or later, then you can download everything -- buildkit and the system requirements -- with one command. This command will install buildkit to
curl -Ls https://civicrm.org/get-buildkit.sh | bash -s -- --full --dir ~/buildkit
- When executing the above command, you should not run as
root, as it will cause failures. However, you should have
--fulloption is very opinionated; it specifically installs
percona). If you try to mix
--fullwith alternative systems, then expect conflicts.
- If you use the Ubuntu feature for "encrypted home directories", then don't put buildkit in
/srv/buildkit, or some other location that remains available during reboot.
After running the above command, then proceed to the post-installation configuration.
Full Download: Vagrantbox - Download a prepared virtual-machine with all system dependencies (mysql, etc). This is ideal if you work on Windows or OS X.
If you have Docker running, you can use one of the following projects to run buildkit within a Docker container:
There different version of Buildkit on Docker. Michael McAndrew's seems to be the easiest to get started with on Linux. There is an outstanding issue that needs to be resolved before getting set up on a Mac is as straight forward.
Install buildkit on docker on ubuntu¶
Follow the official installation instructions from https://docs.docker.com/compose/install/ to install docker compose on your linux machine.
git clone https://github.com/michaelmcandrew/civicrm-buildkit-docker.git cd civicrm-buildkit-docker sudo docker-compose up -d
Now you are ready to go.
To create a new site with buildkit run the following command:
docker-compose exec -u buildkit civicrm civibuild create dmaster --url http://localhost:8080
Alternative you can login into the conatiner and run the commands from there:
docker-compose exec -u buildkit civicrm bash
More information is in the Readme: https://github.com/michaelmcandrew/civicrm-buildkit-docker/blob/master/README.md
You may install buildkit in other environments. The main pre-requisites are:
- Linux or OS X
- PHP 5.3+ (Extensions:
bcmath curl gd gettext imap intl imagick json mbstring mcrypt openssl pdo_mysql phar posix soap zip)
- NodeJS (v5 recommended)
- Recommended (for amp and civibuild)
- Apache 2.2 or 2.4 (Modules:
mod_rewrite. On SUSE, possibly
mod_access_compat. This list may not be exhaustive.)
- MySQL 5.1+ (client and server)
- Apache 2.2 or 2.4 (Modules:
All pre-requisites must support command-line access using the standard command names (
mysqldump, etc). In some environments, you may need to enable these commands by configuring
PATH -- this is especially true for MAMP, XAMPP, and other downloaded packages. (See, e.g., Setup Command-Line PHP.)
Once the pre-requisites are met, download buildkit to
$ git clone https://github.com/civicrm/civicrm-buildkit.git ~/buildkit $ cd ~/buildkit $ ./bin/civi-download-tools
Configuring your path¶
Not needed for Vagrant/Docker installations
If you set up buildkit using Vagrant or Docker, then you don't need to perform the configuration steps listed here.
Buildkit includes many CLI commands in the
You may execute the commands directly (e.g.
/path/to/buildkit/bin/civix). However, this would become very cumbersome. Instead, you should configure the shell's
PATH to recognize these commands automatically.
Throughout this document, we will provide examples which assume that buildkit was downloaded to
/path/to/buildkit. Be sure to adjust the examples to match your system.
If you want to ensure that the buildkit CLI tools are always available, then:
- Determine the location of your shell configuration file. This is usually
~/.profile. You may have to create one.
- At the end of the file, add
- If you are on a mac, you can close and re-open your terminal. On other systems, you will need to log-out or source your
- Enter the command
civibuild -h. This should display a help screen for civibuild. If you get 'command not found', then check your path and retry the steps above.
For most installations with the standard buildkit install script the following lines in your shell configuration file will work.
# Add ~/buildkit/bin to path if it exists. if [ -d "$HOME/buildkit/bin" ] ; then PATH="$HOME/buildkit/bin:$PATH" fi
More on bash
On most OS's
~/.profile is run only once when you login to your desktop. There is a distinction between "login shells" and "non-login shells" which you don't really need to worry about, except that the distinction is the reason that you should set your
$PATH in your
~/.profile and not your
When you open a terminal (non-login),
~/.bashrc will be executed. The common idiom for changing the path is to add to the
$PATH, not rebuild it, so if you update your
$PATH every time a shell is invoked, your
$PATH will continually grow. This is not really a problem, but you might want to be aware of this.
If you are on a mac, the situation is reversed. That is, your
$PATH is not set when you login into your desktop and every terminal you open is a "login shell" and
~/.profile will be executed every time.
You do not need to run
export PATH=... because your system certainly has already exported the
$PATH variable and you only need to update it.
Buildkit includes specific versions of some fairly popular tools (such as
wp-cli), and it's possible that you have already installed other versions of these tools.
By design, buildkit can coexist with other tools, but you must manually manage the
Whenever you wish to use buildkit, manually run a command like, e.g.:
To restore your normal
PATH, simply close the terminal and open a new one.
Each time you open a new terminal while working on Civi development, you would need to re-run the
Buildkit provides a tool called
amp which civibuild uses when it needs to set up a new site. Before you can use
civibuild, need to configure
amp by telling it a bit about your system (e.g. what webserver you're using).
Run the interactive configuration tool.
$ amp config
- Run this as a non-
rootuser who has
sudopermission. This will ensure that new files are owned by a regular user, and (if necessary) it enables
civibuildto restart your webserver and edit
- Pay close attention to any instructions given in the output of this command.
- To check which version of apache you have, run
We strongly recommend using Apache as your webserver because support for nginx is limited.
- Run this as a non-
Test amp's configuration
$ amp test
The test is successful if you see
Received expected responseat the end.
If the test produces any errors, you might try re-running the above config steps and/or asking for help in the developer chat room.
ampis configured, you can move on to running civibuild to build a local development installation of CiviCRM.
Node JS issues¶
- Nodejs version too old or npm update does not work:
Download the latest version from nodejs.org and follow their instructions
- Nodejs problems
It might be handy to run
npm update npm install fs-extra
Website login issues¶
If you find that when you try and login to a new buildkit build or similar and it doesn't seem to login just redirects to the same page. This may mean that the rewrite module for apache is not enabled. To enable it do the following
sudo a2enmod rewrite
After enabling the rewite module you will need to restart apache.
New versions of buildkit are likely to include new versions of tools. The new tools will download automatically when you first run
civibuild. If you prefer to download explicitly, then re-run
The configurations and tools in buildkit are periodically updated. To get the latest, simply run:
cd ~/buildkit git pull ./bin/civi-download-tools
See the buildkit changelog for info about specific changes to buildkit.