Changeset View
Changeset View
Standalone 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 |
Content licensed under Creative Commons Attribution-ShareAlike 4.0 (CC-BY-SA) unless otherwise noted; code licensed under Apache 2.0 or other open source licenses. · CC BY-SA 4.0 · Apache 2.0