Move the "Advanced Configuration" documentation.

Summary: This documentation doesn't really fall under the "Application User Guides" section, it should be moved to "Configuration".

Test Plan: N/A

Reviewers: epriestley, #blessed_reviewers

Reviewed By: epriestley, #blessed_reviewers

Subscribers: epriestley, Korvin

Differential Revision: https://secure.phabricator.com/D9403

src/docs/user/configuration/advanced_configuration.diviner

@@ -0,0 +1,116 @@
+@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 `phabrictor/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 your webserver. 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}.