Homec4science
Diffusion Phabricator (feature/better-testing) Browse

phab/src/docs/user/configuration/advanced_configuration.diviner
6b372d7d7a35feature/better-testing

Last Change
Raw File

advanced_configuration.diviner
View Options

@title Configuration User Guide: Advanced Configuration
@group config
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/config.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 @{article: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 @{article:Configuration Guide}.
c4science · Help