Differential D25007 Diff 23 src/docs/user/configuration/advanced_configuration.diviner

Changeset View

Standalone View

src/docs/user/configuration/advanced_configuration.diviner

	@title Configuration User Guide: Advanced Configuration			@title Configuration User Guide: Advanced Configuration
	@group config			@group config

	Configuring Phabricator for multiple environments.			Configuring Phorge for multiple environments.

	= Overview =			= Overview =

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

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

	= Configuration Sources =			= Configuration Sources =

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

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

	Normally, you install and configure Phabricator by writing enough configuration			Normally, you install and configure Phorge by writing enough configuration
	into the local config to get access to the database configuration (e.g., the			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			MySQL username, password, and hostname), then use the web interface to further
	configure Phabricator.			configure Phorge.

	= Configuration Files =			= Configuration Files =

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

	== Creating a Configuration File ==			== Creating a Configuration File ==

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

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

	phabricator/conf/custom/exampleconfig.conf.php			phorge/conf/custom/exampleconfig.conf.php

	Its contents should look like this:			Its contents should look like this:

	<?php			<?php

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

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

	<?php			<?php

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

	== Selecting a Configuration File ==			== Selecting a Configuration File ==

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

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

	You can also set the environmental variable `PHABRICATOR_ENV`. This is more			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			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			to be set in your webserver environment, and also in your shell whenever you
	run a script:			run a script:

	```			```
	# Shell			# Shell
	export PHABRICATOR_ENV=custom/exampleconfig			export PHABRICATOR_ENV=custom/exampleconfig

	# Apache			# Apache
	SetEnv PHABRICATOR_ENV custom/exampleconfig			SetEnv PHABRICATOR_ENV custom/exampleconfig

	# nginx			# nginx
	fastcgi_param PHABRICATOR_ENV "custom/exampleconfig";			fastcgi_param PHABRICATOR_ENV "custom/exampleconfig";

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

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

	= Next Steps =			= Next Steps =

	Return to the @{article:Configuration Guide}.			Return to the @{article:Configuration Guide}.