[Summary view] [Print] [Text view]

   1  @title Configuration User Guide: Advanced Configuration
   2  @group config
   3  
   4  Configuring Phabricator for multiple environments.
   5  
   6  = Overview =
   7  
   8  Phabricator reads configuration from multiple sources. This document explains
   9  the configuration stack and how to set up advanced configuration sources, which
  10  may be useful for deployments with multiple environments (e.g., development and
  11  production).
  12  
  13  This is a complicated topic for advanced users. You do not need to understand
  14  this topic to install Phabricator.
  15  
  16  = Configuration Sources =
  17  
  18  Phabricator supports the following configuration sources, from highest priority
  19  to lowest priority:
  20  
  21    - **Database**: Values are stored in the database and edited from the web UI
  22      by administrators. They have the highest priority and override other
  23      settings.
  24    - **Local**: Values are stored in `conf/local/config.json` and edited by
  25      running `bin/config`.
  26    - **Config Files**: Values are stored in a config file in `conf/`. The file
  27      to use is selected by writing to `conf/local/ENVIRONMENT`, or setting the
  28      `PHABRICATOR_ENV` configuration variable. See below for more information.
  29    - **Defaults**: Defaults hard-coded in the Phabricator source, which can not
  30      be edited. They have the lowest priority, and all other settings override
  31      them.
  32  
  33  Normally, you install and configure Phabricator by writing enough configuration
  34  into the local config to get access to the database configuration (e.g., the
  35  MySQL username, password, and hostname), then use the web interface to further
  36  configure Phabricator.
  37  
  38  = Configuration Files =
  39  
  40  Configuration files provide an alternative to database configuration, and may be
  41  appropriate if you want to deploy in multiple environments or create dynamic
  42  configuration. Configuration files are more complicated than database
  43  configuration, which is why they are not used by default.
  44  
  45  == Creating a Configuration File ==
  46  
  47  To create a configuration file, first choose a name for the config (like
  48  "devserver" or "live"). For the purposes of this section, we'll assume you chose
  49  `exampleconfig`. Replace "exampleconfig" with whatever you actually chose in the
  50  examples below.
  51  
  52  First, write an `exampleconfig.conf.php` file here (rename it according to the
  53  name you chose):
  54  
  55    phabricator/conf/custom/exampleconfig.conf.php
  56  
  57  Its contents should look like this:
  58  
  59    <?php
  60  
  61    return array(
  62      // Specify whichever keys and values you want to set.
  63      'example.key' => 'examplevalue',
  64    );
  65  
  66  For example, to specify MySQL credentials in your config file, you might create
  67  a config like this:
  68  
  69    <?php
  70  
  71    return array(
  72      'mysql.host' => 'localhost',
  73      'mysql.user' => 'root',
  74      'mysql.pass' => 'hunter2trustno1',
  75    );
  76  
  77  == Selecting a Configuration File ==
  78  
  79  To select a configuration file, write the name of the file (relative to
  80  `phabricator/conf/`) to `phabricator/conf/local/ENVIRONMENT`. For example, to
  81  select `phabricator/conf/custom/exampleconfig.conf.php`, you would write
  82  "custom/exampleconfig" to `phabrictor/conf/local/ENVIRONMENT`:
  83  
  84    phabricator/ $ echo custom/exampleconfig > conf/local/ENVIRONMENT
  85    phabricator/ $ cat conf/local/ENVIRONMENT
  86    custom/exampleconfig
  87    phabricator/ $
  88  
  89  You can also set the environmental variable `PHABRICATOR_ENV`. This is more
  90  involved but may be easier in some deployment environments. Note that this needs
  91  to be set in your webserver environment, and also in your shell whenever you
  92  run a script:
  93  
  94  ```
  95  # Shell
  96  export PHABRICATOR_ENV=custom/exampleconfig
  97  
  98  # Apache
  99  SetEnv PHABRICATOR_ENV custom/exampleconfig
 100  
 101  # nginx
 102  fastcgi_param PHABRICATOR_ENV "custom/exampleconfig";
 103  
 104  # lighttpd
 105  setenv.add-environment = (
 106     "PHABRICATOR_ENV" => "custom/exampleconfig",
 107  )
 108  ```
 109  
 110  After creating and selecting a configuration file, restart your webserver. Any
 111  configuration you set should take effect immediately, and your file should be
 112  visible in the Config application when examining configuration.
 113  
 114  = Next Steps =
 115  
 116  Return to the @{article:Configuration Guide}.