Differential D25007 Diff 21 src/docs/user/configuration/configuration_guide.diviner

Changeset View

Standalone View

src/docs/user/configuration/configuration_guide.diviner

	@title Configuration Guide			@title Configuration Guide
	@group config			@group config

	This document contains basic configuration instructions for Phabricator.			This document contains basic configuration instructions for Phorge.

	= Prerequisites =			= Prerequisites =

	This document assumes you've already installed all the components you need.			This document assumes you've already installed all the components you need.
	If you haven't, see @{article:Installation Guide}.			If you haven't, see @{article:Installation Guide}.

	The next steps are:			The next steps are:

	- Configure your webserver (Apache, nginx, or lighttpd).			- Configure your webserver (Apache, nginx, or lighttpd).
	- Access Phabricator with your browser.			- Access Phorge with your browser.
	- Follow the instructions to complete setup.			- Follow the instructions to complete setup.

	= Webserver: Configuring Apache =			= Webserver: Configuring Apache =

	NOTE: Follow these instructions to use Apache. To use nginx or lighttpd, scroll			NOTE: Follow these instructions to use Apache. To use nginx or lighttpd, scroll
	down to their sections.			down to their sections.

	Get Apache running and verify it's serving a test page. Consult the Apache			Get Apache running and verify it's serving a test page. Consult the Apache
	documentation for help. Make sure `mod_php` and `mod_rewrite` are enabled,			documentation for help. Make sure `mod_php` and `mod_rewrite` are enabled,
	and `mod_ssl` if you intend to set up SSL.			and `mod_ssl` if you intend to set up SSL.

	If you haven't already, set up a domain name to point to the host you're			If you haven't already, set up a domain name to point to the host you're
	installing on. You can either install Phabricator on a subdomain (like			installing on. You can either install Phorge on a subdomain (like
	phabricator.example.com) or an entire domain, but you can not install it in			phorge.example.com) or an entire domain, but you can not install it in
	some subdirectory of an existing website. Navigate to whatever domain you're			some subdirectory of an existing website. Navigate to whatever domain you're
	going to use and make sure Apache serves you something to verify that DNS			going to use and make sure Apache serves you something to verify that DNS
	is correctly configured.			is correctly configured.

	NOTE: The domain must contain a dot ('.'), i.e. not be just a bare name like			NOTE: The domain must contain a dot ('.'), i.e. not be just a bare name like
	'http://example/'. Some web browsers will not set cookies otherwise.			'http://example/'. Some web browsers will not set cookies otherwise.

	Now create a VirtualHost entry for Phabricator. It should look something like			Now create a VirtualHost entry for Phorge. It should look something like
	this:			this:

	name=httpd.conf			name=httpd.conf
	<VirtualHost *>			<VirtualHost *>
	# Change this to the domain which points to your host.			# Change this to the domain which points to your host.
	ServerName phabricator.example.com			ServerName phorge.example.com

	# Change this to the path where you put 'phabricator' when you checked it			# Change this to the path where you put 'phorge' when you checked it
	# out from GitHub when following the Installation Guide.			# out from the upstream when following the Installation Guide.
	#			#
	# Make sure you include "/webroot" at the end!			# Make sure you include "/webroot" at the end!
	DocumentRoot /path/to/phabricator/webroot			DocumentRoot /path/to/phorge/webroot

	RewriteEngine on			RewriteEngine on
	RewriteRule ^(.*)$ /index.php?__path__=$1 [B,L,QSA]			RewriteRule ^(.*)$ /index.php?__path__=$1 [B,L,QSA]
	</VirtualHost>			</VirtualHost>

	If Apache isn't currently configured to serve documents out of the directory			If Apache isn't currently configured to serve documents out of the directory
	where you put Phabricator, you may also need to add `<Directory />` section. The			where you put Phorge, you may also need to add `<Directory />` section. The
	syntax for this section depends on which version of Apache you're running.			syntax for this section depends on which version of Apache you're running.
	(If you don't know, you can usually figure this out by running `httpd -v`.)			(If you don't know, you can usually figure this out by running `httpd -v`.)
	For Apache versions older than 2.4, use this:			For Apache versions older than 2.4, use this:

	name="Apache Older Than 2.4"			name="Apache Older Than 2.4"
	<Directory "/path/to/phabricator/webroot">			<Directory "/path/to/phorge/webroot">
	Order allow,deny			Order allow,deny
	Allow from all			Allow from all
	</Directory>			</Directory>

	For Apache versions 2.4 and newer, use this:			For Apache versions 2.4 and newer, use this:

	name="Apache 2.4 and Newer"			name="Apache 2.4 and Newer"
	<Directory "/path/to/phabricator/webroot">			<Directory "/path/to/phorge/webroot">
	Require all granted			Require all granted
	</Directory>			</Directory>

	After making your edits, restart Apache, then continue to "Setup" below.			After making your edits, restart Apache, then continue to "Setup" below.

	= Webserver: Configuring nginx =			= Webserver: Configuring nginx =

	NOTE: Follow these instructions to use nginx. To use Apache or lighttpd, scroll			NOTE: Follow these instructions to use nginx. To use Apache or lighttpd, scroll
	to their sections.			to their sections.

	For nginx, use a configuration like this:			For nginx, use a configuration like this:

	name=nginx.conf			name=nginx.conf
	server {			server {
	server_name phabricator.example.com;			server_name phorge.example.com;
	root /path/to/phabricator/webroot;			root /path/to/phorge/webroot;

	location / {			location / {
	index index.php;			index index.php;
	rewrite ^/(.*)$ /index.php?__path__=/$1 last;			rewrite ^/(.*)$ /index.php?__path__=/$1 last;
	}			}

	location /index.php {			location /index.php {
	fastcgi_pass localhost:9000;			fastcgi_pass localhost:9000;
	Show All 22 Lines

	= Webserver: Configuring lighttpd =			= Webserver: Configuring lighttpd =

	NOTE: Follow these instructions to use lighttpd. To use Apache or nginx, scroll			NOTE: Follow these instructions to use lighttpd. To use Apache or nginx, scroll
	up to their sections.			up to their sections.

	For lighttpd, add a section like this to your lighttpd.conf:			For lighttpd, add a section like this to your lighttpd.conf:

	$HTTP["host"] =~ "phabricator(\.example\.com)?" {			$HTTP["host"] =~ "phorge(\.example\.com)?" {
	server.document-root = "/path/to/phabricator/webroot"			server.document-root = "/path/to/phorge/webroot"
	url.rewrite-once = (			url.rewrite-once = (
	# This simulates QSA ("query string append") mode in apache			# This simulates QSA ("query string append") mode in apache
	"^(/[^?])\?(.)" => "/index.php?__path__=$1&$2",			"^(/[^?])\?(.)" => "/index.php?__path__=$1&$2",
	"^(/.*)$" => "/index.php?__path__=$1",			"^(/.*)$" => "/index.php?__path__=$1",
	)			)
	}			}

	You should also ensure the following modules are listed in your			You should also ensure the following modules are listed in your
	Show All 28 Lines
	configure how other users will be able to log in or register -- until you do,			configure how other users will be able to log in or register -- until you do,
	no one else will be able to sign up or log in. For more information, see			no one else will be able to sign up or log in. For more information, see
	@{article:Configuring Accounts and Registration}.			@{article:Configuring Accounts and Registration}.

	= Storage: Configuring MySQL =			= Storage: Configuring MySQL =

	During setup, you'll need to configure MySQL. To do this, get MySQL running and			During setup, you'll need to configure MySQL. To do this, get MySQL running and
	verify you can connect to it. Consult the MySQL documentation for help. When			verify you can connect to it. Consult the MySQL documentation for help. When
	MySQL works, you need to load the Phabricator schemata into it. To do this, run:			MySQL works, you need to load the Phorge schemata into it. To do this, run:

	phabricator/ $ ./bin/storage upgrade			phorge/ $ ./bin/storage upgrade

	If your configuration uses an unprivileged user to connect to the database, you			If your configuration uses an unprivileged user to connect to the database, you
	may have to override the default user so the schema changes can be applied with			may have to override the default user so the schema changes can be applied with
	root or some other admin user:			root or some other admin user:

	phabricator/ $ ./bin/storage upgrade --user <user> --password <password>			phorge/ $ ./bin/storage upgrade --user <user> --password <password>

	You can avoid the prompt the script issues by passing the `--force` flag (for			You can avoid the prompt the script issues by passing the `--force` flag (for
	example, if you are scripting the upgrade process).			example, if you are scripting the upgrade process).

	phabricator/ $ ./bin/storage upgrade --force			phorge/ $ ./bin/storage upgrade --force

	NOTE: When you update Phabricator, run `storage upgrade` again to apply any			NOTE: When you update Phorge, run `storage upgrade` again to apply any
	new updates.			new updates.

	= Next Steps =			= Next Steps =

	Continue by:			Continue by:

	- setting up your admin account and login/registration with			- setting up your admin account and login/registration with
	@{article:Configuring Accounts and Registration}; or			@{article:Configuring Accounts and Registration}; or
	- understanding advanced configuration topics with			- understanding advanced configuration topics with
	@{article:Configuration User Guide: Advanced Configuration}; or			@{article:Configuration User Guide: Advanced Configuration}; or
	- configuring an alternate file domain with			- configuring an alternate file domain with
	@{article:Configuring a File Domain}; or			@{article:Configuring a File Domain}; or
	- configuring a preamble script to set up the environment properly behind a			- configuring a preamble script to set up the environment properly behind a
	load balancer, or adjust rate limiting with			load balancer, or adjust rate limiting with
	@{article:Configuring a Preamble Script}; or			@{article:Configuring a Preamble Script}; or
	- configuring where uploaded files and attachments will be stored with			- configuring where uploaded files and attachments will be stored with
	@{article:Configuring File Storage}; or			@{article:Configuring File Storage}; or
	- configuring Phabricator so it can send mail with			- configuring Phorge so it can send mail with
	@{article:Configuring Outbound Email}; or			@{article:Configuring Outbound Email}; or
	- configuring inbound mail with @{article:Configuring Inbound Email}; or			- configuring inbound mail with @{article:Configuring Inbound Email}; or
	- importing repositories with @{article:Diffusion User Guide}; or			- importing repositories with @{article:Diffusion User Guide}; or
	- learning about daemons with @{article:Managing Daemons with phd}; or			- learning about daemons with @{article:Managing Daemons with phd}; or
	- learning about notification with			- learning about notification with
	@{article:Notifications User Guide: Setup and Configuration}; or			@{article:Notifications User Guide: Setup and Configuration}; or
	- configuring backups with			- configuring backups with
	@{article:Configuring Backups and Performing Migrations}; or			@{article:Configuring Backups and Performing Migrations}; or
	- contributing to Phabricator with @{article:Contributor Introduction}.			- contributing to Phorge with @{article:Contributor Introduction}.