From 70351227535b3c0f636370864947ae1c8783e0b1 Mon Sep 17 00:00:00 2001
From: John McGehee <gitlab@johnnado.com>
Date: Wed, 20 Apr 2016 23:11:54 +0000
Subject: Emphasize that GitLab must be partially running when restoring
 backups.

This caused me a lot of pain until I caught on.
I also enhanced the GitLab Omnibus application data backup restore procedure.  I verified the procedure by executing it with GitLab 8.6.4.
---
 doc/raketasks/backup_restore.md | 35 ++++++++++++++++++++++++-----------
 1 file changed, 24 insertions(+), 11 deletions(-)

diff --git a/doc/raketasks/backup_restore.md b/doc/raketasks/backup_restore.md
index 4329ac30a1c..fa976134341 100644
--- a/doc/raketasks/backup_restore.md
+++ b/doc/raketasks/backup_restore.md
@@ -295,36 +295,49 @@ Deleting tmp directories...[DONE]
 
 ### Omnibus installations
 
-We will assume that you have installed GitLab from an omnibus package and run
-`sudo gitlab-ctl reconfigure` at least once.
+This procedure assumes that:
 
-First make sure your backup tar file is in `/var/opt/gitlab/backups` (or wherever `gitlab_rails['backup_path']` points to).
+- You have installed the exact same version of GitLab Omnibus with which the
+  backup was created
+- You have run `sudo gitlab-ctl reconfigure` at least once
+- GitLab is running.  If not, start it using `sudo gitlab-ctl start`.
+
+First make sure your backup tar file is in the backup directory described in the
+`gitlab.rb` configuration `gitlab_rails['backup_path']`. The default is
+`/var/opt/gitlab/backups`.
 
 ```shell
 sudo cp 1393513186_gitlab_backup.tar /var/opt/gitlab/backups/
 ```
 
-Next, restore the backup by running the restore command. You need to specify the
-timestamp of the backup you are restoring.
+Stop the processes that are connected to the database.  Leave the rest of GitLab
+running:
 
 ```shell
-# Stop processes that are connected to the database
 sudo gitlab-ctl stop unicorn
 sudo gitlab-ctl stop sidekiq
+# Verify
+sudo gitlab-ctl status
+```
 
+Next, restore the backup, specifying the timestamp of the backup you wish to
+restore:
+
+```shell
 # This command will overwrite the contents of your GitLab database!
 sudo gitlab-rake gitlab:backup:restore BACKUP=1393513186
+```
 
-# Start GitLab
-sudo gitlab-ctl start
+Restart and check GitLab:
 
-# Check GitLab
+```shell
+sudo gitlab-ctl start
 sudo gitlab-rake gitlab:check SANITIZE=true
 ```
 
 If there is a GitLab version mismatch between your backup tar file and the installed
-version of GitLab, the restore command will abort with an error. Install a package for
-the [required version](https://www.gitlab.com/downloads/archives/) and try again.
+version of GitLab, the restore command will abort with an error. Install the
+[correct GitLab version](https://www.gitlab.com/downloads/archives/) and try again.
 
 ## Configure cron to make daily backups
 
-- 
cgit v1.2.1