Configuration User Guide: Advanced Configuration

Phabricator User Documentation (Configuration)

Configuring Phabricator for multiple environments.

Overview

Phabricator reads configuration from multiple sources. This document explains the configuration stack and how to set up advanced configuration sources, which may be useful for deployments with multiple environments (e.g., development and production).

This is a complicated topic for advanced users. You do not need to understand this topic to install Phabricator.

Configuration Sources

Phabricator supports the following configuration sources, from highest priority to lowest priority:

• Database: Values are stored in the database and edited from the web UI by administrators. They have the highest priority and override other settings.
• Local: Values are stored in conf/local/local.json and edited by running bin/config.
• Config Files: Values are stored in a config file in conf/. The file to use is selected by writing to conf/local/ENVIRONMENT, or setting the PHABRICATOR_ENV configuration variable. See below for more information.
• Defaults: Defaults hard-coded in the Phabricator source, which can not be edited. They have the lowest priority, and all other settings override them.

Normally, you install and configure Phabricator by writing enough configuration into the local config to get access to the database configuration (e.g., the MySQL username, password, and hostname), then use the web interface to further configure Phabricator.

Configuration Files

Configuration files provide an alternative to database configuration, and may be appropriate if you want to deploy in multiple environments or create dynamic configuration. Configuration files are more complicated than database configuration, which is why they are not used by default.

Creating a Configuration File

To create a configuration file, first choose a name for the config (like "devserver" or "live"). For the purposes of this section, we'll assume you chose exampleconfig. Replace "exampleconfig" with whatever you actually chose in the examples below.

First, write an exampleconfig.conf.php file here (rename it according to the name you chose):

phabricator/conf/custom/exampleconfig.conf.php

Its contents should look like this:

<?php

return array(
  // Specify whichever keys and values you want to set.
  'example.key' => 'examplevalue',
);

For example, to specify MySQL credentials in your config file, you might create a config like this:

<?php

return array(
  'mysql.host' => 'localhost',
  'mysql.user' => 'root',
  'mysql.pass' => 'hunter2trustno1',
);

Selecting a Configuration File

To select a configuration file, write the name of the file (relative to phabricator/conf/) to phabricator/conf/local/ENVIRONMENT. For example, to select phabricator/conf/custom/exampleconfig.conf.php, you would write "custom/exampleconfig" to phabricator/conf/local/ENVIRONMENT:

phabricator/ $ echo custom/exampleconfig > conf/local/ENVIRONMENT
phabricator/ $ cat conf/local/ENVIRONMENT
custom/exampleconfig
phabricator/ $

You can also set the environmental variable PHABRICATOR_ENV. This is more involved but may be easier in some deployment environments. Note that this needs to be set in your webserver environment, and also in your shell whenever you run a script:

# Shell
export PHABRICATOR_ENV=custom/exampleconfig

# Apache
SetEnv PHABRICATOR_ENV custom/exampleconfig

# nginx
fastcgi_param PHABRICATOR_ENV "custom/exampleconfig";

# lighttpd
setenv.add-environment = (
   "PHABRICATOR_ENV" => "custom/exampleconfig",
)

After creating and selecting a configuration file, restart Phabricator (for help, see Restarting Phabricator). Any configuration you set should take effect immediately, and your file should be visible in the Config application when examining configuration.

Next Steps

Return to the Configuration Guide.