Skip to content

Nix

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.

Major features

These instructions will install the following packages in /nix:

  • Interpreters: PHP-CLI, NodeJS
  • Servers: Apache HTTPD, MySQL, PHP-FPM, MailHog, Redis

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

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.

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

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

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.