Skip to content

Nix

Home > Developer Guide > Buildkit nix is a cross-platform package-manager. nix runs on top of most Linux distributions (Debian, Ubuntu, Redhat, etc) as well as MacOS. Nix packages are stored in a separate folder (/nix), and you can safely run multiple versions of any package.

nix is used by the CI test-infrastructure for civicrm-core.

??? info "Major features"

These instructions will install the following packages in `/nix`:

* __Interpreters__: PHP-CLI, NodeJS
* __Servers__: Apache HTTPD, MySQL, PHP-FPM, MailHog, Redis <!-- Memcached is installed but disabled by default -->

Additionally, they will install buildkit in `$HOME/buildkit`.

??? info "Trade-offs"

* __Pro__: `nix` runs locally at native speed on Linux+MacOS with x86+arm64. Configuration is packaged, editable, and disposable. Can be combined with desktop tools (IDEs/debuggers). Packages don't interfere with host. Closely matches official test environment.
* __Con__: No Windows support (except through WSL/virutalization). Customization requires learning new language. Major host OS updates sometimes have compatibility issues (but usually fixable).

Requirements

  • Linux or MacOS (Note: Generally, you'll get the best results with an OS release that is 3-24 months old -- something recent but not brand new.)
  • x86 or arm64
  • git
  • Sudo privileges

Profiles

A profile defines a list of pre-selected packages (such as PHP, MySQL, and gzip). Buildkit includes several profiles.

For this tutorial, we'll use the "default" (dfl) profile which includes a middle-of-the-road configuration.

??? info "Choosing an alternative profile..."

All buildkit profiles include common utilities (such as `tar`, `gzip`, `redis`, and `mailcatcher`).

The _distinctive_ feature of each profile is how it addresses PHP and MySQL. Let's compare some examples:

| Profile | Description |
| -- | -- |
| `php84m80`  | (__Specifically__) PHP 8.4 and MySQL 8.0
| `php83m57`  | (__Specifically__) PHP 8.3 and MySQL 5.7
| `php82r106` | (__Specifically__) PHP 8.2 and MariaDB 10.6
| `php84`     | PHP 8.4. (*Also: MySQL 8.0, but this may change every few years.*)
| `php83`     | PHP 8.3. (*Also: MySQL 8.0, but this may change every few years.*)
| `php82`     | PHP 8.2. (*Also: MySQL 8.0, but this may change every few years.*)
| `dfl`       | (__Floating__) _Default_ suggestions. Mid-range versions of PHP/MySQL.
| `min`       | (__Floating__) _Minimal_ versions of PHP and MySQL.
| `max`       | (__Floating__) _Maximal_ versions of PHP and MySQL.
| `old`       | (__Floating__) _Old, unsupported_ versions of PHP and MySQL.
| `edge`      | (__Floating__) _New, unsupported_ versions of PHP and MySQL.

Note how some profiles are set to specific versions (as in `php84m80`), while other profiles change over
time (as in `min` or `max`).

When using specific versions, there are many possible permutations. In general, you can combine these parts:

* PHP Version: `php73`, `php74`, `php80`, `php81`, `php82`, `php83`, `php84`
* DBMS Version (MySQL): `m57`, `m80`, `m84`, `m90`
* DBMS Version (MariaDB): `r106`, `r1011`

In the following steps, we will download and startup `dfl`. However, you can switch to any of these other profiles.

Download

## Download the configuration
git clone https://github.com/civicrm/civicrm-buildkit ~/buildkit

## Download and install the binaries
cd ~/buildkit
PROFILES=dfl ./nix/bin/install-developer.sh

!!! info "The "install-developer.sh" script will download a few gigabytes worth of data.
It may compile some packages from source."

For further discussion about these commands and their variations, see nix/doc/install-developer.md.

Startup

## Open a subshell
use-bknix dfl -s

## Start the services - HTTPD, MySQL, etc
cd ~/buildkit
loco run

!!! info "The "loco run" command will start HTTPD, MySQL, etc on alternative ports.
This allows them to coexist with any other services you have."

For further discussion about these commands and their variations, see nix/doc/usage-loco.md.

Next steps

Finally, once you are able to work with use-bknix and loco, you can move on to using civibuild within the subshell.