Skip to content

Home > Developer Guide > Tools > civibuild

civibuild: Settings

Settings are stored persistently and re-used over time. They fall in two big buckets.

Build settings

The Build settings are used everytime you create a new build. (Once the build is created, the values are baked-in.) Some values that you might typically customize include:

  • The default HTTP URL for new builds.
  • The default username/password for the administrator on new builds.

In general, these are based on environment-variables. However, the details depend on how you installed Buildkit. Each installation-type prefers a different configuration-file.

Installation Type Key Files
Buildkit: Nix .loco/loco.yml
.loco/config/buildkit/civibuild.conf
Buildkit: Virtual Desktop .loco/loco.yml
.loco/config/buildkit/civibuild.conf
Buildkit: Docker civicrm/civibuild.conf
Buildkit: Generic app/civibuild.conf.tmpl
app/civibuild.conf

If you review these files, you should find several docblocks and examples.

Runtime settings

The Runtime settings are used on every page-load. They have immedate effect. Some values that you might typically customize include:

  • Debug and backtrace
  • Email routes

civicrm.settings.d folders

Civibuild provides a mechanism to quickly add settings to all sites which you've built with civibuild.

For example, you can create a file /etc/civicrm.settings.d/300-debug.php with the following content to enable debugging and backtraces for all civibuild sites (useful for local development).

<?php
$GLOBALS['civicrm_setting']['domain']['debug_enabled'] = 1;
$GLOBALS['civicrm_setting']['domain']['backtrace'] = 1;

Any settings which you would typically put in your site's civicrm.settings.php file can go into a php file (you choose the file name) in a civicrm.settings.d folder.

Civibuild will check the following civicrm.settings.d folders.

Folder Purpose
$PRJDIR/app/civicrm.settings.d/ General defaults provided by upstream buildkit for all civibuild sites
$PRJDIR/app/config/$TYPE/civicrm.settings.d/ General defaults provided by upstream buildkit for specific types of sites
/etc/civicrm.settings.d/ Overrides provided by the sysadmin for the local server
$SITE_DIR/civicrm.settings.d/ Overrides provided for a specific site/build

!!! note "Load order"

For concrete example, suppose we have these files:

 * `$PRJDIR/app/civicrm.settings.d/200-two.php`
 * `$PRJDIR/app/civicrm.settings.d/300-three.php`
 * `/etc/civicrm.settings.d/100-one.php`
 * `/etc/civicrm.settings.d/300-three.php`

Then we would execute/load in this order:

 * `100-one.php` (specifically `/etc/civicrm.settings.d/100-one.php`; this is the only version of `100-one.php`)
 * `200-two.php` (specifically `$PRJDIR/app/civicrm.settings.d/200-two.php`; this is the only version of `200-two.php`)
 * `300-three.php` (specifically `/etc/civicrm.settings.d/300-three.php`; the system configuration in `/etc` overrides the stock code in `$PRJDIR/app/civicrm.settings.d`)

The $PRJDIR/app/civicrm.settings.d/ also contains some example configuration files. For more advanced logic, one can look at the global $civibuild variable or at any of the standard CiviCRM configuration directives.

settings.php; wp-config.php

Each CMS includes a settings file that is analogous to civicrm.settings.php. These follow a parallel structure -- which means that you can put extra config files in: