Skip to content

Buildkit

To develop for CiviCRM, you will need the basic requirements (PHP, MySQL, etc) and several specific development tools. This collection is called civicrm-buildkit. Buildkit has several installation options:

  • Full Stack: Install everything as one suite.
  • Half Stack: Install PHP+MySQL on your own. Add buildkit for additional tools.
  • Custom Stack: Choose and configure every component yourself.

Full Stack

A full stack deployment installs everything (PHP, MySQL, cv, civix, etc). This requires a framework for systems-development, such as nix, Docker, VirtualBox, or UTM.

  • Pro: You get a comprehensive suite. Everything is configured.

  • Con: Highly opinionated configurations. You need to find a full stack that comes close to your needs.

There are several full-stack options. They differ in performance, compatibility, and isolation.

Full Stack Option Host Compatibility
Buildkit-Docker: Run isolated Linux containers with a mounted data-folder. Linux: Native (x86†)
MacOS: Virtual (x86†)
Windows: Virtual (x86†)
Buildkit-Nix: Run isolated add-on packages with a local data-folder. Linux: Native (x86, arm64)
MacOS: Native (x86, arm64)
Windows: Virtual (x86††)
Buildkit-Virtual Desktop: Run a virtual machine with an entire desktop OS. Linux: Virtual (x86)
MacOS: Virtual (x86, arm64)
Windows: Virtual (x86)

†: Docker platform supports x86 and arm64. However, Buildkit-Docker is only developed on x86.
††: Nix can be installed on WSL2. However, WSL2 uses a virtual-network, which requires extra configuration.

For a new or inexperienced contributor, Virtual Desktop is the safe bet. It provides broad functionality, broad compatibility, and strong isolation... with very little effort. However, it is slow and heavy. (More info...)

For best performance, look at Nix. It runs locally on MacOS and Linux, which maximizes performance and simplifies debugging. However, it is not fully isolated, and modifying the stack may require an obscure language. (More info...)

For a system that feels more familiar to sysadmins, look at Docker. It provides good isolation and good performance on Linux-x86. However, the virtual-networking will complicate efforts at debugging, and performance suffers on macOS. (More info...)

Half Stack

With a half stack, you install one half (PHP+MySQL) of the stack. For the second half, you can add buildkit on top.

  • Pro: You can choose how to address basic requirements, but you don't need to manage every tool. More flexible.

  • Con: Initial configuration is difficult. Requires Unix-style host. Somewhat opinionated.

This may be appropriate if...

  1. The basic requirements are already provided by your operating system (Debian, Ubuntu, Fedora, RHEL, etc) or add-on stack (MAMP, XAMPP, brew, etc), and...
  2. You are willing to defer to buildkit on many decisions (such as software versions and HTTPD-type).

To learn more, consult the generic installation guide for buildkit.

Custom Stack

With a custom stack, you install all the tools on your own.

  • Pro: Maximum flexibility. Works on all platforms.

  • Con: You will need to understand, configure, and maintain all tools. Your toolset may get out-of-sync with other developers' toolset.

If the Full Stack and Half Stack options are not a good fit, then you may prefer to maintain a custom stack. Some common cases would be:

  • You are developing on Windows. Building a custom stack will provide the most native experience.
  • You are developing for an enterprise with its own standards and practices.
  • You already have a custom stack for PHP. Adding a few more tools is easier than reworking your entire system.

There is no specific guide for custom stacks. However, you should review civicrm-buildkit to understand the kinds of tools and configurations that are typically required.