[Summary view] [Print] [Text view]

   1  @title Configuring Backups and Performing Migrations
   2  @group config
   3  
   4  Advice for backing up Phabricator, or migrating from one machine to another.
   5  
   6  = Overview =
   7  
   8  Phabricator does not currently have a comprehensive backup system, but creating
   9  backups is not particularly difficult and Phabricator does have a few basic
  10  tools which can help you set up a reasonable process. In particular, the things
  11  which needs to be backed up are:
  12  
  13    - the MySQL databases;
  14    - uploaded files; and
  15    - your Phabricator configuration files.
  16  
  17  This document discusses approaches for backing up this data.
  18  
  19  If you are migrating from one machine to another, you can generally follow the
  20  same steps you would if you were creating a backup and then restoring it, you
  21  will just backup the old machine and then restore the data onto the new
  22  machine.
  23  
  24  = Backup: MySQL Databases =
  25  
  26  Most of Phabricator's data is stored in MySQL, and it's the most important thing
  27  to back up. You can run `bin/storage dump` to get a dump of all the MySQL
  28  databases. This is a convenience script which just runs a normal `mysqldump`,
  29  but will only dump databases Phabricator owns.
  30  
  31  Since most of this data is compressible, it may be helpful to run it through
  32  gzip prior to storage. For example:
  33  
  34    phabricator/ $ ./bin/storage dump | gzip > backup.sql.gz
  35  
  36  Then store the backup somewhere safe, like in a box buried under an old tree
  37  stump. No one will ever think to look for it there.
  38  
  39  = Restore: MySQL =
  40  
  41  To restore a MySQL dump, just pipe it to `mysql` on a clean host. (You may need
  42  to uncompress it first, if you compressed it prior to storage.)
  43  
  44    $ gunzip -c backup.sql.gz | mysql
  45  
  46  = Backup: Uploaded Files =
  47  
  48  Uploaded files may be stored in several different locations. The backup
  49  procedure depends on where files are stored:
  50  
  51  **Default / MySQL**: Under the default configuration, uploaded files are stored
  52  in MySQL, so the MySQL backup will include all files. In this case, you don't
  53  need to do any additional work.
  54  
  55  **Amazon S3**: If you use Amazon S3, redundancy and backups are built in to the
  56  service. This is probably sufficient for most installs. If you trust Amazon with
  57  your data //except not really//, you can backup your S3 bucket outside of
  58  Phabricator.
  59  
  60  **Local Disk**: If you use the local disk storage engine, you'll need to back up
  61  files manually. You can do this by creating a copy of the root directory where
  62  you told Phabricator to put files (the `storage.local-disk.path` configuration
  63  setting).
  64  
  65  For more information about configuring how files are stored, see
  66  @{article:Configuring File Storage}.
  67  
  68  = Restore: Uploaded Files =
  69  
  70  To restore a backup of local disk storage, just copy the backup into place.
  71  
  72  = Backup: Configuration Files =
  73  
  74  You should also backup your configuration files, and any scripts you use to
  75  deploy or administrate Phabricator (like a customized upgrade script). The best
  76  way to do this is to check them into a private repository somewhere and just use
  77  whatever backup process you already have in place for repositories. Just copying
  78  them somewhere will work fine too, of course.
  79  
  80  = Restore: Configuration Files =
  81  
  82  To restore configuration files, just copy them into the right locations.
  83  
  84  = Security =
  85  
  86  MySQL dumps have no builtin encryption and most data in Phabricator is stored in
  87  a raw, accessible form, so giving a user access to backups is a lot like giving
  88  them shell access to the machine Phabricator runs on. In particular, a user who
  89  has the backups can:
  90  
  91    - read data that policies do not permit them to see;
  92    - read email addresses and object secret keys; and
  93    - read other users' session and conduit tokens and impersonate them.
  94  
  95  Some of this information is durable, so disclosure of even a very old backup may
  96  present a risk. If you restrict access to the Phabricator host or database, you
  97  should also restrict access to the backups.
  98  
  99  = Next Steps =
 100  
 101  Continue by:
 102  
 103    - returning to the @{article:Configuration Guide}.