Generic

In the Generic approach, you install buildkit on top of an existing Unix-style environment.

Trade-offs

Pro: The Generic approach is compatible with many different environments, styles, and versions. You may freely tune your environment and process without concern for how it affects other developers.
Con: The Generic approach requires configuring several subsystems (bash, amp, mysql, etc). You need to understand each subsystem, track requirements, manage updates. Your environment may not match other developers' environments.

Requirements¶

The system must already meet the basic requirements for PHP, MySQL, etc.

Apache HTTPD is very strongly recommended. Why?
Apache HTTPD is not strictly required. Many tools in buildkit work with any web-server (or no web server!).

However, one major tool (civibuild) works better with Apache. civibuild facilitates testing across different PHP CMS's (D7, D8, D9, WordPress, Backdrop, etc). Every CMS includes built-in Apache support (via .htaccess).

It is theoretically possible to run civibuild and then serve sites with a different HTTPD. Or you could skip civibuild completely. However, in either case, you would have to maintain the HTTPD configuration yourself.

Apache is the only option with automatic, canonical support in all CMS's.
Additionally, the configuration process requires sysadmin skills. You will be asked to configure several components and adapt them to match the local environment.

If you are not comfortable with sysadmin tasks, then consider using a Virtual Desktop instead.

Download¶

Clone the civicrm-buildkit.git repo and run civi-download-tools:

$ git clone https://github.com/civicrm/civicrm-buildkit.git ~/buildkit
$ cd ~/buildkit
$ ./bin/civi-download-tools

In the above example, all tools are downloaded under ~/buildkit.

Requirements checking

civi-download-tools will attempt to identify and report common issues (such as missing/unknown commands).

If it reports a problem, you should resolve that problem and retry.

Depending on the specific problem and its resolution, you may find it necessary to close and reopen the terminal.

Configure PATH¶

Buildkit includes many CLI commands in the bin/ folder.

You may execute the commands directly (e.g. ./bin/civix or /path/to/buildkit/bin/civix). However, this would become very cumbersome. Instead, you should configure the shell's PATH to recognize these commands automatically.

Tip

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 ~/.bash_profile, or ~/.profile. You may have to create one.
At the end of the file, add PATH="/path/to/buildkit/bin:$PATH".
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 ~/.profile with source ~/.profile.
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.

Tip

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 $PATH

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 ~/.bashrc.

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.

References:

Note

Buildkit includes specific versions of some fairly popular tools (such as drush, phpunit, and 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 PATH.

Whenever you wish to use buildkit, manually run a command like, e.g.:

export PATH=/path/to/buildkit/bin:$PATH

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 export command.

Configure `amp`¶

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
```
tips
- Run this as a non-root user who has sudo permission. This will ensure that new files are owned by a regular user, and (if necessary) it enables civibuild to restart your webserver and edit /etc/hosts.
- Pay close attention to any instructions given in the output of this command.
- To check which version of apache you have, run apachectl -v.
Caution

We strongly recommend using Apache as your webserver because support for nginx is limited.
Test amp's configuration
```
$ amp test
```
The test is successful if you see Received expected response at 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.

Next steps¶

After configuring the PATH and amp, you can move on to using civibuild.

Appendix: Troubleshoot¶

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

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.

Appendix: Upgrade buildkit¶

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 civi-download-tools.

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.

When upgrading civix, check upgrade instructions.

If you see an upgrade to civix in the changelog, and if you maintain extensions with civix, then check the general civix upgrade documentation and UPGRADE.md.