Differential D25007 Diff 19 src/docs/user/configuration/configuring_backups.diviner

Changeset View

Standalone View

src/docs/user/configuration/configuring_backups.diviner

	@title Configuring Backups and Performing Migrations			@title Configuring Backups and Performing Migrations
	@group config			@group config

	Advice for backing up Phabricator, or migrating from one machine to another.			Advice for backing up Phorge, or migrating from one machine to another.


	Overview			Overview
	========			========

	Phabricator does not currently have a comprehensive backup system, but creating			Phorge does not currently have a comprehensive backup system, but creating
	backups is not particularly difficult and Phabricator does have a few basic			backups is not particularly difficult and Phorge does have a few basic
	tools which can help you set up a reasonable process. In particular, the things			tools which can help you set up a reasonable process. In particular, the things
	which needs to be backed up are:			which needs to be backed up are:

	- the MySQL databases;			- the MySQL databases;
	- hosted repositories;			- hosted repositories;
	- uploaded files; and			- uploaded files; and
	- your Phabricator configuration files.			- your Phorge configuration files.

	This document discusses approaches for backing up this data.			This document discusses approaches for backing up this data.

	If you are migrating from one machine to another, you can generally follow the			If you are migrating from one machine to another, you can generally follow the
	same steps you would if you were creating a backup and then restoring it, you			same steps you would if you were creating a backup and then restoring it, you
	will just backup the old machine and then restore the data onto the new			will just backup the old machine and then restore the data onto the new
	machine.			machine.

	WARNING: You need to restart Phabricator after restoring data.			WARNING: You need to restart Phorge after restoring data.

	Restarting Phabricator after performing a restore makes sure that caches are			Restarting Phorge after performing a restore makes sure that caches are
	flushed properly. For complete instructions, see			flushed properly. For complete instructions, see
	@{article:Restarting Phabricator}.			@{article:Restarting Phorge}.


	Backup: MySQL Databases			Backup: MySQL Databases
	=======================			=======================

	Most of Phabricator's data is stored in MySQL, and it's the most important thing			Most of Phorge'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			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`,			databases. This is a convenience script which just runs a normal `mysqldump`,
	but will only dump databases Phabricator owns.			but will only dump databases Phorge owns.

	Since most of this data is compressible, it may be helpful to run it through			Since most of this data is compressible, it may be helpful to run it through
	gzip prior to storage. For example:			gzip prior to storage. For example:

	phabricator/ $ ./bin/storage dump --compress --output backup.sql.gz			phorge/ $ ./bin/storage dump --compress --output backup.sql.gz

	Then store the backup somewhere safe, like in a box buried under an old tree			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.			stump. No one will ever think to look for it there.

	Restore: MySQL			Restore: MySQL
	==============			==============

	To restore a MySQL dump, just pipe it to `mysql` on a clean host. (You may need			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.)			to uncompress it first, if you compressed it prior to storage.)

	$ gunzip -c backup.sql.gz \| mysql			$ gunzip -c backup.sql.gz \| mysql


	Backup: Hosted Repositories			Backup: Hosted Repositories
	===========================			===========================

	If you host repositories in Phabricator, you should back them up. You can use			If you host repositories in Phorge, you should back them up. You can use
	`bin/repository list-paths` to show the local paths on disk for each			`bin/repository list-paths` to show the local paths on disk for each
	repository. To back them up, copy them elsewhere.			repository. To back them up, copy them elsewhere.

	You can also just clone them and keep the clones up to date, or use			You can also just clone them and keep the clones up to date, or use
	{nav Add Mirror} to have them mirror somewhere automatically.			{nav Add Mirror} to have them mirror somewhere automatically.


	Restore: Hosted Repositories			Restore: Hosted Repositories
	Show All 11 Lines

	Default / MySQL: Under the default configuration, uploaded 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			in MySQL, so the MySQL backup will include all files. In this case, you don't
	need to do any additional work.			need to do any additional work.

	Amazon S3: If you use Amazon S3, redundancy and backups are built in to the			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			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			your data //except not really//, you can backup your S3 bucket outside of
	Phabricator.			Phorge.

	Local Disk: If you use the local disk storage engine, you'll need to back up			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			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			you told Phorge to put files (the `storage.local-disk.path` configuration
	setting).			setting).

	For more information about configuring how files are stored, see			For more information about configuring how files are stored, see
	@{article:Configuring File Storage}.			@{article:Configuring File Storage}.


	Restore: Uploaded Files			Restore: Uploaded Files
	=======================			=======================

	To restore a backup of local disk storage, just copy the backup into place.			To restore a backup of local disk storage, just copy the backup into place.


	Backup: Configuration Files			Backup: Configuration Files
	===========================			===========================

	You should also backup your configuration files, and any scripts you use to			You should also backup your configuration files, and any scripts you use to
	deploy or administrate Phabricator (like a customized upgrade script). The best			deploy or administrate Phorge (like a customized upgrade script). The best
	way to do this is to check them into a private repository somewhere and just use			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			whatever backup process you already have in place for repositories. Just copying
	them somewhere will work fine too, of course.			them somewhere will work fine too, of course.

	In particular, you should backup this configuration file which Phabricator			In particular, you should backup this configuration file which Phorge
	creates:			creates:

	phabricator/conf/local/local.json			phorge/conf/local/local.json

	This file contains all of the configuration settings that have been adjusted			This file contains all of the configuration settings that have been adjusted
	by using `bin/config set <key> <value>`.			by using `bin/config set <key> <value>`.


	Restore: Configuration Files			Restore: Configuration Files
	============================			============================

	To restore configuration files, just copy them into the right locations. Copy			To restore configuration files, just copy them into the right locations. Copy
	your backup of `local.json` to `phabricator/conf/local/local.json`.			your backup of `local.json` to `phorge/conf/local/local.json`.

	Security			Security
	========			========

	MySQL dumps have no builtin encryption and most data in Phabricator is stored in			MySQL dumps have no builtin encryption and most data in Phorge is stored in
	a raw, accessible form, so giving a user access to backups is a lot like giving			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			them shell access to the machine Phorge runs on. In particular, a user who
	has the backups can:			has the backups can:

	- read data that policies do not permit them to see;			- read data that policies do not permit them to see;
	- read email addresses and object secret keys; and			- read email addresses and object secret keys; and
	- read other users' session and conduit tokens and impersonate them.			- 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			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			present a risk. If you restrict access to the Phorge host or database, you
	should also restrict access to the backups.			should also restrict access to the backups.


	Skipping Indexes			Skipping Indexes
	================			================

	By default, `bin/storage dump` does not dump all of the data in the database:			By default, `bin/storage dump` does not dump all of the data in the database:
	it skips some caches which can be rebuilt automatically and do not need to be			it skips some caches which can be rebuilt automatically and do not need to be
	Show All 19 Lines