Rebase and resolve conflicts in backup doc for !3761

1 files changed, 34 insertions, 23 deletions

diff --git a/doc/raketasks/backup_restore.md b/doc/raketasks/backup_restore.md
index 3f4056dc440..faa7e9eaa44 100644
--- a/doc/raketasks/backup_restore.md
+++ b/doc/raketasks/backup_restore.md
@@ -2,34 +2,45 @@
 
 ![backup banner](backup_hrz.png)
 
-## Create a backup of the GitLab system
-
-A backup creates an archive file that contains the database, all repositories and all attachments.
-This archive will be saved in backup_path (see `config/gitlab.yml`).
-The filename will be `[TIMESTAMP]_gitlab_backup.tar`. This timestamp can be used to restore an specific backup.
-You can only restore a backup to exactly the same version of GitLab that you created it
-on, for example 7.2.1. The best way to migrate your repositories from one server to
+An application data backup creates an archive file that contains the database,
+all repositories and all attachments.
+This archive will be saved in `backup_path`, which is specified in the
+`config/gitlab.yml` file.
+The filename will be `[TIMESTAMP]_gitlab_backup.tar`, where `TIMESTAMP`
+identifies the time at which each backup was created.
+
+You can only restore a backup to exactly the same version of GitLab on which it
+was created.  The best way to migrate your repositories from one server to
 another is through backup restore.
 
-You need to keep separate copies of `/etc/gitlab/gitlab-secrets.json` and
-`/etc/gitlab/gitlab.rb` (for omnibus packages) or
-`/home/git/gitlab/config/secrets.yml` (for installations from source). This file
-contains the database encryption keys used for two-factor authentication and CI
-secret variables, among other things. If you restore a GitLab backup without
-restoring the database encryption key, users who have two-factor authentication
-enabled will lose access to your GitLab server.
+To restore a backup, you will also need to restore `/etc/gitlab/gitlab-secrets.json`
+(for omnibus packages) or `/home/git/gitlab/.secret` (for installations
+from source). This file contains the database encryption key used
+for two-factor authentication. If you fail to restore this encryption key file
+along with the application data backup, users with two-factor
+authentication enabled will lose access to your GitLab server.
+
+## Create a backup of the GitLab system
 
+Use this command if you've installed GitLab with the Omnibus package:
 ```
-# use this command if you've installed GitLab with the Omnibus package
 sudo gitlab-rake gitlab:backup:create
-
-# if you've installed GitLab from source
+```
+Use this if you've installed GitLab from source:
+```
 sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production
 ```
 
-Also you can choose what should be backed up by adding environment variable SKIP. Available options: db,
-uploads (attachments), repositories, builds(CI build output logs), artifacts (CI build artifacts), lfs (LFS objects).
-Use a comma to specify several options at the same time.
+You can specify that portions of the application data be skipped using the
+environment variable `SKIP`.  You can skip:
+- `db`
+- `uploads` (attachments)
+- `repositories`
+- `builds` (CI build output logs)
+- `artifacts` (CI build artifacts)
+- `lfs` (LFS objects)
+
+Separate multiple data types to skip using a comma.  For example:
 
 ```
 sudo gitlab-rake gitlab:backup:create SKIP=db,uploads
@@ -69,7 +80,7 @@ Deleting old backups... [SKIPPING]
 Starting with GitLab 7.4 you can let the backup script upload the '.tar' file it creates.
 It uses the [Fog library](http://fog.io/) to perform the upload.
 In the example below we use Amazon S3 for storage.
-But Fog also lets you use [other storage providers](http://fog.io/storage/).
+Fog also supports [other storage providers](http://fog.io/storage/).
 
 For omnibus packages:
 
@@ -161,7 +172,7 @@ with the name of your bucket:
 ### Uploading to locally mounted shares
 
 You may also send backups to a mounted share (`NFS` / `CIFS` / `SMB` / etc.) by
-using the [`Local`](https://github.com/fog/fog-local#usage) storage provider.
+using the Fog [`Local`](https://github.com/fog/fog-local#usage) storage provider.
 The directory pointed to by the `local_root` key **must** be owned by the `git`
 user **when mounted** (mounting with the `uid=` of the `git` user for `CIFS` and
 `SMB`) or the user that you are executing the backup tasks under (for omnibus
@@ -228,7 +239,7 @@ of using encryption in the first place!
 
 If you use an Omnibus package please see the [instructions in the readme to backup your configuration](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/README.md#backup-and-restore-omnibus-gitlab-configuration).
 If you have a cookbook installation there should be a copy of your configuration in Chef.
-If you have an installation from source, please consider backing up your `config/secrets.yml` file, `gitlab.yml` file, any SSL keys and certificates, and your [SSH host keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079).
+If you installed from source, please consider backing up your `config/secrets.yml` file, `gitlab.yml` file, any SSL keys and certificates, and your [SSH host keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079).
 
 At the very **minimum** you should backup `/etc/gitlab/gitlab.rb` and
 `/etc/gitlab/gitlab-secrets.json` (Omnibus), or