No OneTemporary
Actions

Size

13 KB

Referenced Files

None

Subscribers

None

View Options

	diff --git a/src/docs/configuration/configuration_guide.diviner b/src/docs/configuration/configuration_guide.diviner
	index 46e5b5723d..9910e16628 100644
	--- a/src/docs/configuration/configuration_guide.diviner
	+++ b/src/docs/configuration/configuration_guide.diviner
	@@ -1,262 +1,263 @@
	@title Configuration Guide
	@group config

	This document contains basic configuration instructions for Phabricator.

	= Prerequisites =

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

	= Configuring Phabricator =

	Create a new file here:

	path/to/phabricator/conf/custom/myconfig.conf.php

	...where ##myconfig## is some name which identifies your installation. Put this
	in the file:

	name=myconfig.conf.php, lang=php
	<?php

	return array(

	// Important! This will put Phabricator into setup mode to help you
	// configure things.
	'phabricator.setup' => true,

	// This will be the base domain for your install, and must be configured.
	// Use "https://" if you have SSL. See below for some notes.
	'phabricator.base-uri' => 'http://phabricator.example.com/',

	// Connection information for MySQL.
	'mysql.host' => 'localhost',
	'mysql.user' => 'root',
	'mysql.pass' => 'trustno1hunter2',

	// Basic email domain configuration.
	'metamta.default-address' => 'noreply@phabricator.example.com',
	'metamta.domain' => 'phabricator.example.com',

	// NOTE: Check default.conf.php for detailed explanations of all the
	// configuration options, including these.

	) + phabricator_read_config_file('production');

	For the last line, you can also use ##'development'## instead of
	##'production'## if you are planning to develop Phabricator itself. This will
	turn on some debugging features.

	= PHABRICATOR_ENV Environment Variable =

	When running Phabricator scripts, they will ask you to set the `PHABRICATOR_ENV`
	environment variable to point at your config. If you put your script in
	`custom/myconfig.conf.php`, you can identify the config with
	`custom/myconfig`, like this:

	$ PHABRICATOR_ENV=custom/myconfig ./some_phabricator_command

	NOTE: Make sure you put 'PHABRICATOR_ENV=...' at the beginning of the line, not
	in the middle. The shell won't parse environmental variables declared after the
	command. You can also ##export PHABRICATOR_ENV=...## in your ~/.bashrc or
	~/.profile or similar, depending on which shell you use and how your system is
	configured.

	= Storage: Configuring MySQL =

	Get MySQL running and 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:

	phabricator/ $ ./bin/storage upgrade

	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
	root or some other admin user:

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

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

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

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

	= Webserver: Configuring 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,
	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
	installing on. You can either install Phabricator on a subdomain (like
	phabricator.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
	going to use and make sure Apache serves you something to verify that DNS
	is correctly configured.

	Now, either create a VirtualHost entry (to put Phabricator on a subdomain)
	or edit the Directory entry for the DocumentRoot. It should look something like
	this:

	name=httpd.conf
	<VirtualHost *>
	# Change this to the domain which points to your host, i.e. the domain
	# you set as "phabricator.base-uri".
	ServerName phabricator.example.com

	# Change this to the path where you put 'phabricator' when you checked it
	# out from github when following the Installation Guide.
	DocumentRoot /path/to/phabricator/webroot

	RewriteEngine on
	RewriteRule ^/rsrc/(.*) - [L,QSA]
	RewriteRule ^/favicon.ico - [L,QSA]
	RewriteRule ^(.*)$ /index.php?__path__=$1 [B,L,QSA]

	# This will use the config file you set up in the previous step. If you
	# called it something other than 'myconfig', put that here.
	SetEnv PHABRICATOR_ENV custom/myconfig
	</VirtualHost>

	Continue to "Setup" below.

	= Webserver: Configuring nginx =

	For nginx, use a configuration like this:

	name=nginx.conf
	server {
	server_name phabricator.example.com;

	root /path/to/phabricator/webroot;
	try_files $uri $uri/ /index.php;

	location / {
	index index.php;

	if ( !-f $request_filename )
	{
	rewrite ^/(.*)$ /index.php?__path__=/$1 last;
	break;
	}
	}

	location /index.php {
	fastcgi_pass localhost:9000;
	fastcgi_index index.php;

	#custom environment variable
	fastcgi_param PHABRICATOR_ENV "custom/myconfig";

	#required if PHP was built with --enable-force-cgi-redirect
	fastcgi_param REDIRECT_STATUS 200;

	#variables to make the $_SERVER populate in PHP
	fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
	fastcgi_param QUERY_STRING $query_string;
	fastcgi_param REQUEST_METHOD $request_method;
	fastcgi_param CONTENT_TYPE $content_type;
	fastcgi_param CONTENT_LENGTH $content_length;

	fastcgi_param SCRIPT_NAME $fastcgi_script_name;

	fastcgi_param GATEWAY_INTERFACE CGI/1.1;
	fastcgi_param SERVER_SOFTWARE nginx/$nginx_version;

	fastcgi_param REMOTE_ADDR $remote_addr;
	}
	}

	= Webserver: Configuring lighttpd =

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

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

	You should also ensure the following modules are listed in your
	server.modules list:

	mod_fastcgi
	mod_rewrite
	mod_setenv

	Finally, you should run the following commands to enable php support:

	$ sudo apt-get install php5-cgi # for ubuntu; other distros should be similar
	$ sudo lighty-enable-mod fastcgi-php

	= Setup =

	Now, restart your webserver and navigate to whichever subdomain you set up. You
	should either see the Phabricator setup screen, which is a simple text page that
	looks something like this:

	PHABRICATOR SETUP

	This setup mode will guide you through setting up your Phabricator
	configuration.

	>>> REQUIRED PHP EXTENSIONS ------------------------------------------------
	...

	If you see this, you're in good shape. Follow the instructions and correct any
	problems setup detects. If you don't see it but you do see a useful error
	message, try to fix that. If neither of these cover you, something is wrong.
	If you can't figure it out, come get help in IRC or on the mailing list (see
	http://phabricator.org/ for links).

	= Configuring Phabricator =

	Now that basic setup is complete, you should configure Phabricator for your
	installation. Phabricator configuration options which control how the
	applications behave are documented here:

	/path/to/phabricator/conf/default.conf.php

	There are several builtin configurations:

	- ##default.conf.php##: root configuration, lists every configuration option
	and sets some default for it. Look in this file to figure out what you can
	configure.
	- ##development.conf.php##: pulls in ##default.conf.php##, but overrides some
	configuration options to better values for doing development on Phabricator.
	You probably don't need to even look at this file unless you're making
	changes to Phabricator itself.
	- ##production.conf.php##: pulls in ##default.conf.php##, but overrides some
	configuration options to provide better values for a production install.

	To actually configure your install, edit your ##custom/myconfig.conf.php## file
	and override values from either the ##'production'## or ##'development'##
	configurations. You should not edit the builtin configurations directly because
	that will make upgrading Phabricator more difficult in the future.

	= Next Steps =

	Continue by:

	- setting up your admin account and login/registration with
	@{article:Configuring Accounts and Registration}; or
	- configuring where uploaded files and attachments will be stored with
	@{article:Configuring File Storage}; or
	- configuring Phabricator so it can send mail with
	@{article:Configuring Outbound Email}; or
	- configuring inbound mail with @{article:Configuring Inbound Email}; or
	- importing repositories with @{article:Diffusion User Guide}; or
	- learning about daemons with @{article:Managing Daemons with phd}; or
	+ - configuring backups with @{article:Configuring Backups}; or
	- contributing to Phabricator with @{article:Contributor Introduction}.
	diff --git a/src/docs/configuration/configuring_backups.diviner b/src/docs/configuration/configuring_backups.diviner
	new file mode 100644
	index 0000000000..20aee18e33
	--- /dev/null
	+++ b/src/docs/configuration/configuring_backups.diviner
	@@ -0,0 +1,98 @@
	+@title Configuring Backups
	+@group config
	+
	+Advice for backing up Phabricator.
	+
	+= Overview =
	+
	+Phabricator does not currently have a comprehensive backup system, but creating
	+backups is not particularly difficult and Phabricator does have a few basic
	+tools which can help you set up a reasonable process. In particular, the things
	+which needs to be backed up are:
	+
	+ - the MySQL databases;
	+ - uploaded files; and
	+ - your Phabricator configuration files.
	+
	+This document discusses approaches for backing up this data.
	+
	+= Backup: MySQL Databases =
	+
	+Most of Phabricator's data is stored in MySQL, and it's the most important thing
	+to back up. You can run `bin/storage dump` to get a dump of all the MySQL
	+databases. This is a convenience script which just runs a normal `mysqldump`
	+of every database Phabricator owns.
	+
	+Since most of this data is compressible, it may be helpful to run it through
	+gzip prior to storage. For example:
	+
	+ phabricator/ $ ./bin/storage dump \| gzip > backup.sql.gz
	+
	+Then store the backup somewhere safe, like in a box buried under an old tree
	+stump. No one will ever think to look for it there.
	+
	+= Restore: MySQL =
	+
	+To restore a MySQL dump, just pipe it to `mysql` on a clean host. (You may need
	+to uncompress it first, if you compressed it prior to storage.)
	+
	+ $ gunzip -c backup.sql.gz \| mysql
	+
	+= Backup: Uploaded Files =
	+
	+Uploaded files may be stored in several different locations. The backup
	+procedure depends on where files are stored:
	+
	+Default / MySQL: Under the default configuration, uploaded files are stored
	+in MySQL, so the MySQL backup will include all files. In this case, you don't
	+need to do any additional work.
	+
	+Amazon S3: If you use Amazon S3, redundancy and backups are built in to the
	+service. This is probably sufficient for most installs. If you trust Amazon with
	+your data //except not really//, you can backup your S3 bucket outside of
	+Phabricator.
	+
	+Local Disk: If you use the local disk storage engine, you'll need to back up
	+files manually. You can do this by creating a copy of the root directory where
	+you told Phabricator to put files (the `storage.local-disk.path` configuration
	+setting).
	+
	+For more information about configuring how files are stored, see
	+@{article:Configuring File Storage}.
	+
	+= Restore: Uploaded Files =
	+
	+To restore a backup of local disk storage, just copy the backup into place.
	+
	+= Backup: Configuration Files =
	+
	+You should also backup your configuration files, and any scripts you use to
	+deploy or administrate Phabricator (like a customized upgrade script). The best
	+way to do this is to check them into a private repository somewhere and just use
	+whatever backup process you already have in place for repositories. Just copying
	+them somewhere will work fine too, of course.
	+
	+= Restore: Configuration Files =
	+
	+To restore configuration files, just copy them into the right locations.
	+
	+= Security =
	+
	+MySQL dumps have no builtin encryption and most data in Phabricator is stored in
	+a raw, accessible form, so giving a user access to backups is a lot like giving
	+them shell access to the machine Phabricator runs on. In particular, a user who
	+has the backups can:
	+
	+ - read data that policies do not permit them to see;
	+ - read email addresses and object secret keys; and
	+ - read other users' session and conduit tokens and impersonate them.
	+
	+Some of this information is durable, so disclosure of even a very old backup may
	+present a risk. If you restrict access to the Phabricator host or database, you
	+should also restrict access to the backups.
	+
	+= Next Steps =
	+
	+Continue by:
	+
	+ - returning to the @{article:Configuration Guide}.

File Metadata

Mime Type: text/x-diff
Expires: Sat, Nov 15, 1:14 AM (1 d, 1 h)
Storage Engine: blob
Storage Format: Raw Data
Storage Handle: 337381
Default Alt Text: (13 KB)

No OneTemporaryActions

View Options

File Metadata

Event Timeline

No OneTemporary
Actions