@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
1@title Configuring Backups and Performing Migrations
2@group config
3
4Advice for backing up Phorge, or migrating from one machine to another.
5
6
7Overview
8========
9
10Phorge does not currently have a comprehensive backup system, but creating
11backups is not particularly difficult and Phorge does have a few basic
12tools which can help you set up a reasonable process. In particular, the things
13which needs to be backed up are:
14
15 - the MySQL databases;
16 - hosted repositories;
17 - uploaded files; and
18 - your Phorge configuration files.
19
20This document discusses approaches for backing up this data.
21
22If you are migrating from one machine to another, you can generally follow the
23same steps you would if you were creating a backup and then restoring it, you
24will just backup the old machine and then restore the data onto the new
25machine.
26
27WARNING: You need to restart Phorge after restoring data.
28
29Restarting Phorge after performing a restore makes sure that caches are
30flushed properly. For complete instructions, see
31@{article:Restarting Phorge}.
32
33
34Backup: MySQL Databases
35=======================
36
37Most of Phorge's data is stored in MySQL, and it's the most important thing
38to back up. You can run `bin/storage dump` to get a dump of all the MySQL
39databases. This is a convenience script which just runs a normal `mysqldump`,
40but will only dump databases Phorge owns.
41
42Since most of this data is compressible, it may be helpful to run it through
43gzip prior to storage. For example:
44
45 phorge/ $ ./bin/storage dump --compress --output backup.sql.gz
46
47Then store the backup somewhere safe, like in a box buried under an old tree
48stump. No one will ever think to look for it there.
49
50Restore: MySQL
51==============
52
53To restore a MySQL dump, just pipe it to `mysql` on a clean host. (You may need
54to uncompress it first, if you compressed it prior to storage.)
55
56 $ gunzip -c backup.sql.gz | mysql
57
58
59Backup: Hosted Repositories
60===========================
61
62If you host repositories in Phorge, you should back them up. You can use
63`bin/repository list-paths` to show the local paths on disk for each
64repository. To back them up, copy them elsewhere.
65
66You can also just clone them and keep the clones up to date, or use
67{nav Add Mirror} to have them mirror somewhere automatically.
68
69
70Restore: Hosted Repositories
71============================
72
73To restore hosted repositories, copy them back into the correct locations
74as shown by `bin/repository list-paths`.
75
76
77Backup: Uploaded Files
78======================
79
80Uploaded files may be stored in several different locations. The backup
81procedure depends on where files are stored:
82
83**Default / MySQL**: Under the default configuration, uploaded files are stored
84in MySQL, so the MySQL backup will include all files. In this case, you don't
85need to do any additional work.
86
87**Amazon S3**: If you use Amazon S3, redundancy and backups are built in to the
88service. This is probably sufficient for most installs. If you trust Amazon with
89your data //except not really//, you can backup your S3 bucket outside of
90Phorge.
91
92**Local Disk**: If you use the local disk storage engine, you'll need to back up
93files manually. You can do this by creating a copy of the root directory where
94you told Phorge to put files (the `storage.local-disk.path` configuration
95setting).
96
97For more information about configuring how files are stored, see
98@{article:Configuring File Storage}.
99
100
101Restore: Uploaded Files
102=======================
103
104To restore a backup of local disk storage, just copy the backup into place.
105
106
107Backup: Configuration Files
108===========================
109
110You should also backup your configuration files, and any scripts you use to
111deploy or administrate Phorge (like a customized upgrade script). The best
112way to do this is to check them into a private repository somewhere and just use
113whatever backup process you already have in place for repositories. Just copying
114them somewhere will work fine too, of course.
115
116In particular, you should backup this configuration file which Phorge
117creates:
118
119 phorge/conf/local/local.json
120
121This file contains all of the configuration settings that have been adjusted
122by using `bin/config set <key> <value>`.
123
124
125Restore: Configuration Files
126============================
127
128To restore configuration files, just copy them into the right locations. Copy
129your backup of `local.json` to `phorge/conf/local/local.json`.
130
131Security
132========
133
134MySQL dumps have no builtin encryption and most data in Phorge is stored in
135a raw, accessible form, so giving a user access to backups is a lot like giving
136them shell access to the machine Phorge runs on. In particular, a user who
137has the backups can:
138
139 - read data that policies do not permit them to see;
140 - read email addresses and object secret keys; and
141 - read other users' session and conduit tokens and impersonate them.
142
143Some of this information is durable, so disclosure of even a very old backup may
144present a risk. If you restrict access to the Phorge host or database, you
145should also restrict access to the backups.
146
147
148Skipping Indexes
149================
150
151By default, `bin/storage dump` does not dump all of the data in the database:
152it skips some caches which can be rebuilt automatically and do not need to be
153backed up. Some of these caches are very large, so the size of the dump may
154be significantly smaller than the size of the databases.
155
156If you have a large amount of data, you can specify `--no-indexes` when taking
157a database dump to skip additional tables which contain search indexes. This
158will reduce the size (and increase the speed) of the backup. This is an
159advanced option which most installs will not benefit from.
160
161This index data can be rebuilt after a restore, but will not be rebuilt
162automatically. If you choose to use this flag, you must manually rebuild
163indexes after a restore (for details, see ((reindex))).
164
165
166Next Steps
167==========
168
169Continue by:
170
171 - returning to the @{article:Configuration Guide}.