From 13d3bd81a68cc73c597a9a920deb94ed1e79d048 Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axilleas@axilleas.me>
Date: Wed, 21 Sep 2016 13:01:48 +0200
Subject: Change location and refactor issue closing pattern documentation

Split into user and administrator docs:

- administration/issue_closing_pattern.md
- user/project/issues/automatic_issue_closing.md

[ci skip]
---
 doc/administration/issue_closing_pattern.md | 49 +++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)
 create mode 100644 doc/administration/issue_closing_pattern.md

(limited to 'doc/administration')

diff --git a/doc/administration/issue_closing_pattern.md b/doc/administration/issue_closing_pattern.md
new file mode 100644
index 00000000000..28e1fd4e12e
--- /dev/null
+++ b/doc/administration/issue_closing_pattern.md
@@ -0,0 +1,49 @@
+# Issue closing pattern
+
+>**Note:**
+This is the administration documentation.
+There is a separate [user documentation] on issue closing pattern.
+
+When a commit or merge request resolves one or more issues, it is possible to
+automatically have these issues closed when the commit or merge request lands
+in the project's default branch.
+
+## Change the issue closing pattern
+
+In order to change the pattern you need to have access to the server that GitLab
+is installed on.
+
+The default pattern can be located in [gitlab.yml.example] under the
+"Automatic issue closing" section.
+
+> **Tip:**
+You are advised to use http://rubular.com to test the issue closing pattern.
+Because Rubular doesn't understand `%{issue_ref}`, you can replace this by
+`#\d+` when testing your patterns, which matches only local issue references like `#123`.
+
+**For Omnibus installations**
+
+1. Open `/etc/gitlab/gitlab.rb` with your editor.
+1. Change the value of `gitlab_rails['issue_closing_pattern']` to a regular
+   expression of your liking:
+
+    ```ruby
+    gitlab_rails['issue_closing_pattern'] = "((?:[Cc]los(?:e[sd]|ing)|[Ff]ix(?:e[sd]|ing)?) +(?:(?:issues? +)?%{issue_ref}(?:(?:, *| +and +)?))+)"
+    ```
+1. [Reconfigure] GitLab for the changes to take effect.
+
+**For installations from source**
+
+1. Open `gitlab.yml` with your editor.
+1. Change the value of `issue_closing_pattern`:
+
+    ```yaml
+    issue_closing_pattern: "((?:[Cc]los(?:e[sd]|ing)|[Ff]ix(?:e[sd]|ing)?) +(?:(?:issues? +)?%{issue_ref}(?:(?:, *| +and +)?))+)"
+    ```
+
+1. [Restart] GitLab for the changes to take effect.
+
+[gitlab.yml.example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/gitlab.yml.example
+[reconfigure]: restart_gitlab.md#omnibus-gitlab-reconfigure
+[restart]: restart_gitlab.md#installations-from-source
+[user documentation]: ../user/project/issues/automatic_issue_closing.md
-- 
cgit v1.2.1


From ce77bc0bf0958578fd8f3aa7ea606154ae5346ab Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axilleas@axilleas.me>
Date: Sun, 25 Sep 2016 11:18:52 +0200
Subject: Move container_registry user docs to new location

[ci skip]
---
 doc/administration/container_registry.md | 9 +++++++++
 1 file changed, 9 insertions(+)

(limited to 'doc/administration')

diff --git a/doc/administration/container_registry.md b/doc/administration/container_registry.md
index c5611e2a121..c5ba777d093 100644
--- a/doc/administration/container_registry.md
+++ b/doc/administration/container_registry.md
@@ -2,6 +2,15 @@
 
 > [Introduced][ce-4040] in GitLab 8.8.
 
+---
+
+> **Note**
+Docker Registry manifest `v1` support was added in GitLab 8.9 to support Docker
+versions earlier than 1.10.
+>
+This document is about the admin guide. To learn how to use GitLab Container
+Registry [user documentation](../user/project/container_registry.md).
+
 With the Docker Container Registry integrated into GitLab, every project can
 have its own space to store its Docker images.
 
-- 
cgit v1.2.1


From dffd33252f029901e33883935b20f6b0368d819b Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axilleas@axilleas.me>
Date: Sun, 25 Sep 2016 11:55:14 +0200
Subject: Move reply by email docs to a new location

[ci skip]
---
 doc/administration/reply_by_email.md               | 302 +++++++++++++++++++
 doc/administration/reply_by_email_postfix_setup.md | 324 +++++++++++++++++++++
 doc/administration/restart_gitlab.md               |   2 +-
 3 files changed, 627 insertions(+), 1 deletion(-)
 create mode 100644 doc/administration/reply_by_email.md
 create mode 100644 doc/administration/reply_by_email_postfix_setup.md

(limited to 'doc/administration')

diff --git a/doc/administration/reply_by_email.md b/doc/administration/reply_by_email.md
new file mode 100644
index 00000000000..5a9a1582877
--- /dev/null
+++ b/doc/administration/reply_by_email.md
@@ -0,0 +1,302 @@
+# Reply by email
+
+GitLab can be set up to allow users to comment on issues and merge requests by
+replying to notification emails.
+
+## Requirement
+
+Reply by email requires an IMAP-enabled email account. GitLab allows you to use
+three strategies for this feature:
+- using email sub-addressing
+- using a dedicated email address
+- using a catch-all mailbox
+
+### Email sub-addressing
+
+**If your provider or server supports email sub-addressing, we recommend using it.**
+
+[Sub-addressing](https://en.wikipedia.org/wiki/Email_address#Sub-addressing) is
+a feature where any email to `user+some_arbitrary_tag@example.com` will end up
+in the mailbox for `user@example.com`, and is supported by providers such as
+Gmail, Google Apps, Yahoo! Mail, Outlook.com and iCloud, as well as the Postfix
+mail server which you can run on-premises.
+
+### Dedicated email address
+
+This solution is really simple to set up: you just have to create an email
+address dedicated to receive your users' replies to GitLab notifications.
+
+### Catch-all mailbox
+
+A [catch-all mailbox](https://en.wikipedia.org/wiki/Catch-all) for a domain will
+"catch all" the emails addressed to the domain that do not exist in the mail
+server.
+
+## How it works?
+
+### 1. GitLab sends a notification email
+
+When GitLab sends a notification and Reply by email is enabled, the `Reply-To`
+header is set to the address defined in your GitLab configuration, with the
+`%{key}` placeholder (if present) replaced by a specific "reply key". In
+addition, this "reply key" is also added to the `References` header.
+
+### 2. You reply to the notification email
+
+When you reply to the notification email, your email client will:
+
+- send the email to the `Reply-To` address it got from the notification email
+- set the `In-Reply-To` header to the value of the `Message-ID` header from the
+  notification email
+- set the `References` header to the value of the `Message-ID` plus the value of
+  the notification email's `References` header.
+
+### 3. GitLab receives your reply to the notification email
+
+When GitLab receives your reply, it will look for the "reply key" in the
+following headers, in this order:
+
+1. the `To` header
+1. the `References` header
+
+If it finds a reply key, it will be able to leave your reply as a comment on
+the entity the notification was about (issue, merge request, commit...).
+
+For more details about the `Message-ID`, `In-Reply-To`, and `References headers`,
+please consult [RFC 5322](https://tools.ietf.org/html/rfc5322#section-3.6.4).
+
+## Set it up
+
+If you want to use Gmail / Google Apps with Reply by email, make sure you have
+[IMAP access enabled](https://support.google.com/mail/troubleshooter/1668960?hl=en#ts=1665018)
+and [allowed less secure apps to access the account](https://support.google.com/accounts/answer/6010255).
+
+To set up a basic Postfix mail server with IMAP access on Ubuntu, follow
+[these instructions](./postfix.md).
+
+### Omnibus package installations
+
+1. Find the `incoming_email` section in `/etc/gitlab/gitlab.rb`, enable the
+  feature and fill in the details for your specific IMAP server and email account:
+
+    ```ruby
+    # Configuration for Postfix mail server, assumes mailbox incoming@gitlab.example.com
+    gitlab_rails['incoming_email_enabled'] = true
+
+    # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
+    # The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`).
+    gitlab_rails['incoming_email_address'] = "incoming+%{key}@gitlab.example.com"
+
+    # Email account username
+    # With third party providers, this is usually the full email address.
+    # With self-hosted email servers, this is usually the user part of the email address.
+    gitlab_rails['incoming_email_email'] = "incoming"
+    # Email account password
+    gitlab_rails['incoming_email_password'] = "[REDACTED]"
+
+    # IMAP server host
+    gitlab_rails['incoming_email_host'] = "gitlab.example.com"
+    # IMAP server port
+    gitlab_rails['incoming_email_port'] = 143
+    # Whether the IMAP server uses SSL
+    gitlab_rails['incoming_email_ssl'] = false
+    # Whether the IMAP server uses StartTLS
+    gitlab_rails['incoming_email_start_tls'] = false
+
+    # The mailbox where incoming mail will end up. Usually "inbox".
+    gitlab_rails['incoming_email_mailbox_name'] = "inbox"
+    ```
+
+    ```ruby
+    # Configuration for Gmail / Google Apps, assumes mailbox gitlab-incoming@gmail.com
+    gitlab_rails['incoming_email_enabled'] = true
+
+    # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
+    # The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`).
+    gitlab_rails['incoming_email_address'] = "gitlab-incoming+%{key}@gmail.com"
+
+    # Email account username
+    # With third party providers, this is usually the full email address.
+    # With self-hosted email servers, this is usually the user part of the email address.
+    gitlab_rails['incoming_email_email'] = "gitlab-incoming@gmail.com"
+    # Email account password
+    gitlab_rails['incoming_email_password'] = "[REDACTED]"
+
+    # IMAP server host
+    gitlab_rails['incoming_email_host'] = "imap.gmail.com"
+    # IMAP server port
+    gitlab_rails['incoming_email_port'] = 993
+    # Whether the IMAP server uses SSL
+    gitlab_rails['incoming_email_ssl'] = true
+    # Whether the IMAP server uses StartTLS
+    gitlab_rails['incoming_email_start_tls'] = false
+
+    # The mailbox where incoming mail will end up. Usually "inbox".
+    gitlab_rails['incoming_email_mailbox_name'] = "inbox"
+    ```
+
+1. Reconfigure GitLab and restart mailroom for the changes to take effect:
+
+    ```sh
+    sudo gitlab-ctl reconfigure
+    sudo gitlab-ctl restart mailroom
+    ```
+
+1. Verify that everything is configured correctly:
+
+    ```sh
+    sudo gitlab-rake gitlab:incoming_email:check
+    ```
+
+1. Reply by email should now be working.
+
+### Installations from source
+
+1. Go to the GitLab installation directory:
+
+    ```sh
+    cd /home/git/gitlab
+    ```
+
+1. Find the `incoming_email` section in `config/gitlab.yml`, enable the feature
+  and fill in the details for your specific IMAP server and email account:
+
+    ```sh
+    sudo editor config/gitlab.yml
+    ```
+
+    ```yaml
+    # Configuration for Postfix mail server, assumes mailbox incoming@gitlab.example.com
+    incoming_email:
+      enabled: true
+
+      # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
+      # The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`).
+      address: "incoming+%{key}@gitlab.example.com"
+
+      # Email account username
+      # With third party providers, this is usually the full email address.
+      # With self-hosted email servers, this is usually the user part of the email address.
+      user: "incoming"
+      # Email account password
+      password: "[REDACTED]"
+
+      # IMAP server host
+      host: "gitlab.example.com"
+      # IMAP server port
+      port: 143
+      # Whether the IMAP server uses SSL
+      ssl: false
+      # Whether the IMAP server uses StartTLS
+      start_tls: false
+
+      # The mailbox where incoming mail will end up. Usually "inbox".
+      mailbox: "inbox"
+    ```
+
+    ```yaml
+    # Configuration for Gmail / Google Apps, assumes mailbox gitlab-incoming@gmail.com
+    incoming_email:
+      enabled: true
+
+      # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
+      # The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`).
+      address: "gitlab-incoming+%{key}@gmail.com"
+
+      # Email account username
+      # With third party providers, this is usually the full email address.
+      # With self-hosted email servers, this is usually the user part of the email address.
+      user: "gitlab-incoming@gmail.com"
+      # Email account password
+      password: "[REDACTED]"
+
+      # IMAP server host
+      host: "imap.gmail.com"
+      # IMAP server port
+      port: 993
+      # Whether the IMAP server uses SSL
+      ssl: true
+      # Whether the IMAP server uses StartTLS
+      start_tls: false
+
+      # The mailbox where incoming mail will end up. Usually "inbox".
+      mailbox: "inbox"
+    ```
+
+1. Enable `mail_room` in the init script at `/etc/default/gitlab`:
+
+    ```sh
+    sudo mkdir -p /etc/default
+    echo 'mail_room_enabled=true' | sudo tee -a /etc/default/gitlab
+    ```
+
+1. Restart GitLab:
+
+    ```sh
+    sudo service gitlab restart
+    ```
+
+1. Verify that everything is configured correctly:
+
+    ```sh
+    sudo -u git -H bundle exec rake gitlab:incoming_email:check RAILS_ENV=production
+    ```
+
+1. Reply by email should now be working.
+
+### Development
+
+1. Go to the GitLab installation directory.
+
+1. Find the `incoming_email` section in `config/gitlab.yml`, enable the feature and fill in the details for your specific IMAP server and email account:
+
+    ```yaml
+    # Configuration for Gmail / Google Apps, assumes mailbox gitlab-incoming@gmail.com
+    incoming_email:
+      enabled: true
+
+      # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
+      # The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`).
+      address: "gitlab-incoming+%{key}@gmail.com"
+
+      # Email account username
+      # With third party providers, this is usually the full email address.
+      # With self-hosted email servers, this is usually the user part of the email address.
+      user: "gitlab-incoming@gmail.com"
+      # Email account password
+      password: "[REDACTED]"
+
+      # IMAP server host
+      host: "imap.gmail.com"
+      # IMAP server port
+      port: 993
+      # Whether the IMAP server uses SSL
+      ssl: true
+      # Whether the IMAP server uses StartTLS
+      start_tls: false
+
+      # The mailbox where incoming mail will end up. Usually "inbox".
+      mailbox: "inbox"
+    ```
+
+    As mentioned, the part after `+` is ignored, and this will end up in the mailbox for `gitlab-incoming@gmail.com`.
+
+1. Uncomment the `mail_room` line in your `Procfile`:
+
+    ```yaml
+    mail_room: bundle exec mail_room -q -c config/mail_room.yml
+    ```
+
+1. Restart GitLab:
+
+    ```sh
+    bundle exec foreman start
+    ```
+
+1. Verify that everything is configured correctly:
+
+    ```sh
+    bundle exec rake gitlab:incoming_email:check RAILS_ENV=development
+    ```
+
+1. Reply by email should now be working.
diff --git a/doc/administration/reply_by_email_postfix_setup.md b/doc/administration/reply_by_email_postfix_setup.md
new file mode 100644
index 00000000000..22f10489a6c
--- /dev/null
+++ b/doc/administration/reply_by_email_postfix_setup.md
@@ -0,0 +1,324 @@
+# Set up Postfix for Reply by email
+
+This document will take you through the steps of setting up a basic Postfix mail
+server with IMAP authentication on Ubuntu, to be used with [Reply by email].
+
+The instructions make the assumption that you will be using the email address `incoming@gitlab.example.com`, that is, username `incoming` on host `gitlab.example.com`. Don't forget to change it to your actual host when executing the example code snippets.
+
+## Configure your server firewall
+
+1. Open up port 25 on your server so that people can send email into the server over SMTP.
+2. If the mail server is different from the server running GitLab, open up port 143 on your server so that GitLab can read email from the server over IMAP.
+
+## Install packages
+
+1. Install the `postfix` package if it is not installed already:
+
+    ```sh
+    sudo apt-get install postfix
+    ```
+
+    When asked about the environment, select 'Internet Site'. When asked to confirm the hostname, make sure it matches `gitlab.example.com`.
+
+1. Install the `mailutils` package.
+
+    ```sh
+    sudo apt-get install mailutils
+    ```
+
+## Create user
+
+1. Create a user for incoming email.
+
+    ```sh
+    sudo useradd -m -s /bin/bash incoming
+    ```
+
+1. Set a password for this user.
+
+    ```sh
+    sudo passwd incoming
+    ```
+
+    Be sure not to forget this, you'll need it later.
+
+## Test the out-of-the-box setup
+
+1. Connect to the local SMTP server:
+
+    ```sh
+    telnet localhost 25
+    ```
+
+    You should see a prompt like this:
+
+    ```sh
+    Trying 127.0.0.1...
+    Connected to localhost.
+    Escape character is '^]'.
+    220 gitlab.example.com ESMTP Postfix (Ubuntu)
+    ```
+
+    If you get a `Connection refused` error instead, verify that `postfix` is running:
+
+    ```sh
+    sudo postfix status
+    ```
+
+    If it is not, start it:
+
+    ```sh
+    sudo postfix start
+    ```
+
+1. Send the new `incoming` user a dummy email to test SMTP, by entering the following into the SMTP prompt:
+
+    ```
+    ehlo localhost
+    mail from: root@localhost
+    rcpt to: incoming@localhost
+    data
+    Subject: Re: Some issue
+
+    Sounds good!
+    .
+    quit
+    ```
+
+    _**Note:** The `.` is a literal period on its own line._
+
+    _**Note:** If you receive an error after entering `rcpt to: incoming@localhost`
+    then your Postfix `my_network` configuration is not correct. The error will
+    say 'Temporary lookup failure'. See
+    [Configure Postfix to receive email from the Internet](#configure-postfix-to-receive-email-from-the-internet)._
+
+1. Check if the `incoming` user received the email:
+
+    ```sh
+    su - incoming
+    mail
+    ```
+
+    You should see output like this:
+
+    ```
+    "/var/mail/incoming": 1 message 1 unread
+    >U   1 root@localhost                           59/2842  Re: Some issue
+    ```
+
+    Quit the mail app:
+
+    ```sh
+    q
+    ```
+
+1. Log out of the `incoming` account and go back to being `root`:
+
+    ```sh
+    logout
+    ```
+
+## Configure Postfix to use Maildir-style mailboxes
+
+Courier, which we will install later to add IMAP authentication, requires mailboxes to have the Maildir format, rather than mbox.
+
+1. Configure Postfix to use Maildir-style mailboxes:
+
+    ```sh
+    sudo postconf -e "home_mailbox = Maildir/"
+    ```
+
+1. Restart Postfix:
+
+    ```sh
+    sudo /etc/init.d/postfix restart
+    ```
+
+1. Test the new setup:
+
+    1. Follow steps 1 and 2 of _[Test the out-of-the-box setup](#test-the-out-of-the-box-setup)_.
+    1. Check if the `incoming` user received the email:
+
+        ```sh
+        su - incoming
+        MAIL=/home/incoming/Maildir
+        mail
+        ```
+
+        You should see output like this:
+
+        ```
+        "/home/incoming/Maildir": 1 message 1 unread
+        >U   1 root@localhost                           59/2842  Re: Some issue
+        ```
+
+        Quit the mail app:
+
+        ```sh
+        q
+        ```
+
+    _**Note:** If `mail` returns an error `Maildir: Is a directory` then your
+    version of `mail` doesn't support Maildir style mailboxes. Install
+    `heirloom-mailx` by running `sudo apt-get install heirloom-mailx`. Then,
+    try the above steps again, substituting `heirloom-mailx` for the `mail`
+    command._
+
+1. Log out of the `incoming` account and go back to being `root`:
+
+    ```sh
+    logout
+    ```
+
+## Install the Courier IMAP server
+
+1. Install the `courier-imap` package:
+
+    ```sh
+    sudo apt-get install courier-imap
+    ```
+
+## Configure Postfix to receive email from the internet
+
+1. Let Postfix know about the domains that it should consider local:
+
+    ```sh
+    sudo postconf -e "mydestination = gitlab.example.com, localhost.localdomain, localhost"
+    ```
+
+1. Let Postfix know about the IPs that it should consider part of the LAN:
+
+    We'll assume `192.168.1.0/24` is your local LAN. You can safely skip this step if you don't have other machines in the same local network.
+
+    ```sh
+    sudo postconf -e "mynetworks = 127.0.0.0/8, 192.168.1.0/24"
+    ```
+
+1. Configure Postfix to receive mail on all interfaces, which includes the internet:
+
+    ```sh
+    sudo postconf -e "inet_interfaces = all"
+    ```
+
+1. Configure Postfix to use the `+` delimiter for sub-addressing:
+
+    ```sh
+    sudo postconf -e "recipient_delimiter = +"
+    ```
+
+1. Restart Postfix:
+
+    ```sh
+    sudo service postfix restart
+    ```
+
+## Test the final setup
+
+1. Test SMTP under the new setup:
+
+    1. Connect to the SMTP server:
+
+        ```sh
+        telnet gitlab.example.com 25
+        ```
+
+        You should see a prompt like this:
+
+        ```sh
+        Trying 123.123.123.123...
+        Connected to gitlab.example.com.
+        Escape character is '^]'.
+        220 gitlab.example.com ESMTP Postfix (Ubuntu)
+        ```
+
+        If you get a `Connection refused` error instead, make sure your firewall is setup to allow inbound traffic on port 25.
+
+    1. Send the `incoming` user a dummy email to test SMTP, by entering the following into the SMTP prompt:
+
+        ```
+        ehlo gitlab.example.com
+        mail from: root@gitlab.example.com
+        rcpt to: incoming@gitlab.example.com
+        data
+        Subject: Re: Some issue
+
+        Sounds good!
+        .
+        quit
+        ```
+
+        (Note: The `.` is a literal period on its own line)
+
+    1. Check if the `incoming` user received the email:
+
+        ```sh
+        su - incoming
+        MAIL=/home/incoming/Maildir
+        mail
+        ```
+
+        You should see output like this:
+
+        ```
+        "/home/incoming/Maildir": 1 message 1 unread
+        >U   1 root@gitlab.example.com                           59/2842  Re: Some issue
+        ```
+
+        Quit the mail app:
+
+        ```sh
+        q
+        ```
+
+    1. Log out of the `incoming` account and go back to being `root`:
+
+        ```sh
+        logout
+        ```
+
+1. Test IMAP under the new setup:
+
+    1. Connect to the IMAP server:
+
+        ```sh
+        telnet gitlab.example.com 143
+        ```
+
+        You should see a prompt like this:
+
+        ```sh
+        Trying 123.123.123.123...
+        Connected to mail.example.gitlab.com.
+        Escape character is '^]'.
+        - OK [CAPABILITY IMAP4rev1 UIDPLUS CHILDREN NAMESPACE THREAD=ORDEREDSUBJECT THREAD=REFERENCES SORT QUOTA IDLE ACL ACL2=UNION] Courier-IMAP ready. Copyright 1998-2011 Double Precision, Inc.  See COPYING for distribution information.
+        ```
+
+    1. Sign in as the `incoming` user to test IMAP, by entering the following into the IMAP prompt:
+
+        ```
+        a login incoming PASSWORD
+        ```
+
+        Replace PASSWORD with the password you set on the `incoming` user earlier.
+
+        You should see output like this:
+
+        ```
+        a OK LOGIN Ok.
+        ```
+
+    1. Disconnect from the IMAP server:
+
+        ```sh
+        a logout
+        ```
+
+## Done!
+
+If all the tests were successful, Postfix is all set up and ready to receive email! Continue with the [Reply by email](./README.md) guide to configure GitLab.
+
+---
+
+_This document was adapted from https://help.ubuntu.com/community/PostfixBasicSetupHowto, by contributors to the Ubuntu documentation wiki._
+
+[reply by email]: reply_by_email.md
diff --git a/doc/administration/restart_gitlab.md b/doc/administration/restart_gitlab.md
index 483060395dd..b561c2f82aa 100644
--- a/doc/administration/restart_gitlab.md
+++ b/doc/administration/restart_gitlab.md
@@ -139,7 +139,7 @@ If you are using other init systems, like systemd, you can check the
 
 [omnibus-dl]: https://about.gitlab.com/downloads/ "Download the Omnibus packages"
 [install]: ../install/installation.md "Documentation to install GitLab from source"
-[mailroom]: ../incoming_email/README.md "Used for replying by email in GitLab issues and merge requests"
+[mailroom]: reply_by_email.md "Used for replying by email in GitLab issues and merge requests"
 [chef]: https://www.chef.io/chef/ "Chef official website"
 [src-service]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/support/init.d/gitlab "GitLab init service file"
 [gl-recipes]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/init "GitLab Recipes repository"
-- 
cgit v1.2.1


From 6207dc9037601d5188c86876c2ff79d6ddbbe540 Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axilleas@axilleas.me>
Date: Sun, 25 Sep 2016 12:16:14 +0200
Subject: Move monitoring/ to new location

---
 doc/administration/monitoring/health_check.md      |  66 +++++++
 .../monitoring/img/health_check_token.png          | Bin 0 -> 6630 bytes
 .../monitoring/performance/gitlab_configuration.md |  40 +++++
 .../performance/grafana_configuration.md           | 111 ++++++++++++
 .../performance/img/grafana_dashboard_dropdown.png | Bin 0 -> 14368 bytes
 .../performance/img/grafana_dashboard_import.png   | Bin 0 -> 18267 bytes
 .../img/grafana_data_source_configuration.png      | Bin 0 -> 26060 bytes
 .../performance/img/grafana_data_source_empty.png  | Bin 0 -> 21821 bytes
 .../performance/img/grafana_save_icon.png          | Bin 0 -> 9107 bytes
 .../img/metrics_gitlab_configuration_settings.png  | Bin 0 -> 61357 bytes
 .../performance/influxdb_configuration.md          | 193 +++++++++++++++++++++
 .../monitoring/performance/influxdb_schema.md      |  97 +++++++++++
 .../monitoring/performance/introduction.md         |  65 +++++++
 13 files changed, 572 insertions(+)
 create mode 100644 doc/administration/monitoring/health_check.md
 create mode 100644 doc/administration/monitoring/img/health_check_token.png
 create mode 100644 doc/administration/monitoring/performance/gitlab_configuration.md
 create mode 100644 doc/administration/monitoring/performance/grafana_configuration.md
 create mode 100644 doc/administration/monitoring/performance/img/grafana_dashboard_dropdown.png
 create mode 100644 doc/administration/monitoring/performance/img/grafana_dashboard_import.png
 create mode 100644 doc/administration/monitoring/performance/img/grafana_data_source_configuration.png
 create mode 100644 doc/administration/monitoring/performance/img/grafana_data_source_empty.png
 create mode 100644 doc/administration/monitoring/performance/img/grafana_save_icon.png
 create mode 100644 doc/administration/monitoring/performance/img/metrics_gitlab_configuration_settings.png
 create mode 100644 doc/administration/monitoring/performance/influxdb_configuration.md
 create mode 100644 doc/administration/monitoring/performance/influxdb_schema.md
 create mode 100644 doc/administration/monitoring/performance/introduction.md

(limited to 'doc/administration')

diff --git a/doc/administration/monitoring/health_check.md b/doc/administration/monitoring/health_check.md
new file mode 100644
index 00000000000..eac57bc3de4
--- /dev/null
+++ b/doc/administration/monitoring/health_check.md
@@ -0,0 +1,66 @@
+# Health Check
+
+> [Introduced][ce-3888] in GitLab 8.8.
+
+GitLab provides a health check endpoint for uptime monitoring on the `health_check` web
+endpoint. The health check reports on the overall system status based on the status of
+the database connection, the state of the database migrations, and the ability to write
+and access the cache. This endpoint can be provided to uptime monitoring services like
+[Pingdom][pingdom], [Nagios][nagios-health], and [NewRelic][newrelic-health].
+
+## Access Token
+
+An access token needs to be provided while accessing the health check endpoint. The current
+accepted token can be found on the `admin/health_check` page of your GitLab instance.
+
+![access token](img/health_check_token.png)
+
+The access token can be passed as a URL parameter:
+
+```
+https://gitlab.example.com/health_check.json?token=ACCESS_TOKEN
+```
+
+or as an HTTP header:
+
+```bash
+curl --header "TOKEN: ACCESS_TOKEN" https://gitlab.example.com/health_check.json
+```
+
+## Using the Endpoint
+
+Once you have the access token, health information can be retrieved as plain text, JSON,
+or XML using the `health_check` endpoint:
+
+- `https://gitlab.example.com/health_check?token=ACCESS_TOKEN`
+- `https://gitlab.example.com/health_check.json?token=ACCESS_TOKEN`
+- `https://gitlab.example.com/health_check.xml?token=ACCESS_TOKEN`
+
+You can also ask for the status of specific services:
+
+- `https://gitlab.example.com/health_check/cache.json?token=ACCESS_TOKEN`
+- `https://gitlab.example.com/health_check/database.json?token=ACCESS_TOKEN`
+- `https://gitlab.example.com/health_check/migrations.json?token=ACCESS_TOKEN`
+
+For example, the JSON output of the following health check:
+
+```bash
+curl --header "TOKEN: ACCESS_TOKEN" https://gitlab.example.com/health_check.json
+```
+
+would be like:
+
+```
+{"healthy":true,"message":"success"}
+```
+
+## Status
+
+On failure, the endpoint will return a `500` HTTP status code. On success, the endpoint
+will return a valid successful HTTP status code, and a `success` message. Ideally your
+uptime monitoring should look for the success message.
+
+[ce-3888]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3888
+[pingdom]: https://www.pingdom.com
+[nagios-health]: https://nagios-plugins.org/doc/man/check_http.html
+[newrelic-health]: https://docs.newrelic.com/docs/alerts/alert-policies/downtime-alerts/availability-monitoring
diff --git a/doc/administration/monitoring/img/health_check_token.png b/doc/administration/monitoring/img/health_check_token.png
new file mode 100644
index 00000000000..2d7c82a65a8
Binary files /dev/null and b/doc/administration/monitoring/img/health_check_token.png differ
diff --git a/doc/administration/monitoring/performance/gitlab_configuration.md b/doc/administration/monitoring/performance/gitlab_configuration.md
new file mode 100644
index 00000000000..771584268d9
--- /dev/null
+++ b/doc/administration/monitoring/performance/gitlab_configuration.md
@@ -0,0 +1,40 @@
+# GitLab Configuration
+
+GitLab Performance Monitoring is disabled by default. To enable it and change any of its
+settings, navigate to the Admin area in **Settings > Metrics**
+(`/admin/application_settings`).
+
+The minimum required settings you need to set are the InfluxDB host and port.
+Make sure _Enable InfluxDB Metrics_ is checked and hit **Save** to save the
+changes.
+
+---
+
+![GitLab Performance Monitoring Admin Settings](img/metrics_gitlab_configuration_settings.png)
+
+---
+
+Finally, a restart of all GitLab processes is required for the changes to take
+effect:
+
+```bash
+# For Omnibus installations
+sudo gitlab-ctl restart
+
+# For installations from source
+sudo service gitlab restart
+```
+
+## Pending Migrations
+
+When any migrations are pending, the metrics are disabled until the migrations
+have been performed.
+
+---
+
+Read more on:
+
+- [Introduction to GitLab Performance Monitoring](introduction.md)
+- [InfluxDB Configuration](influxdb_configuration.md)
+- [InfluxDB Schema](influxdb_schema.md)
+- [Grafana Install/Configuration](grafana_configuration.md)
diff --git a/doc/administration/monitoring/performance/grafana_configuration.md b/doc/administration/monitoring/performance/grafana_configuration.md
new file mode 100644
index 00000000000..7947b0fedc4
--- /dev/null
+++ b/doc/administration/monitoring/performance/grafana_configuration.md
@@ -0,0 +1,111 @@
+# Grafana Configuration
+
+[Grafana](http://grafana.org/) is a tool that allows you to visualize time
+series metrics through graphs and dashboards. It supports several backend
+data stores, including InfluxDB. GitLab writes performance data to InfluxDB
+and Grafana will allow you to query InfluxDB to display useful graphs.
+
+For the easiest installation and configuration, install Grafana on the same
+server as InfluxDB. For larger installations, you may want to split out these
+services.
+
+## Installation
+
+Grafana supplies package repositories (Yum/Apt) for easy installation.
+See [Grafana installation documentation](http://docs.grafana.org/installation/)
+for detailed steps.
+
+> **Note**: Before starting Grafana for the first time, set the admin user
+and password in `/etc/grafana/grafana.ini`. Otherwise, the default password
+will be `admin`.
+
+## Configuration
+
+Login as the admin user. Expand the menu by clicking the Grafana logo in the
+top left corner. Choose 'Data Sources' from the menu. Then, click 'Add new'
+in the top bar.
+
+![Grafana empty data source page](img/grafana_data_source_empty.png)
+
+Fill in the configuration details for the InfluxDB data source. Save and
+Test Connection to ensure the configuration is correct.
+
+- **Name**: InfluxDB
+- **Default**: Checked
+- **Type**: InfluxDB 0.9.x (Even if you're using InfluxDB 0.10.x)
+- **Url**: https://localhost:8086 (Or the remote URL if you've installed InfluxDB
+on a separate server)
+- **Access**: proxy
+- **Database**: gitlab
+- **User**: admin (Or the username configured when setting up InfluxDB)
+- **Password**: The password configured when you set up InfluxDB
+
+![Grafana data source configurations](img/grafana_data_source_configuration.png)
+
+## Apply retention policies and create continuous queries
+
+If you intend to import the GitLab provided Grafana dashboards, you will need to
+set up the right retention policies and continuous queries. The easiest way of
+doing this is by using the [influxdb-management](https://gitlab.com/gitlab-org/influxdb-management)
+repository.
+
+To use this repository you must first clone it:
+
+```
+git clone https://gitlab.com/gitlab-org/influxdb-management.git
+cd influxdb-management
+```
+
+Next you must install the required dependencies:
+
+```
+gem install bundler
+bundle install
+```
+
+Now you must configure the repository by first copying `.env.example` to `.env`
+and then editing the `.env` file to contain the correct InfluxDB settings. Once
+configured you can simply run `bundle exec rake` and the InfluxDB database will
+be configured for you.
+
+For more information see the [influxdb-management README](https://gitlab.com/gitlab-org/influxdb-management/blob/master/README.md).
+
+## Import Dashboards
+
+You can now import a set of default dashboards that will give you a good
+start on displaying useful information. GitLab has published a set of default
+[Grafana dashboards][grafana-dashboards] to get you started. Clone the
+repository or download a zip/tarball, then follow these steps to import each
+JSON file.
+
+Open the dashboard dropdown menu and click 'Import'
+
+![Grafana dashboard dropdown](img/grafana_dashboard_dropdown.png)
+
+Click 'Choose file' and browse to the location where you downloaded or cloned
+the dashboard repository. Pick one of the JSON files to import.
+
+![Grafana dashboard import](img/grafana_dashboard_import.png)
+
+Once the dashboard is imported, be sure to click save icon in the top bar. If
+you do not save the dashboard after importing it will be removed when you
+navigate away.
+
+![Grafana save icon](img/grafana_save_icon.png)
+
+Repeat this process for each dashboard you wish to import.
+
+Alternatively you can automatically import all the dashboards into your Grafana
+instance. See the README of the [Grafana dashboards][grafana-dashboards]
+repository for more information on this process.
+
+[grafana-dashboards]: https://gitlab.com/gitlab-org/grafana-dashboards
+
+---
+
+Read more on:
+
+- [Introduction to GitLab Performance Monitoring](introduction.md)
+- [GitLab Configuration](gitlab_configuration.md)
+- [InfluxDB Installation/Configuration](influxdb_configuration.md)
+- [InfluxDB Schema](influxdb_schema.md)
diff --git a/doc/administration/monitoring/performance/img/grafana_dashboard_dropdown.png b/doc/administration/monitoring/performance/img/grafana_dashboard_dropdown.png
new file mode 100644
index 00000000000..7e34fad71ce
Binary files /dev/null and b/doc/administration/monitoring/performance/img/grafana_dashboard_dropdown.png differ
diff --git a/doc/administration/monitoring/performance/img/grafana_dashboard_import.png b/doc/administration/monitoring/performance/img/grafana_dashboard_import.png
new file mode 100644
index 00000000000..f97624365c7
Binary files /dev/null and b/doc/administration/monitoring/performance/img/grafana_dashboard_import.png differ
diff --git a/doc/administration/monitoring/performance/img/grafana_data_source_configuration.png b/doc/administration/monitoring/performance/img/grafana_data_source_configuration.png
new file mode 100644
index 00000000000..7d50e4c88c2
Binary files /dev/null and b/doc/administration/monitoring/performance/img/grafana_data_source_configuration.png differ
diff --git a/doc/administration/monitoring/performance/img/grafana_data_source_empty.png b/doc/administration/monitoring/performance/img/grafana_data_source_empty.png
new file mode 100644
index 00000000000..aa39a53acae
Binary files /dev/null and b/doc/administration/monitoring/performance/img/grafana_data_source_empty.png differ
diff --git a/doc/administration/monitoring/performance/img/grafana_save_icon.png b/doc/administration/monitoring/performance/img/grafana_save_icon.png
new file mode 100644
index 00000000000..c740e33cd1c
Binary files /dev/null and b/doc/administration/monitoring/performance/img/grafana_save_icon.png differ
diff --git a/doc/administration/monitoring/performance/img/metrics_gitlab_configuration_settings.png b/doc/administration/monitoring/performance/img/metrics_gitlab_configuration_settings.png
new file mode 100644
index 00000000000..db396423e30
Binary files /dev/null and b/doc/administration/monitoring/performance/img/metrics_gitlab_configuration_settings.png differ
diff --git a/doc/administration/monitoring/performance/influxdb_configuration.md b/doc/administration/monitoring/performance/influxdb_configuration.md
new file mode 100644
index 00000000000..c30cd2950d8
--- /dev/null
+++ b/doc/administration/monitoring/performance/influxdb_configuration.md
@@ -0,0 +1,193 @@
+# InfluxDB Configuration
+
+The default settings provided by [InfluxDB] are not sufficient for a high traffic
+GitLab environment. The settings discussed in this document are based on the
+settings GitLab uses for GitLab.com, depending on your own needs you may need to
+further adjust them.
+
+If you are intending to run InfluxDB on the same server as GitLab, make sure
+you have plenty of RAM since InfluxDB can use quite a bit depending on traffic.
+
+Unless you are going with a budget setup, it's advised to run it separately.
+
+## Requirements
+
+- InfluxDB 0.9.5 or newer
+- A fairly modern version of Linux
+- At least 4GB of RAM
+- At least 10GB of storage for InfluxDB data
+
+Note that the RAM and storage requirements can differ greatly depending on the
+amount of data received/stored. To limit the amount of stored data users can
+look into [InfluxDB Retention Policies][influxdb-retention].
+
+## Installation
+
+Installing InfluxDB is out of the scope of this document. Please refer to the
+[InfluxDB documentation].
+
+## InfluxDB Server Settings
+
+Since InfluxDB has many settings that users may wish to customize themselves
+(e.g. what port to run InfluxDB on), we'll only cover the essentials.
+
+The configuration file in question is usually located at
+`/etc/influxdb/influxdb.conf`. Whenever you make a change in this file,
+InfluxDB needs to be restarted.
+
+### Storage Engine
+
+InfluxDB comes with different storage engines and as of InfluxDB 0.9.5 a new
+storage engine is available, called [TSM Tree]. All users **must** use the new
+`tsm1` storage engine as this [will be the default engine][tsm1-commit] in
+upcoming InfluxDB releases.
+
+Make sure you have the following in your configuration file:
+
+```
+[data]
+  dir = "/var/lib/influxdb/data"
+  engine = "tsm1"
+```
+
+### Admin Panel
+
+Production environments should have the InfluxDB admin panel **disabled**. This
+feature can be disabled by adding the following to your InfluxDB configuration
+file:
+
+```
+[admin]
+  enabled = false
+```
+
+### HTTP
+
+HTTP is required when using the [InfluxDB CLI] or other tools such as Grafana,
+thus it should be enabled. When enabling make sure to _also_ enable
+authentication:
+
+```
+[http]
+  enabled = true
+  auth-enabled = true
+```
+
+_**Note:** Before you enable authentication, you might want to [create an
+admin user](#create-a-new-admin-user)._
+
+### UDP
+
+GitLab writes data to InfluxDB via UDP and thus this must be enabled. Enabling
+UDP can be done using the following settings:
+
+```
+[[udp]]
+  enabled = true
+  bind-address = ":8089"
+  database = "gitlab"
+  batch-size = 1000
+  batch-pending = 5
+  batch-timeout = "1s"
+  read-buffer = 209715200
+```
+
+This does the following:
+
+1. Enable UDP and bind it to port 8089 for all addresses.
+2. Store any data received in the "gitlab" database.
+3. Define a batch of points to be 1000 points in size and allow a maximum of
+   5 batches _or_ flush them automatically after 1 second.
+4. Define a UDP read buffer size of 200 MB.
+
+One of the most important settings here is the UDP read buffer size as if this
+value is set too low, packets will be dropped. You must also make sure the OS
+buffer size is set to the same value, the default value is almost never enough.
+
+To set the OS buffer size to 200 MB, on Linux you can run the following command:
+
+```bash
+sysctl -w net.core.rmem_max=209715200
+```
+
+To make this permanent, add the following to `/etc/sysctl.conf` and restart the
+server:
+
+```bash
+net.core.rmem_max=209715200
+```
+
+It is **very important** to make sure the buffer sizes are large enough to
+handle all data sent to InfluxDB as otherwise you _will_ lose data. The above
+buffer sizes are based on the traffic for GitLab.com. Depending on the amount of
+traffic, users may be able to use a smaller buffer size, but we highly recommend
+using _at least_ 100 MB.
+
+When enabling UDP, users should take care to not expose the port to the public,
+as doing so will allow anybody to write data into your InfluxDB database (as
+[InfluxDB's UDP protocol][udp] doesn't support authentication). We recommend either
+whitelisting the allowed IP addresses/ranges, or setting up a VLAN and only
+allowing traffic from members of said VLAN.
+
+## Create a new admin user
+
+If you want to [enable authentication](#http), you might want to [create an
+admin user][influx-admin]:
+
+```
+influx -execute "CREATE USER jeff WITH PASSWORD '1234' WITH ALL PRIVILEGES"
+```
+
+## Create the `gitlab` database
+
+Once you get InfluxDB up and running, you need to create a database for GitLab.
+Make sure you have changed the [storage engine](#storage-engine) to `tsm1`
+before creating a database.
+
+_**Note:** If you [created an admin user](#create-a-new-admin-user) and enabled
+[HTTP authentication](#http), remember to append the username (`-username <username>`)
+and password (`-password <password>`)  you set earlier to the commands below._
+
+Run the following command to create a database named `gitlab`:
+
+```bash
+influx -execute 'CREATE DATABASE gitlab'
+```
+
+The name **must** be `gitlab`, do not use any other name.
+
+Next, make sure that the database was successfully created:
+
+```bash
+influx -execute 'SHOW DATABASES'
+```
+
+The output should be similar to:
+
+```
+name: databases
+---------------
+name
+_internal
+gitlab
+```
+
+That's it! Now your GitLab instance should send data to InfluxDB.
+
+---
+
+Read more on:
+
+- [Introduction to GitLab Performance Monitoring](introduction.md)
+- [GitLab Configuration](gitlab_configuration.md)
+- [InfluxDB Schema](influxdb_schema.md)
+- [Grafana Install/Configuration](grafana_configuration.md)
+
+[influxdb-retention]: https://docs.influxdata.com/influxdb/v0.9/query_language/database_management/#retention-policy-management
+[influxdb documentation]: https://docs.influxdata.com/influxdb/v0.9/
+[influxdb cli]: https://docs.influxdata.com/influxdb/v0.9/tools/shell/
+[udp]: https://docs.influxdata.com/influxdb/v0.9/write_protocols/udp/
+[influxdb]: https://influxdata.com/time-series-platform/influxdb/
+[tsm tree]: https://influxdata.com/blog/new-storage-engine-time-structured-merge-tree/
+[tsm1-commit]: https://github.com/influxdata/influxdb/commit/15d723dc77651bac83e09e2b1c94be480966cb0d
+[influx-admin]: https://docs.influxdata.com/influxdb/v0.9/administration/authentication_and_authorization/#create-a-new-admin-user
diff --git a/doc/administration/monitoring/performance/influxdb_schema.md b/doc/administration/monitoring/performance/influxdb_schema.md
new file mode 100644
index 00000000000..eff0e29f58d
--- /dev/null
+++ b/doc/administration/monitoring/performance/influxdb_schema.md
@@ -0,0 +1,97 @@
+# InfluxDB Schema
+
+The following measurements are currently stored in InfluxDB:
+
+- `PROCESS_file_descriptors`
+- `PROCESS_gc_statistics`
+- `PROCESS_memory_usage`
+- `PROCESS_method_calls`
+- `PROCESS_object_counts`
+- `PROCESS_transactions`
+- `PROCESS_views`
+- `events`
+
+Here, `PROCESS` is replaced with either `rails` or `sidekiq` depending on the
+process type. In all series, any form of duration is stored in milliseconds.
+
+## PROCESS_file_descriptors
+
+This measurement contains the number of open file descriptors over time. The
+value field `value` contains the number of descriptors.
+
+## PROCESS_gc_statistics
+
+This measurement contains Ruby garbage collection statistics such as the amount
+of minor/major GC runs (relative to the last sampling interval), the time spent
+in garbage collection cycles, and all fields/values returned by `GC.stat`.
+
+## PROCESS_memory_usage
+
+This measurement contains the process' memory usage (in bytes) over time. The
+value field `value` contains the number of bytes.
+
+## PROCESS_method_calls
+
+This measurement contains the methods called during a transaction along with
+their duration, and a name of the transaction action that invoked the method (if
+available). The method call duration is stored in the value field `duration`,
+while the method name is stored in the tag `method`. The tag `action` contains
+the full name of the transaction action. Both the `method` and `action` fields
+are in the following format:
+
+```
+ClassName#method_name
+```
+
+For example, a method called by the `show` method in the `UsersController` class
+would have `action` set to `UsersController#show`.
+
+## PROCESS_object_counts
+
+This measurement is used to store retained Ruby objects (per class) and the
+amount of retained objects. The number of objects is stored in the `count` value
+field while the class name is stored in the `type` tag.
+
+## PROCESS_transactions
+
+This measurement is used to store basic transaction details such as the time it
+took to complete a transaction, how much time was spent in SQL queries, etc. The
+following value fields are available:
+
+| Value | Description |
+| ----- | ----------- |
+| `duration`  | The total duration of the transaction |
+| `allocated_memory` | The amount of bytes allocated while the transaction was running. This value is only reliable when using single-threaded application servers |
+| `method_duration` | The total time spent in method calls |
+| `sql_duration` | The total time spent in SQL queries |
+| `view_duration` | The total time spent in views |
+
+## PROCESS_views
+
+This measurement is used to store view rendering timings for a transaction. The
+following value fields are available:
+
+| Value | Description |
+| ----- | ----------- |
+| `duration` | The rendering time of the view |
+| `view` | The path of the view, relative to the application's root directory |
+
+The `action` tag contains the action name of the transaction that rendered the
+view.
+
+## events
+
+This measurement is used to store generic events such as the number of Git
+pushes, Emails sent, etc. Each point in this measurement has a single value
+field called `count`. The value of this field is simply set to `1`. Each point
+also has at least one tag: `event`. This tag's value is set to the event name.
+Depending on the event type additional tags may be available as well.
+
+---
+
+Read more on:
+
+- [Introduction to GitLab Performance Monitoring](introduction.md)
+- [GitLab Configuration](gitlab_configuration.md)
+- [InfluxDB Configuration](influxdb_configuration.md)
+- [Grafana Install/Configuration](grafana_configuration.md)
diff --git a/doc/administration/monitoring/performance/introduction.md b/doc/administration/monitoring/performance/introduction.md
new file mode 100644
index 00000000000..79904916b7e
--- /dev/null
+++ b/doc/administration/monitoring/performance/introduction.md
@@ -0,0 +1,65 @@
+# GitLab Performance Monitoring
+
+GitLab comes with its own application performance measuring system as of GitLab
+8.4, simply called "GitLab Performance Monitoring". GitLab Performance Monitoring is available in both the
+Community and Enterprise editions.
+
+Apart from this introduction, you are advised to read through the following
+documents in order to understand and properly configure GitLab Performance Monitoring:
+
+- [GitLab Configuration](gitlab_configuration.md)
+- [InfluxDB Install/Configuration](influxdb_configuration.md)
+- [InfluxDB Schema](influxdb_schema.md)
+- [Grafana Install/Configuration](grafana_configuration.md)
+
+## Introduction to GitLab Performance Monitoring
+
+GitLab Performance Monitoring makes it possible to measure a wide variety of statistics
+including (but not limited to):
+
+- The time it took to complete a transaction (a web request or Sidekiq job).
+- The time spent in running SQL queries and rendering HAML views.
+- The time spent executing (instrumented) Ruby methods.
+- Ruby object allocations, and retained objects in particular.
+- System statistics such as the process' memory usage and open file descriptors.
+- Ruby garbage collection statistics.
+
+Metrics data is written to [InfluxDB][influxdb] over [UDP][influxdb-udp]. Stored
+data can be visualized using [Grafana][grafana] or any other application that
+supports reading data from InfluxDB. Alternatively data can be queried using the
+InfluxDB CLI.
+
+## Metric Types
+
+Two types of metrics are collected:
+
+1. Transaction specific metrics.
+1. Sampled metrics, collected at a certain interval in a separate thread.
+
+### Transaction Metrics
+
+Transaction metrics are metrics that can be associated with a single
+transaction. This includes statistics such as the transaction duration, timings
+of any executed SQL queries, time spent rendering HAML views, etc. These metrics
+are collected for every Rack request and Sidekiq job processed.
+
+### Sampled Metrics
+
+Sampled metrics are metrics that can't be associated with a single transaction.
+Examples include garbage collection statistics and retained Ruby objects. These
+metrics are collected at a regular interval. This interval is made up out of two
+parts:
+
+1. A user defined interval.
+1. A randomly generated offset added on top of the interval, the same offset
+   can't be used twice in a row.
+
+The actual interval can be anywhere between a half of the defined interval and a
+half above the interval. For example, for a user defined interval of 15 seconds
+the actual interval can be anywhere between 7.5 and 22.5. The interval is
+re-generated for every sampling run instead of being generated once and re-used
+for the duration of the process' lifetime.
+
+[influxdb]: https://influxdata.com/time-series-platform/influxdb/
+[influxdb-udp]: https://docs.influxdata.com/influxdb/v0.9/write_protocols/udp/
+[grafana]: http://grafana.org/
-- 
cgit v1.2.1


From 68364fe2f03a543c4ad89553f50b6fa30d143331 Mon Sep 17 00:00:00 2001
From: Markus Koller <markus-koller@gmx.ch>
Date: Tue, 30 Aug 2016 13:21:33 +0200
Subject: Log LDAP lookup errors and don't swallow unrelated exceptions

Signed-off-by: Roger Meier <r.meier@siemens.com>
---
 doc/administration/auth/ldap.md | 6 ++++++
 1 file changed, 6 insertions(+)

(limited to 'doc/administration')

diff --git a/doc/administration/auth/ldap.md b/doc/administration/auth/ldap.md
index 7186f707ad6..bf7814875bf 100644
--- a/doc/administration/auth/ldap.md
+++ b/doc/administration/auth/ldap.md
@@ -275,3 +275,9 @@ If you are getting 'Connection Refused' errors when trying to connect to the
 LDAP server please double-check the LDAP `port` and `method` settings used by
 GitLab. Common combinations are `method: 'plain'` and `port: 389`, OR
 `method: 'ssl'` and `port: 636`.
+
+### Login with valid credentials rejected
+
+If there is an unexpected error while authenticating the user with the LDAP
+backend, the login is rejected and details about the error are logged to
+`production.log`.
-- 
cgit v1.2.1


From 74c8e091f40c29a59b99bf7864b9fee303c68e50 Mon Sep 17 00:00:00 2001
From: Fu Xu <fuxu@fuxu.name>
Date: Fri, 2 Sep 2016 16:57:08 +0800
Subject: add configurable email subject suffix

---
 doc/administration/environment_variables.md | 20 +++++++++++---------
 1 file changed, 11 insertions(+), 9 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/environment_variables.md b/doc/administration/environment_variables.md
index 7f53915a4d7..b4a953d1ccc 100644
--- a/doc/administration/environment_variables.md
+++ b/doc/administration/environment_variables.md
@@ -13,15 +13,17 @@ override certain values.
 
 Variable | Type | Description
 -------- | ---- | -----------
-`GITLAB_ROOT_PASSWORD`      | string | Sets the password for the `root` user on installation
-`GITLAB_HOST`               | string | The full URL of the GitLab server (including `http://` or `https://`)
-`RAILS_ENV`                 | string | The Rails environment; can be one of `production`, `development`, `staging` or `test`
-`DATABASE_URL`              | string | The database URL; is of the form: `postgresql://localhost/blog_development`
-`GITLAB_EMAIL_FROM`         | string | The e-mail address used in the "From" field in e-mails sent by GitLab
-`GITLAB_EMAIL_DISPLAY_NAME` | string | The name used in the "From" field in e-mails sent by GitLab
-`GITLAB_EMAIL_REPLY_TO`     | string | The e-mail address used in the "Reply-To" field in e-mails sent by GitLab
-`GITLAB_UNICORN_MEMORY_MIN` | integer | The minimum memory threshold (in bytes) for the Unicorn worker killer
-`GITLAB_UNICORN_MEMORY_MAX` | integer | The maximum memory threshold (in bytes) for the Unicorn worker killer
+`GITLAB_ROOT_PASSWORD`        | string  | Sets the password for the `root` user on installation
+`GITLAB_HOST`                 | string  | The full URL of the GitLab server (including `http://` or `https://`)
+`RAILS_ENV`                   | string  | The Rails environment; can be one of `production`, `development`, `staging` or `test`
+`DATABASE_URL`                | string  | The database URL; is of the form: `postgresql://localhost/blog_development`
+`GITLAB_EMAIL_FROM`           | string  | The e-mail address used in the "From" field in e-mails sent by GitLab
+`GITLAB_EMAIL_DISPLAY_NAME`   | string  | The name used in the "From" field in e-mails sent by GitLab
+`GITLAB_EMAIL_REPLY_TO`       | string  | The e-mail address used in the "Reply-To" field in e-mails sent by GitLab
+`GITLAB_EMAIL_REPLY_TO`       | string  | The e-mail address used in the "Reply-To" field in e-mails sent by GitLab
+`GITLAB_EMAIL_SUBJECT_SUFFIX` | string  | The e-mail subject suffix used in e-mails sent by GitLab
+`GITLAB_UNICORN_MEMORY_MIN`   | integer | The minimum memory threshold (in bytes) for the Unicorn worker killer
+`GITLAB_UNICORN_MEMORY_MAX`   | integer | The maximum memory threshold (in bytes) for the Unicorn worker killer
 
 ## Complete database variables
 
-- 
cgit v1.2.1


From bd9bdddad3b24dbd22268ccc2e9fba208ed02d5b Mon Sep 17 00:00:00 2001
From: Wolfgang Faust <wolfgangmcq@gmail.com>
Date: Tue, 4 Oct 2016 12:10:14 -0400
Subject: Update housekeeping docs for new GitLab UI.

---
 doc/administration/housekeeping.md               |   2 +-
 doc/administration/img/housekeeping_settings.png | Bin 19347 -> 27420 bytes
 2 files changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/administration')

diff --git a/doc/administration/housekeeping.md b/doc/administration/housekeeping.md
index 34b4f1faa94..ad1fa98b63b 100644
--- a/doc/administration/housekeeping.md
+++ b/doc/administration/housekeeping.md
@@ -12,7 +12,7 @@ revisions (to reduce disk space and increase performance) and removing
 unreachable objects which may have been created from prior invocations of
 `git add`.
 
-You can find this option under your **[Project] > Settings**.
+You can find this option under your **[Project] > Edit Project**.
 
 ---
 
diff --git a/doc/administration/img/housekeeping_settings.png b/doc/administration/img/housekeeping_settings.png
index f72ad9a45d5..6ebc6205635 100644
Binary files a/doc/administration/img/housekeeping_settings.png and b/doc/administration/img/housekeeping_settings.png differ
-- 
cgit v1.2.1


From babb78d1adc7fb19615d9ed4ba974a83b75c5a8b Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axilleas@axilleas.me>
Date: Thu, 6 Oct 2016 15:22:41 +0200
Subject: Remove doctoc from administration/container_registry

---
 doc/administration/container_registry.md | 20 --------------------
 1 file changed, 20 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/container_registry.md b/doc/administration/container_registry.md
index c5ba777d093..25c5474745b 100644
--- a/doc/administration/container_registry.md
+++ b/doc/administration/container_registry.md
@@ -16,26 +16,6 @@ have its own space to store its Docker images.
 
 You can read more about Docker Registry at https://docs.docker.com/registry/introduction/.
 
----
-
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
-
-- [Enable the Container Registry](#enable-the-container-registry)
-- [Container Registry domain configuration](#container-registry-domain-configuration)
-    - [Configure Container Registry under an existing GitLab domain](#configure-container-registry-under-an-existing-gitlab-domain)
-    - [Configure Container Registry under its own domain](#configure-container-registry-under-its-own-domain)
-- [Disable Container Registry site-wide](#disable-container-registry-site-wide)
-- [Disable Container Registry per project](#disable-container-registry-per-project)
-- [Disable Container Registry for new projects site-wide](#disable-container-registry-for-new-projects-site-wide)
-- [Container Registry storage path](#container-registry-storage-path)
-- [Container Registry storage driver](#container-registry-storage-driver)
-- [Storage limitations](#storage-limitations)
-- [Changelog](#changelog)
-
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
-
 ## Enable the Container Registry
 
 **Omnibus GitLab installations**
-- 
cgit v1.2.1


From db77289bcb0a075d8de5c7052ef93a91616afb76 Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axilleas@axilleas.me>
Date: Thu, 6 Oct 2016 18:42:30 +0200
Subject: Document how to change the Registry's internal port

Closes https://gitlab.com/gitlab-org/omnibus-gitlab/issues/1433
---
 doc/administration/container_registry.md | 85 +++++++++++++++++++++++---------
 1 file changed, 62 insertions(+), 23 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/container_registry.md b/doc/administration/container_registry.md
index 25c5474745b..d7cfb464f74 100644
--- a/doc/administration/container_registry.md
+++ b/doc/administration/container_registry.md
@@ -1,31 +1,32 @@
-# GitLab Container Registry Administration
+# GitLab Container Registry administration
 
 > [Introduced][ce-4040] in GitLab 8.8.
 
 ---
 
-> **Note**
-Docker Registry manifest `v1` support was added in GitLab 8.9 to support Docker
-versions earlier than 1.10.
->
-This document is about the admin guide. To learn how to use GitLab Container
-Registry [user documentation](../user/project/container_registry.md).
+> **Notes:**
+- Container Registry manifest `v1` support was added in GitLab 8.9 to support
+  Docker versions earlier than 1.10.
+- This document is about the admin guide. To learn how to use GitLab Container
+  Registry [user documentation](../user/project/container_registry.md).
 
-With the Docker Container Registry integrated into GitLab, every project can
-have its own space to store its Docker images.
+With the Container Registry integrated into GitLab, every project can have its
+own space to store its Docker images.
 
-You can read more about Docker Registry at https://docs.docker.com/registry/introduction/.
+You can read more about the Container Registry at
+https://docs.docker.com/registry/introduction/.
 
 ## Enable the Container Registry
 
 **Omnibus GitLab installations**
 
 All you have to do is configure the domain name under which the Container
-Registry will listen to. Read [#container-registry-domain-configuration](#container-registry-domain-configuration)
+Registry will listen to. Read
+[#container-registry-domain-configuration](#container-registry-domain-configuration)
 and pick one of the two options that fits your case.
 
 >**Note:**
-The container Registry works under HTTPS by default. Using HTTP is possible
+The container registry works under HTTPS by default. Using HTTP is possible
 but not recommended and out of the scope of this document.
 Read the [insecure Registry documentation][docker-insecure] if you want to
 implement this.
@@ -36,7 +37,7 @@ implement this.
 
 If you have installed GitLab from source:
 
-1. You will have to [install Docker Registry][registry-deploy] by yourself.
+1. You will have to [install Registry][registry-deploy] by yourself.
 1. After the installation is complete, you will have to configure the Registry's
    settings in `gitlab.yml` in order to enable it.
 1. Use the sample NGINX configuration file that is found under
@@ -69,11 +70,13 @@ where:
 | `issuer`  | This should be the same value as configured in Registry's `issuer`. Read the [token auth configuration documentation][token-config]. |
 
 >**Note:**
-GitLab does not ship with a Registry init file. Hence, [restarting GitLab][restart gitlab]
-will not restart the Registry should you modify its settings. Read the upstream
-documentation on how to achieve that.
+A Registry init file is not shipped with GitLab if you install it from source.
+Hence, [restarting GitLab][restart gitlab] will not restart the Registry should
+you modify its settings. Read the upstream documentation on how to achieve that.
 
-The Docker Registry configuration will need `container_registry` as the service and `https://gitlab.example.com/jwt/auth` as the realm:
+At the absolute minimum, make sure your [Registry configuration][registry-auth]
+has `container_registry` as the service and `https://gitlab.example.com/jwt/auth`
+as the realm:
 
 ```
 auth:
@@ -264,12 +267,6 @@ Registry application itself.
 
 1. Save the file and [restart GitLab][] for the changes to take effect.
 
-## Disable Container Registry per project
-
-If Registry is enabled in your GitLab instance, but you don't need it for your
-project, you can disable it from your project's settings. Read the user guide
-on how to achieve that.
-
 ## Disable Container Registry for new projects site-wide
 
 If the Container Registry is enabled, then it will be available on all new
@@ -425,6 +422,46 @@ storage:
     enabled: true
 ```
 
+## Change the registry's internal port
+
+> **Note:**
+This is not to be confused with the port that GitLab itself uses to expose
+the Registry to the world.
+
+The Registry server listens on localhost at port `5000` by default,
+which is the address for which the Registry server should accept connections.
+In the examples below we set the Registry's port to `5001`.
+
+**Omnibus GitLab**
+
+1. Open `/etc/gitlab/gitlab.rb` and set `registry['registry_http_addr']`:
+
+    ```ruby
+    registry['registry_http_addr'] = "localhost:5001"
+    ```
+
+1. Save the file and [reconfigure GitLab][] for the changes to take effect.
+
+---
+
+**Installations from source**
+
+1. Open the configuration file of your Registry server and edit the
+   [`http:addr`][registry-http-config] value:
+
+    ```
+    http
+      addr: localhost:5001
+    ```
+
+1. Save the file and restart the Registry server.
+
+## Disable Container Registry per project
+
+If Registry is enabled in your GitLab instance, but you don't need it for your
+project, you can disable it from your project's settings. Read the user guide
+on how to achieve that.
+
 ## Storage limitations
 
 Currently, there is no storage limitation, which means a user can upload an
@@ -444,6 +481,8 @@ configurable in future releases.
 [docker-insecure]: https://docs.docker.com/registry/insecure/
 [registry-deploy]: https://docs.docker.com/registry/deploying/
 [storage-config]: https://docs.docker.com/registry/configuration/#storage
+[registry-http-config]: https://docs.docker.com/registry/configuration/#http
+[registry-auth]: https://docs.docker.com/registry/configuration/#auth
 [token-config]: https://docs.docker.com/registry/configuration/#token
 [8-8-docs]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-8-stable/doc/administration/container_registry.md
 [registry-ssl]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/support/nginx/registry-ssl
-- 
cgit v1.2.1


From dd9e5ba16598eceb61a2d27a4519710b84d01397 Mon Sep 17 00:00:00 2001
From: Chris Wilson <chris@chrisjwilson.com>
Date: Tue, 11 Oct 2016 05:33:55 +0000
Subject: Fix step number and token param in URL example. Fix gitlab-rails
 command code formatting.

---
 doc/administration/troubleshooting/debug.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/troubleshooting/debug.md b/doc/administration/troubleshooting/debug.md
index d127d7b85e5..d8dce4388e1 100644
--- a/doc/administration/troubleshooting/debug.md
+++ b/doc/administration/troubleshooting/debug.md
@@ -144,14 +144,14 @@ separate Rails process to debug the issue:
 1. Obtain the private token for your user (Profile Settings -> Account).
 1. Bring up the GitLab Rails console. For omnibus users, run:
 
-    ````
+    ```
     sudo gitlab-rails console
     ```
 
 1. At the Rails console, run:
 
     ```ruby
-    [1] pry(main)> app.get '<URL FROM STEP 1>/private_token?<TOKEN FROM STEP 2>'
+    [1] pry(main)> app.get '<URL FROM STEP 2>/?private_token=<TOKEN FROM STEP 3>'
     ```
 
     For example:
-- 
cgit v1.2.1


From 1bbe1cea919d174b9bc1bdd39e6235ffadcccb50 Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axilleas@axilleas.me>
Date: Tue, 11 Oct 2016 15:55:32 +0200
Subject: Move health check docs under user/admin_area/monitoring

[ci skip]
---
 doc/administration/monitoring/health_check.md      |  66 ---------------------
 .../monitoring/img/health_check_token.png          | Bin 6630 -> 0 bytes
 2 files changed, 66 deletions(-)
 delete mode 100644 doc/administration/monitoring/health_check.md
 delete mode 100644 doc/administration/monitoring/img/health_check_token.png

(limited to 'doc/administration')

diff --git a/doc/administration/monitoring/health_check.md b/doc/administration/monitoring/health_check.md
deleted file mode 100644
index eac57bc3de4..00000000000
--- a/doc/administration/monitoring/health_check.md
+++ /dev/null
@@ -1,66 +0,0 @@
-# Health Check
-
-> [Introduced][ce-3888] in GitLab 8.8.
-
-GitLab provides a health check endpoint for uptime monitoring on the `health_check` web
-endpoint. The health check reports on the overall system status based on the status of
-the database connection, the state of the database migrations, and the ability to write
-and access the cache. This endpoint can be provided to uptime monitoring services like
-[Pingdom][pingdom], [Nagios][nagios-health], and [NewRelic][newrelic-health].
-
-## Access Token
-
-An access token needs to be provided while accessing the health check endpoint. The current
-accepted token can be found on the `admin/health_check` page of your GitLab instance.
-
-![access token](img/health_check_token.png)
-
-The access token can be passed as a URL parameter:
-
-```
-https://gitlab.example.com/health_check.json?token=ACCESS_TOKEN
-```
-
-or as an HTTP header:
-
-```bash
-curl --header "TOKEN: ACCESS_TOKEN" https://gitlab.example.com/health_check.json
-```
-
-## Using the Endpoint
-
-Once you have the access token, health information can be retrieved as plain text, JSON,
-or XML using the `health_check` endpoint:
-
-- `https://gitlab.example.com/health_check?token=ACCESS_TOKEN`
-- `https://gitlab.example.com/health_check.json?token=ACCESS_TOKEN`
-- `https://gitlab.example.com/health_check.xml?token=ACCESS_TOKEN`
-
-You can also ask for the status of specific services:
-
-- `https://gitlab.example.com/health_check/cache.json?token=ACCESS_TOKEN`
-- `https://gitlab.example.com/health_check/database.json?token=ACCESS_TOKEN`
-- `https://gitlab.example.com/health_check/migrations.json?token=ACCESS_TOKEN`
-
-For example, the JSON output of the following health check:
-
-```bash
-curl --header "TOKEN: ACCESS_TOKEN" https://gitlab.example.com/health_check.json
-```
-
-would be like:
-
-```
-{"healthy":true,"message":"success"}
-```
-
-## Status
-
-On failure, the endpoint will return a `500` HTTP status code. On success, the endpoint
-will return a valid successful HTTP status code, and a `success` message. Ideally your
-uptime monitoring should look for the success message.
-
-[ce-3888]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3888
-[pingdom]: https://www.pingdom.com
-[nagios-health]: https://nagios-plugins.org/doc/man/check_http.html
-[newrelic-health]: https://docs.newrelic.com/docs/alerts/alert-policies/downtime-alerts/availability-monitoring
diff --git a/doc/administration/monitoring/img/health_check_token.png b/doc/administration/monitoring/img/health_check_token.png
deleted file mode 100644
index 2d7c82a65a8..00000000000
Binary files a/doc/administration/monitoring/img/health_check_token.png and /dev/null differ
-- 
cgit v1.2.1


From d8f33c0a51d9106ece6cd4bae469e40734e05f85 Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axilleas@axilleas.me>
Date: Sun, 25 Sep 2016 12:44:09 +0200
Subject: Move operations/ to new location

[ci skip]
---
 doc/administration/operations.md                   |   6 +
 .../operations/cleaning_up_redis_sessions.md       |  52 ++++++
 .../operations/moving_repositories.md              | 180 +++++++++++++++++++++
 .../operations/sidekiq_memory_killer.md            |  40 +++++
 doc/administration/operations/unicorn.md           |  86 ++++++++++
 5 files changed, 364 insertions(+)
 create mode 100644 doc/administration/operations.md
 create mode 100644 doc/administration/operations/cleaning_up_redis_sessions.md
 create mode 100644 doc/administration/operations/moving_repositories.md
 create mode 100644 doc/administration/operations/sidekiq_memory_killer.md
 create mode 100644 doc/administration/operations/unicorn.md

(limited to 'doc/administration')

diff --git a/doc/administration/operations.md b/doc/administration/operations.md
new file mode 100644
index 00000000000..4b582d16b64
--- /dev/null
+++ b/doc/administration/operations.md
@@ -0,0 +1,6 @@
+# GitLab operations
+
+- [Sidekiq MemoryKiller](operations/sidekiq_memory_killer.md)
+- [Cleaning up Redis sessions](operations/cleaning_up_redis_sessions.md)
+- [Understanding Unicorn and unicorn-worker-killer](operations/unicorn.md)
+- [Moving repositories to a new location](operations/moving_repositories.md)
diff --git a/doc/administration/operations/cleaning_up_redis_sessions.md b/doc/administration/operations/cleaning_up_redis_sessions.md
new file mode 100644
index 00000000000..93521e976d5
--- /dev/null
+++ b/doc/administration/operations/cleaning_up_redis_sessions.md
@@ -0,0 +1,52 @@
+# Cleaning up stale Redis sessions
+
+Since version 6.2, GitLab stores web user sessions as key-value pairs in Redis.
+Prior to GitLab 7.3, user sessions did not automatically expire from Redis. If
+you have been running a large GitLab server (thousands of users) since before
+GitLab 7.3 we recommend cleaning up stale sessions to compact the Redis
+database after you upgrade to GitLab 7.3. You can also perform a cleanup while
+still running GitLab 7.2 or older, but in that case new stale sessions will
+start building up again after you clean up.
+
+In GitLab versions prior to 7.3.0, the session keys in Redis are 16-byte
+hexadecimal values such as '976aa289e2189b17d7ef525a6702ace9'. Starting with
+GitLab 7.3.0, the keys are
+prefixed with 'session:gitlab:', so they would look like
+'session:gitlab:976aa289e2189b17d7ef525a6702ace9'. Below we describe how to
+remove the keys in the old format.
+
+First we define a shell function with the proper Redis connection details.
+
+```
+rcli() {
+  # This example works for Omnibus installations of GitLab 7.3 or newer. For an
+  # installation from source you will have to change the socket path and the
+  # path to redis-cli.
+  sudo /opt/gitlab/embedded/bin/redis-cli -s /var/opt/gitlab/redis/redis.socket "$@"
+}
+
+# test the new shell function; the response should be PONG
+rcli ping
+```
+
+Now we do a search to see if there are any session keys in the old format for
+us to clean up.
+
+```
+# returns the number of old-format session keys in Redis
+rcli keys '*' | grep '^[a-f0-9]\{32\}$' | wc -l
+```
+
+If the number is larger than zero, you can proceed to expire the keys from
+Redis. If the number is zero there is nothing to clean up.
+
+```
+# Tell Redis to expire each matched key after 600 seconds.
+rcli keys '*' | grep '^[a-f0-9]\{32\}$' | awk '{ print "expire", $0, 600 }' | rcli
+# This will print '(integer) 1' for each key that gets expired.
+```
+
+Over the next 15 minutes (10 minutes expiry time plus 5 minutes Redis
+background save interval) your Redis database will be compacted. If you are
+still using GitLab 7.2, users who are not clicking around in GitLab during the
+10 minute expiry window will be signed out of GitLab.
diff --git a/doc/administration/operations/moving_repositories.md b/doc/administration/operations/moving_repositories.md
new file mode 100644
index 00000000000..54adb99386a
--- /dev/null
+++ b/doc/administration/operations/moving_repositories.md
@@ -0,0 +1,180 @@
+# Moving repositories managed by GitLab
+
+Sometimes you need to move all repositories managed by GitLab to
+another filesystem or another server. In this document we will look
+at some of the ways you can copy all your repositories from
+`/var/opt/gitlab/git-data/repositories` to `/mnt/gitlab/repositories`.
+
+We will look at three scenarios: the target directory is empty, the
+target directory contains an outdated copy of the repositories, and
+how to deal with thousands of repositories.
+
+**Each of the approaches we list can/will overwrite data in the
+target directory `/mnt/gitlab/repositories`. Do not mix up the
+source and the target.**
+
+## Target directory is empty: use a tar pipe
+
+If the target directory `/mnt/gitlab/repositories` is empty the
+simplest thing to do is to use a tar pipe.  This method has low
+overhead and tar is almost always already installed on your system.
+However, it is not possible to resume an interrupted tar pipe:  if
+that happens then all data must be copied again.
+
+```
+# As the git user
+tar -C /var/opt/gitlab/git-data/repositories -cf - -- . |\
+  tar -C /mnt/gitlab/repositories -xf -
+```
+
+If you want to see progress, replace `-xf` with `-xvf`.
+
+### Tar pipe to another server
+
+You can also use a tar pipe to copy data to another server. If your
+'git' user has SSH access to the newserver as 'git@newserver', you
+can pipe the data through SSH.
+
+```
+# As the git user
+tar -C /var/opt/gitlab/git-data/repositories -cf - -- . |\
+  ssh git@newserver tar -C /mnt/gitlab/repositories -xf -
+```
+
+If you want to compress the data before it goes over the network
+(which will cost you CPU cycles) you can replace `ssh` with `ssh -C`.
+
+## The target directory contains an outdated copy of the repositories: use rsync
+
+If the target directory already contains a partial / outdated copy
+of the repositories it may be wasteful to copy all the data again
+with tar. In this scenario it is better to use rsync. This utility
+is either already installed on your system or easily installable
+via apt, yum etc.
+
+```
+# As the 'git' user
+rsync -a --delete /var/opt/gitlab/git-data/repositories/. \
+  /mnt/gitlab/repositories
+```
+
+The `/.` in the command above is very important, without it you can
+easily get the wrong directory structure in the target directory.
+If you want to see progress, replace `-a` with `-av`.
+
+### Single rsync to another server
+
+If the 'git' user on your source system has SSH access to the target
+server you can send the repositories over the network with rsync.
+
+```
+# As the 'git' user
+rsync -a --delete /var/opt/gitlab/git-data/repositories/. \
+  git@newserver:/mnt/gitlab/repositories
+```
+
+## Thousands of Git repositories: use one rsync per repository
+
+Every time you start an rsync job it has to inspect all files in
+the source directory, all files in the target directory, and then
+decide what files to copy or not. If the source or target directory
+has many contents this startup phase of rsync can become a burden
+for your GitLab server. In cases like this you can make rsync's
+life easier by dividing its work in smaller pieces, and sync one
+repository at a time.
+
+In addition to rsync we will use [GNU
+Parallel](http://www.gnu.org/software/parallel/). This utility is
+not included in GitLab so you need to install it yourself with apt
+or yum.  Also note that the GitLab scripts we used below were added
+in GitLab 8.1.
+
+** This process does not clean up repositories at the target location that no
+longer exist at the source. ** If you start using your GitLab instance with
+`/mnt/gitlab/repositories`, you need to run `gitlab-rake gitlab:cleanup:repos`
+after switching to the new repository storage directory.
+
+### Parallel rsync for all repositories known to GitLab
+
+This will sync repositories with 10 rsync processes at a time. We keep
+track of progress so that the transfer can be restarted if necessary.
+
+First we create a new directory, owned by 'git', to hold transfer
+logs. We assume the directory is empty before we start the transfer
+procedure, and that we are the only ones writing files in it.
+
+```
+# Omnibus
+sudo mkdir /var/opt/gitlab/transfer-logs
+sudo chown git:git /var/opt/gitlab/transfer-logs
+
+# Source
+sudo -u git -H mkdir /home/git/transfer-logs
+```
+
+We seed the process with a list of the directories we want to copy.
+
+```
+# Omnibus
+sudo -u git sh -c 'gitlab-rake gitlab:list_repos > /var/opt/gitlab/transfer-logs/all-repos-$(date +%s).txt'
+
+# Source
+cd /home/git/gitlab
+sudo -u git -H sh -c 'bundle exec rake gitlab:list_repos > /home/git/transfer-logs/all-repos-$(date +%s).txt'
+```
+
+Now we can start the transfer. The command below is idempotent, and
+the number of jobs done by GNU Parallel should converge to zero. If it
+does not some repositories listed in all-repos-1234.txt may have been
+deleted/renamed before they could be copied.
+
+```
+# Omnibus
+sudo -u git sh -c '
+cat /var/opt/gitlab/transfer-logs/* | sort | uniq -u |\
+  /usr/bin/env JOBS=10 \
+  /opt/gitlab/embedded/service/gitlab-rails/bin/parallel-rsync-repos \
+    /var/opt/gitlab/transfer-logs/success-$(date +%s).log \
+    /var/opt/gitlab/git-data/repositories \
+    /mnt/gitlab/repositories
+'
+
+# Source
+cd /home/git/gitlab
+sudo -u git -H sh -c '
+cat /home/git/transfer-logs/* | sort | uniq -u |\
+  /usr/bin/env JOBS=10 \
+  bin/parallel-rsync-repos \
+    /home/git/transfer-logs/success-$(date +%s).log \
+    /home/git/repositories \
+    /mnt/gitlab/repositories
+`
+```
+
+### Parallel rsync only for repositories with recent activity
+
+Suppose you have already done one sync that started after 2015-10-1 12:00 UTC.
+Then you might only want to sync repositories that were changed via GitLab
+_after_ that time. You can use the 'SINCE' variable to tell 'rake
+gitlab:list_repos' to only print repositories with recent activity.
+
+```
+# Omnibus
+sudo gitlab-rake gitlab:list_repos SINCE='2015-10-1 12:00 UTC' |\
+  sudo -u git \
+  /usr/bin/env JOBS=10 \
+  /opt/gitlab/embedded/service/gitlab-rails/bin/parallel-rsync-repos \
+    success-$(date +%s).log \
+    /var/opt/gitlab/git-data/repositories \
+    /mnt/gitlab/repositories
+
+# Source
+cd /home/git/gitlab
+sudo -u git -H bundle exec rake gitlab:list_repos SINCE='2015-10-1 12:00 UTC' |\
+  sudo -u git -H \
+  /usr/bin/env JOBS=10 \
+  bin/parallel-rsync-repos \
+    success-$(date +%s).log \
+    /home/git/repositories \
+    /mnt/gitlab/repositories
+```
diff --git a/doc/administration/operations/sidekiq_memory_killer.md b/doc/administration/operations/sidekiq_memory_killer.md
new file mode 100644
index 00000000000..b5e78348989
--- /dev/null
+++ b/doc/administration/operations/sidekiq_memory_killer.md
@@ -0,0 +1,40 @@
+# Sidekiq MemoryKiller
+
+The GitLab Rails application code suffers from memory leaks. For web requests
+this problem is made manageable using
+[unicorn-worker-killer](https://github.com/kzk/unicorn-worker-killer) which
+restarts Unicorn worker processes in between requests when needed. The Sidekiq
+MemoryKiller applies the same approach to the Sidekiq processes used by GitLab
+to process background jobs.
+
+Unlike unicorn-worker-killer, which is enabled by default for all GitLab
+installations since GitLab 6.4, the Sidekiq MemoryKiller is enabled by default
+_only_ for Omnibus packages. The reason for this is that the MemoryKiller
+relies on Runit to restart Sidekiq after a memory-induced shutdown and GitLab
+installations from source do not all use Runit or an equivalent.
+
+With the default settings, the MemoryKiller will cause a Sidekiq restart no
+more often than once every 15 minutes, with the restart causing about one
+minute of delay for incoming background jobs.
+
+## Configuring the MemoryKiller
+
+The MemoryKiller is controlled using environment variables.
+
+- `SIDEKIQ_MEMORY_KILLER_MAX_RSS`: if this variable is set, and its value is
+  greater than 0, then after each Sidekiq job, the MemoryKiller will check the
+  RSS of the Sidekiq process that executed the job. If the RSS of the Sidekiq
+  process (expressed in kilobytes) exceeds SIDEKIQ_MEMORY_KILLER_MAX_RSS, a
+  delayed shutdown is triggered. The default value for Omnibus packages is set
+  [in the omnibus-gitlab
+  repository](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-cookbooks/gitlab/attributes/default.rb).
+- `SIDEKIQ_MEMORY_KILLER_GRACE_TIME`: defaults 900 seconds (15 minutes). When
+  a shutdown is triggered, the Sidekiq process will keep working normally for
+  another 15 minutes.
+- `SIDEKIQ_MEMORY_KILLER_SHUTDOWN_WAIT`: defaults to 30 seconds. When the grace
+  time has expired, the MemoryKiller tells Sidekiq to stop accepting new jobs.
+  Existing jobs get 30 seconds to finish. After that, the MemoryKiller tells
+  Sidekiq to shut down, and an external supervision mechanism (e.g. Runit) must
+  restart Sidekiq.
+- `SIDEKIQ_MEMORY_KILLER_SHUTDOWN_SIGNAL`: defaults to `SIGKILL`. The name of
+  the final signal sent to the Sidekiq process when we want it to shut down.
diff --git a/doc/administration/operations/unicorn.md b/doc/administration/operations/unicorn.md
new file mode 100644
index 00000000000..bad61151bda
--- /dev/null
+++ b/doc/administration/operations/unicorn.md
@@ -0,0 +1,86 @@
+# Understanding Unicorn and unicorn-worker-killer
+
+## Unicorn
+
+GitLab uses [Unicorn](http://unicorn.bogomips.org/), a pre-forking Ruby web
+server, to handle web requests (web browsers and Git HTTP clients). Unicorn is
+a daemon written in Ruby and C that can load and run a Ruby on Rails
+application; in our case the Rails application is GitLab Community Edition or
+GitLab Enterprise Edition.
+
+Unicorn has a multi-process architecture to make better use of available CPU
+cores (processes can run on different cores) and to have stronger fault
+tolerance (most failures stay isolated in only one process and cannot take down
+GitLab entirely). On startup, the Unicorn 'master' process loads a clean Ruby
+environment with the GitLab application code, and then spawns 'workers' which
+inherit this clean initial environment. The 'master' never handles any
+requests, that is left to the workers. The operating system network stack
+queues incoming requests and distributes them among the workers.
+
+In a perfect world, the master would spawn its pool of workers once, and then
+the workers handle incoming web requests one after another until the end of
+time. In reality, worker processes can crash or time out: if the master notices
+that a worker takes too long to handle a request it will terminate the worker
+process with SIGKILL ('kill -9'). No matter how the worker process ended, the
+master process will replace it with a new 'clean' process again. Unicorn is
+designed to be able to replace 'crashed' workers without dropping user
+requests.
+
+This is what a Unicorn worker timeout looks like in `unicorn_stderr.log`. The
+master process has PID 56227 below.
+
+```
+[2015-06-05T10:58:08.660325 #56227] ERROR -- : worker=10 PID:53009 timeout (61s > 60s), killing
+[2015-06-05T10:58:08.699360 #56227] ERROR -- : reaped #<Process::Status: pid 53009 SIGKILL (signal 9)> worker=10
+[2015-06-05T10:58:08.708141 #62538]  INFO -- : worker=10 spawned pid=62538
+[2015-06-05T10:58:08.708824 #62538]  INFO -- : worker=10 ready
+```
+
+### Tunables
+
+The main tunables for Unicorn are the number of worker processes and the
+request timeout after which the Unicorn master terminates a worker process.
+See the [omnibus-gitlab Unicorn settings
+documentation](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/doc/settings/unicorn.md)
+if you want to adjust these settings.
+
+## unicorn-worker-killer
+
+GitLab has memory leaks. These memory leaks manifest themselves in long-running
+processes, such as Unicorn workers. (The Unicorn master process is not known to
+leak memory, probably because it does not handle user requests.)
+
+To make these memory leaks manageable, GitLab comes with the
+[unicorn-worker-killer gem](https://github.com/kzk/unicorn-worker-killer). This
+gem [monkey-patches](https://en.wikipedia.org/wiki/Monkey_patch) the Unicorn
+workers to do a memory self-check after every 16 requests. If the memory of the
+Unicorn worker exceeds a pre-set limit then the worker process exits. The
+Unicorn master then automatically replaces the worker process.
+
+This is a robust way to handle memory leaks: Unicorn is designed to handle
+workers that 'crash' so no user requests will be dropped. The
+unicorn-worker-killer gem is designed to only terminate a worker process _in
+between requests_, so no user requests are affected.
+
+This is what a Unicorn worker memory restart looks like in unicorn_stderr.log.
+You see that worker 4 (PID 125918) is inspecting itself and decides to exit.
+The threshold memory value was 254802235 bytes, about 250MB. With GitLab this
+threshold is a random value between 200 and 250 MB.  The master process (PID
+117565) then reaps the worker process and spawns a new 'worker 4' with PID
+127549.
+
+```
+[2015-06-05T12:07:41.828374 #125918]  WARN -- : #<Unicorn::HttpServer:0x00000002734770>: worker (pid: 125918) exceeds memory limit (256413696 bytes > 254802235 bytes)
+[2015-06-05T12:07:41.828472 #125918]  WARN -- : Unicorn::WorkerKiller send SIGQUIT (pid: 125918) alive: 23 sec (trial 1)
+[2015-06-05T12:07:42.025916 #117565]  INFO -- : reaped #<Process::Status: pid 125918 exit 0> worker=4
+[2015-06-05T12:07:42.034527 #127549]  INFO -- : worker=4 spawned pid=127549
+[2015-06-05T12:07:42.035217 #127549]  INFO -- : worker=4 ready
+```
+
+One other thing that stands out in the log snippet above, taken from
+GitLab.com, is that 'worker 4' was serving requests for only 23 seconds. This
+is a normal value for our current GitLab.com setup and traffic.
+
+The high frequency of Unicorn memory restarts on some GitLab sites can be a
+source of confusion for administrators. Usually they are a [red
+herring](https://en.wikipedia.org/wiki/Red_herring).
-- 
cgit v1.2.1


From 3939d4dfbfda5f7bb5133e12573c80f600ce451f Mon Sep 17 00:00:00 2001
From: Sean McGivern <sean@gitlab.com>
Date: Thu, 13 Oct 2016 09:58:06 +0100
Subject: Fix secret names in HA docs

---
 doc/administration/high_availability/gitlab.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/high_availability/gitlab.md b/doc/administration/high_availability/gitlab.md
index 8a881ce8863..137fed35a73 100644
--- a/doc/administration/high_availability/gitlab.md
+++ b/doc/administration/high_availability/gitlab.md
@@ -101,9 +101,9 @@ need some additional configuration.
 
     ```ruby
     gitlab_shell['secret_token'] = 'fbfb19c355066a9afb030992231c4a363357f77345edd0f2e772359e5be59b02538e1fa6cae8f93f7d23355341cea2b93600dab6d6c3edcdced558fc6d739860'
-    gitlab_rails['secret_token'] = 'b719fe119132c7810908bba18315259ed12888d4f5ee5430c42a776d840a396799b0a5ef0a801348c8a357f07aa72bbd58e25a84b8f247a25c72f539c7a6c5fa'
-    gitlab_ci['secret_key_base'] = '6e657410d57c71b4fc3ed0d694e7842b1895a8b401d812c17fe61caf95b48a6d703cb53c112bc01ebd197a85da81b18e29682040e99b4f26594772a4a2c98c6d'
-    gitlab_ci['db_key_base'] = 'bf2e47b68d6cafaef1d767e628b619365becf27571e10f196f98dc85e7771042b9203199d39aff91fcb6837c8ed83f2a912b278da50999bb11a2fbc0fba52964'
+    gitlab_rails['otp_key_base'] = 'b719fe119132c7810908bba18315259ed12888d4f5ee5430c42a776d840a396799b0a5ef0a801348c8a357f07aa72bbd58e25a84b8f247a25c72f539c7a6c5fa'
+    gitlab_rails['secret_key_base'] = '6e657410d57c71b4fc3ed0d694e7842b1895a8b401d812c17fe61caf95b48a6d703cb53c112bc01ebd197a85da81b18e29682040e99b4f26594772a4a2c98c6d'
+    gitlab_rails['db_key_base'] = 'bf2e47b68d6cafaef1d767e628b619365becf27571e10f196f98dc85e7771042b9203199d39aff91fcb6837c8ed83f2a912b278da50999bb11a2fbc0fba52964'
     ```
 
 1. Run `touch /etc/gitlab/skip-auto-migrations` to prevent database migrations
-- 
cgit v1.2.1


From c180221a5b0e58c42632412d2084efc3bd4cda99 Mon Sep 17 00:00:00 2001
From: Ahmad Sherif <me@ahmadsherif.com>
Date: Fri, 14 Oct 2016 19:49:36 +0200
Subject: Add docs for request profiling

Closes #23239
---
 .../performance/img/request_profile_result.png          | Bin 0 -> 9720 bytes
 .../performance/img/request_profiling_token.png         | Bin 0 -> 30076 bytes
 .../monitoring/performance/request_profiling.md         |  16 ++++++++++++++++
 3 files changed, 16 insertions(+)
 create mode 100644 doc/administration/monitoring/performance/img/request_profile_result.png
 create mode 100644 doc/administration/monitoring/performance/img/request_profiling_token.png
 create mode 100644 doc/administration/monitoring/performance/request_profiling.md

(limited to 'doc/administration')

diff --git a/doc/administration/monitoring/performance/img/request_profile_result.png b/doc/administration/monitoring/performance/img/request_profile_result.png
new file mode 100644
index 00000000000..73e2fdcab67
Binary files /dev/null and b/doc/administration/monitoring/performance/img/request_profile_result.png differ
diff --git a/doc/administration/monitoring/performance/img/request_profiling_token.png b/doc/administration/monitoring/performance/img/request_profiling_token.png
new file mode 100644
index 00000000000..04d87567816
Binary files /dev/null and b/doc/administration/monitoring/performance/img/request_profiling_token.png differ
diff --git a/doc/administration/monitoring/performance/request_profiling.md b/doc/administration/monitoring/performance/request_profiling.md
new file mode 100644
index 00000000000..c358dfbead2
--- /dev/null
+++ b/doc/administration/monitoring/performance/request_profiling.md
@@ -0,0 +1,16 @@
+# Request Profiling
+
+## Procedure
+1. Grab the profiling token from `Monitoring > Requests Profiles` admin page
+(highlighted in a blue in the image below).
+![Profile token](img/request_profiling_token.png)
+1. Pass the header `X-Profile-Token: <token>` to the request you want to profile. You can use any of these tools
+    * [ModHeader](https://chrome.google.com/webstore/detail/modheader/idgpnmonknjnojddfkpgkljpfnnfcklj) Chrome extension
+    * [Modify Headers](https://addons.mozilla.org/en-US/firefox/addon/modify-headers/) Firefox extension
+    * `curl --header 'X-Profile-Token: <token>' https://gitlab.example.com/group/project`
+1. Once request is finished (which will take a little longer than usual), you can
+view the profiling output from `Monitoring > Requests Profiles` admin page.
+![Profiling output](img/request_profile_result.png)
+
+## Cleaning up
+Profiling output will be cleared out every day via a Sidekiq worker.
-- 
cgit v1.2.1


From e805253d4e2132827f45ce82c99b50c1e1314cfc Mon Sep 17 00:00:00 2001
From: Sonmez Kartal <sonmez@koding.com>
Date: Tue, 25 Oct 2016 09:41:29 +0300
Subject: Add docker-compose environment initialization command

Signed-off-by: Sonmez Kartal <sonmez@koding.com>
---
 doc/administration/integration/koding.md | 1 +
 1 file changed, 1 insertion(+)

(limited to 'doc/administration')

diff --git a/doc/administration/integration/koding.md b/doc/administration/integration/koding.md
index a2c358af095..b95c425842c 100644
--- a/doc/administration/integration/koding.md
+++ b/doc/administration/integration/koding.md
@@ -61,6 +61,7 @@ executing commands in the following snippet.
 ```bash
 git clone https://github.com/koding/koding.git
 cd koding
+docker-compose -f docker-compose-init.yml run init
 docker-compose up
 ```
 
-- 
cgit v1.2.1


From af5322e90b47e830e7713482854ddf6450a0d8c1 Mon Sep 17 00:00:00 2001
From: Drew Blessing <drew@gitlab.com>
Date: Tue, 2 Aug 2016 22:46:43 -0600
Subject: Add Rake task to create/repair GitLab Shell hooks symlinks

---
 doc/administration/raketasks/maintenance.md | 220 ++++++++++++++++++++++++++++
 1 file changed, 220 insertions(+)
 create mode 100644 doc/administration/raketasks/maintenance.md

(limited to 'doc/administration')

diff --git a/doc/administration/raketasks/maintenance.md b/doc/administration/raketasks/maintenance.md
new file mode 100644
index 00000000000..f3c2e72341f
--- /dev/null
+++ b/doc/administration/raketasks/maintenance.md
@@ -0,0 +1,220 @@
+# Maintenance Rake Tasks
+
+## Gather information about GitLab and the system it runs on
+
+This command gathers information about your GitLab installation and the System it runs on. These may be useful when asking for help or reporting issues.
+
+**Omnibus Installation**
+
+```
+sudo gitlab-rake gitlab:env:info
+```
+
+**Source Installation**
+
+```
+bundle exec rake gitlab:env:info RAILS_ENV=production
+```
+
+Example output:
+
+```
+System information
+System:           Debian 7.8
+Current User:     git
+Using RVM:        no
+Ruby Version:     2.1.5p273
+Gem Version:      2.4.3
+Bundler Version:  1.7.6
+Rake Version:     10.3.2
+Sidekiq Version:  2.17.8
+
+GitLab information
+Version:          7.7.1
+Revision:         41ab9e1
+Directory:        /home/git/gitlab
+DB Adapter:       postgresql
+URL:              https://gitlab.example.com
+HTTP Clone URL:   https://gitlab.example.com/some-project.git
+SSH Clone URL:    git@gitlab.example.com:some-project.git
+Using LDAP:       no
+Using Omniauth:   no
+
+GitLab Shell
+Version:          2.4.1
+Repositories:     /home/git/repositories/
+Hooks:            /home/git/gitlab-shell/hooks/
+Git:              /usr/bin/git
+```
+
+## Check GitLab configuration
+
+Runs the following rake tasks:
+
+- `gitlab:gitlab_shell:check`
+- `gitlab:sidekiq:check`
+- `gitlab:app:check`
+
+It will check that each component was setup according to the installation guide and suggest fixes for issues found.
+
+You may also have a look at our [Trouble Shooting Guide](https://github.com/gitlabhq/gitlab-public-wiki/wiki/Trouble-Shooting-Guide).
+
+**Omnibus Installation**
+
+```
+sudo gitlab-rake gitlab:check
+```
+
+**Source Installation**
+
+```
+bundle exec rake gitlab:check RAILS_ENV=production
+```
+
+NOTE: Use SANITIZE=true for gitlab:check if you want to omit project names from the output.
+
+Example output:
+
+```
+Checking Environment ...
+
+Git configured for git user? ... yes
+Has python2? ... yes
+python2 is supported version? ... yes
+
+Checking Environment ... Finished
+
+Checking GitLab Shell ...
+
+GitLab Shell version? ... OK (1.2.0)
+Repo base directory exists? ... yes
+Repo base directory is a symlink? ... no
+Repo base owned by git:git? ... yes
+Repo base access is drwxrws---? ... yes
+post-receive hook up-to-date? ... yes
+post-receive hooks in repos are links: ... yes
+
+Checking GitLab Shell ... Finished
+
+Checking Sidekiq ...
+
+Running? ... yes
+
+Checking Sidekiq ... Finished
+
+Checking GitLab ...
+
+Database config exists? ... yes
+Database is SQLite ... no
+All migrations up? ... yes
+GitLab config exists? ... yes
+GitLab config outdated? ... no
+Log directory writable? ... yes
+Tmp directory writable? ... yes
+Init script exists? ... yes
+Init script up-to-date? ... yes
+Redis version >= 2.0.0? ... yes
+
+Checking GitLab ... Finished
+```
+
+## Rebuild authorized_keys file
+
+In some case it is necessary to rebuild the `authorized_keys` file.
+
+**Omnibus Installation**
+
+```
+sudo gitlab-rake gitlab:shell:setup
+```
+
+**Source Installation**
+
+```
+cd /home/git/gitlab
+sudo -u git -H bundle exec rake gitlab:shell:setup RAILS_ENV=production
+```
+
+```
+This will rebuild an authorized_keys file.
+You will lose any data stored in authorized_keys file.
+Do you want to continue (yes/no)? yes
+```
+
+## Clear redis cache
+
+If for some reason the dashboard shows wrong information you might want to
+clear Redis' cache.
+
+**Omnibus Installation**
+
+```
+sudo gitlab-rake cache:clear
+```
+
+**Source Installation**
+
+```
+cd /home/git/gitlab
+sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production
+```
+
+## Precompile the assets
+
+Sometimes during version upgrades you might end up with some wrong CSS or
+missing some icons. In that case, try to precompile the assets again.
+
+Note that this only applies to source installations and does NOT apply to
+Omnibus packages.
+
+**Source Installation**
+
+```
+cd /home/git/gitlab
+sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production
+```
+
+For omnibus versions, the unoptimized assets (JavaScript, CSS) are frozen at
+the release of upstream GitLab. The omnibus version includes optimized versions
+of those assets. Unless you are modifying the JavaScript / CSS code on your
+production machine after installing the package, there should be no reason to redo
+rake assets:precompile on the production machine. If you suspect that assets
+have been corrupted, you should reinstall the omnibus package.
+
+## Tracking Deployments
+
+GitLab provides a Rake task that lets you track deployments in GitLab
+Performance Monitoring. This Rake task simply stores the current GitLab version
+in the GitLab Performance Monitoring database.
+
+**Omnibus Installation**
+
+```
+sudo gitlab-rake gitlab:track_deployment
+```
+
+**Source Installation**
+
+```
+cd /home/git/gitlab
+sudo -u git -H bundle exec rake gitlab:track_deployment RAILS_ENV=production
+```
+
+## Create or repair repository hooks symlink
+
+If the GitLab shell hooks directory location changes or another circumstance
+leads to the hooks symlink becoming missing or invalid, run this Rake task
+to create or repair the symlinks.
+
+**Omnibus Installation**
+
+```
+sudo gitlab-rake gitlab:shell:create_hooks
+```
+
+**Source Installation**
+
+```
+cd /home/git/gitlab
+sudo -u git -H bundle exec rake gitlab:shell:create_hooks RAILS_ENV=production
+```
-- 
cgit v1.2.1


From c7dd62a0dae8a38a6104b2e4f771a7b324ac927b Mon Sep 17 00:00:00 2001
From: Daniel Axelrod <git@danonline.net>
Date: Tue, 1 Nov 2016 23:59:32 +0000
Subject: Fix gdb backtrace command

Correct the command to get a gdb backtrace from all threads. `apply` is
not a valid gdb command.

See https://sourceware.org/gdb/onlinedocs/gdb/Threads.html#Threads .
---
 doc/administration/troubleshooting/debug.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/administration')

diff --git a/doc/administration/troubleshooting/debug.md b/doc/administration/troubleshooting/debug.md
index d8dce4388e1..6f1356ddf8f 100644
--- a/doc/administration/troubleshooting/debug.md
+++ b/doc/administration/troubleshooting/debug.md
@@ -107,7 +107,7 @@ downtime. Otherwise skip to the next section.
 1. To see the current threads, run:
 
     ```
-    apply all thread bt
+    thread apply all bt
     ```
 
 1. Once you're done debugging with `gdb`, be sure to detach from the process and exit:
-- 
cgit v1.2.1


From e900e53aa530ce15a73a4bf88cafa304999a99e9 Mon Sep 17 00:00:00 2001
From: Lukas Erlacher <erlacher@in.tum.de>
Date: Sat, 29 Oct 2016 17:10:41 +0200
Subject: Show log corresponding to env in admin/logs

No matter which environment Gitlab was running as, the admin/logs view
always showed production.log. This commit selects the logfile based
on Rails.env.

- Rename ProductionLogger to EnvironmentLogger
- Make EnvironmentLogger logfile depend on env
- Update spinach test for log tabs
---
 doc/administration/logs.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

(limited to 'doc/administration')

diff --git a/doc/administration/logs.md b/doc/administration/logs.md
index 737b39db16c..d757a3c2a66 100644
--- a/doc/administration/logs.md
+++ b/doc/administration/logs.md
@@ -13,7 +13,8 @@ This guide talks about how to read and use these system log files.
 
 This file lives in `/var/log/gitlab/gitlab-rails/production.log` for
 omnibus package or in `/home/git/gitlab/log/production.log` for
-installations from source.
+installations from source. (When Gitlab is running in an environment
+other than production, the corresponding logfile is shown here.)
 
 It contains information about all performed requests. You can see the
 URL and type of request, IP address and what exactly parts of code were
-- 
cgit v1.2.1


From fa4f904f2564927b58df0a9a046140597c59a8c5 Mon Sep 17 00:00:00 2001
From: Nick Thomas <nick@gitlab.com>
Date: Thu, 3 Nov 2016 14:45:55 +0000
Subject: Document multiple repository storage paths

---
 .../img/repository_storages_admin_ui.png            | Bin 17081 -> 54043 bytes
 doc/administration/repository_storages.md           |   3 +++
 2 files changed, 3 insertions(+)

(limited to 'doc/administration')

diff --git a/doc/administration/img/repository_storages_admin_ui.png b/doc/administration/img/repository_storages_admin_ui.png
index 599350bc098..6481baca1ad 100644
Binary files a/doc/administration/img/repository_storages_admin_ui.png and b/doc/administration/img/repository_storages_admin_ui.png differ
diff --git a/doc/administration/repository_storages.md b/doc/administration/repository_storages.md
index 55b054fc1a4..ab70557b69a 100644
--- a/doc/administration/repository_storages.md
+++ b/doc/administration/repository_storages.md
@@ -91,6 +91,9 @@ be stored via the **Application Settings** in the Admin area.
 
 ![Choose repository storage path in Admin area](img/repository_storages_admin_ui.png)
 
+Beginning with GitLab 8.13.4, multiple paths can be chosen. New projects will be
+randomly placed on one of the selected paths.
+
 [ce-4578]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4578
 [restart gitlab]: restart_gitlab.md#installations-from-source
 [reconfigure gitlab]: restart_gitlab.md#omnibus-gitlab-reconfigure
-- 
cgit v1.2.1


From 6bcc52a53678ca68001189c801497862d3f6e758 Mon Sep 17 00:00:00 2001
From: Jacob Vosmaer <jacob@gitlab.com>
Date: Thu, 27 Oct 2016 14:59:52 +0200
Subject: Refine Git garbage collection

---
 doc/administration/housekeeping.md | 8 ++++++++
 1 file changed, 8 insertions(+)

(limited to 'doc/administration')

diff --git a/doc/administration/housekeeping.md b/doc/administration/housekeeping.md
index ad1fa98b63b..f846c06ca42 100644
--- a/doc/administration/housekeeping.md
+++ b/doc/administration/housekeeping.md
@@ -3,6 +3,14 @@
 > [Introduced][ce-2371] in GitLab 8.4.
 
 ---
+## Automatic housekeeping
+
+GitLab automatically runs `git gc` and `git repack` on repositories
+after Git pushes. If needed you can change how often this happens, or
+to turn it off, go to **Admin area > Settings**
+(`/admin/application_settings`).
+
+## Manual housekeeping
 
 The housekeeping function runs `git gc` ([man page][man]) on the current
 project Git repository.
-- 
cgit v1.2.1


From c76ff8cf32801198e93122fdcf689f3ac1987e41 Mon Sep 17 00:00:00 2001
From: Gabriel Mazetto <gabriel@gitlab.com>
Date: Thu, 22 Sep 2016 06:05:28 -0300
Subject: Improved redis sentinel documentation for CE

---
 doc/administration/high_availability/redis.md | 62 +++++++++++----------------
 1 file changed, 26 insertions(+), 36 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md
index bc424330656..e347959ebbc 100644
--- a/doc/administration/high_availability/redis.md
+++ b/doc/administration/high_availability/redis.md
@@ -143,6 +143,7 @@ the master, and `masterauth` in slaves.
     redis['port'] = 6379
 
     ## Slave redis instance
+    redis['master'] = false
     redis['master_ip'] = '10.10.10.10' # IP of master Redis server
     redis['master_port'] = 6379 # Port of master Redis server
     redis['master_password'] = "<huge password string here>"
@@ -157,31 +158,19 @@ servers.
 
 ### Sentinel setup
 
-We don't provide yet an automated way to setup and run the Sentinel daemon
-from Omnibus installation method. You must follow the instructions below and
-run it by yourself.
+We provide an automated way to setup and run the Sentinel daemon
+with GitLab EE.
 
-The support for Sentinel in Ruby has some [caveats](https://github.com/redis/redis-rb/issues/531).
-While you can give any name for the `master-group-name` part of the
-configuration, as in this example:
-
-```conf
-sentinel monitor <master-group-name> <ip> <port> <quorum>
-```
-
-,for it to work in Ruby, you have to use the "hostname" of the master Redis
-server, otherwise you will get an error message like:
-`Redis::CannotConnectError: No sentinels available.`. Read
-[Sentinel troubleshooting](#sentinel-troubleshooting) for more information.
+See the instructions below how to setup it by yourself.
 
 Here is an example configuration file (`sentinel.conf`) for a Sentinel node:
 
 ```conf
 port 26379
-sentinel monitor master-redis.example.com 10.10.10.10 6379 1
-sentinel down-after-milliseconds master-redis.example.com 10000
-sentinel config-epoch master-redis.example.com 0
-sentinel leader-epoch master-redis.example.com 0
+sentinel monitor gitlab-redis 10.0.0.1 6379 1
+sentinel down-after-milliseconds gitlab-redis 10000
+sentinel config-epoch gitlab-redis 0
+sentinel leader-epoch gitlab-redis 0
 ```
 
 ---
@@ -213,10 +202,11 @@ The following steps should be performed in the [GitLab application server](gitla
 1. Edit `/etc/gitlab/gitlab.rb` and add/change the following lines:
 
     ```ruby
-    gitlab-rails['redis_host'] = "master-redis.example.com"
-    gitlab-rails['redis_port'] = 6379
-    gitlab-rails['redis_password'] = '<huge password string here>'
-    gitlab-rails['redis_sentinels'] = [
+    redis['master_name'] = "gitlab-redis"
+    redis['master_ip'] = "10.0.0.1"
+    redis['master_port'] = 6379
+    redis['master_password'] = '<huge password string here>'
+    gitlab_rails['redis_sentinels'] = [
       {'host' => '10.10.10.1', 'port' => 26379},
       {'host' => '10.10.10.2', 'port' => 26379},
       {'host' => '10.10.10.3', 'port' => 26379}
@@ -229,33 +219,33 @@ The following steps should be performed in the [GitLab application server](gitla
 
 If you get an error like: `Redis::CannotConnectError: No sentinels available.`,
 there may be something wrong with your configuration files or it can be related
-to [this issue][gh-531] ([pull request][gh-534] that should make things better).
+to [this issue][gh-531].
 
-It's a bit rigid the way you have to config `resque.yml` and `sentinel.conf`,
-otherwise `redis-rb` will not work properly.
+It's a bit non-intuitive the way you have to config `resque.yml` and
+`sentinel.conf`, otherwise `redis-rb` will not work properly.
 
-The hostname ('my-primary-redis') of the primary Redis server (`sentinel.conf`)
-**must** match the one configured in GitLab (`resque.yml` for source installations
-or `gitlab-rails['redis_*']` in Omnibus) and it must be valid ex:
+The `master-group-name` ('gitlab-redis') defined in (`sentinel.conf`)
+**must** be used as the hostname in GitLab (`resque.yml` for source installations
+or `gitlab-rails['redis_*']` in Omnibus):
 
 ```conf
 # sentinel.conf:
-sentinel monitor my-primary-redis 10.10.10.10 6379 1
-sentinel down-after-milliseconds my-primary-redis 10000
-sentinel config-epoch my-primary-redis 0
-sentinel leader-epoch my-primary-redis 0
+sentinel monitor gitlab-redis 10.10.10.10 6379 1
+sentinel down-after-milliseconds gitlab-redis 10000
+sentinel config-epoch gitlab-redis 0
+sentinel leader-epoch gitlab-redis 0
 ```
 
 ```yaml
 # resque.yaml
 production:
-  url: redis://my-primary-redis:6378
+  url: redis://:myredispassword@gitlab-redis/
   sentinels:
     -
-      host: slave1
+      host: slave1.example.com # or use ip
       port: 26380 # point to sentinel, not to redis port
     -
-      host: slave2
+      host: slave2.exampl.com # or use ip
       port: 26381 # point to sentinel, not to redis port
 ```
 
-- 
cgit v1.2.1


From f6d29583b02ffbb35b3c344f78b5a3575bf9c656 Mon Sep 17 00:00:00 2001
From: Gabriel Mazetto <gabriel@gitlab.com>
Date: Fri, 7 Oct 2016 01:16:32 +0200
Subject: Small fixes on Sentinel documentation for CE

---
 doc/administration/high_availability/redis.md | 2 --
 1 file changed, 2 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md
index e347959ebbc..69184ae9723 100644
--- a/doc/administration/high_availability/redis.md
+++ b/doc/administration/high_availability/redis.md
@@ -203,8 +203,6 @@ The following steps should be performed in the [GitLab application server](gitla
 
     ```ruby
     redis['master_name'] = "gitlab-redis"
-    redis['master_ip'] = "10.0.0.1"
-    redis['master_port'] = 6379
     redis['master_password'] = '<huge password string here>'
     gitlab_rails['redis_sentinels'] = [
       {'host' => '10.10.10.1', 'port' => 26379},
-- 
cgit v1.2.1


From f54d60b41df3d30181a371d3799fa8b9451d4c5b Mon Sep 17 00:00:00 2001
From: Gabriel Mazetto <gabriel@gitlab.com>
Date: Fri, 7 Oct 2016 01:47:22 +0200
Subject: Updated password examples and improved omnibus troubleshooting

---
 doc/administration/high_availability/redis.md | 23 +++++++++++++++++++----
 1 file changed, 19 insertions(+), 4 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md
index 69184ae9723..9fca7bfb8b4 100644
--- a/doc/administration/high_availability/redis.md
+++ b/doc/administration/high_availability/redis.md
@@ -45,7 +45,7 @@ Redis.
     redis['bind'] = '0.0.0.0'
 
     # If you wish to use Redis authentication (recommended)
-    redis['password'] = 'Redis Password'
+    redis['password'] = 'redis-password-goes-here'
     ```
 
 1. Run `sudo gitlab-ctl reconfigure` to install and configure PostgreSQL.
@@ -132,7 +132,7 @@ the master, and `masterauth` in slaves.
     redis['port'] = 6379
 
     ## Master redis instance
-    redis['password'] = '<huge password string here>'
+    redis['password'] = 'redis-password-goes-here'
     ```
 
 1. Edit `/etc/gitlab/gitlab.rb` of a slave Redis machine (should be one or more machines):
@@ -146,7 +146,7 @@ the master, and `masterauth` in slaves.
     redis['master'] = false
     redis['master_ip'] = '10.10.10.10' # IP of master Redis server
     redis['master_port'] = 6379 # Port of master Redis server
-    redis['master_password'] = "<huge password string here>"
+    redis['master_password'] = "redis-password-goes-here"
     ```
 
 1. Reconfigure the GitLab for the changes to take effect: `sudo gitlab-ctl reconfigure`
@@ -203,7 +203,7 @@ The following steps should be performed in the [GitLab application server](gitla
 
     ```ruby
     redis['master_name'] = "gitlab-redis"
-    redis['master_password'] = '<huge password string here>'
+    redis['master_password'] = 'redis-password-goes-here'
     gitlab_rails['redis_sentinels'] = [
       {'host' => '10.10.10.1', 'port' => 26379},
       {'host' => '10.10.10.2', 'port' => 26379},
@@ -215,6 +215,21 @@ The following steps should be performed in the [GitLab application server](gitla
 
 ### Sentinel troubleshooting
 
+#### Omnibus install
+
+If you get an error like: `Redis::CannotConnectError: No sentinels available.`,
+there may be something wrong with your configuration files or it can be related
+to [this issue][gh-531].
+
+You must make sure you are defining the same value in `redis['master_name']`
+and `redis['master_pasword']` as you defined for your sentinel node.
+
+The way the redis connector `redis-rb` works with sentinel is a bit
+non-intuitive. We try to hide the complexity in omnibus, but it still requires
+a few extra configs.
+
+#### Source install
+
 If you get an error like: `Redis::CannotConnectError: No sentinels available.`,
 there may be something wrong with your configuration files or it can be related
 to [this issue][gh-531].
-- 
cgit v1.2.1


From c4d3c0de1f489639e1e2f1a12b7b4d88384d3e06 Mon Sep 17 00:00:00 2001
From: Gabriel Mazetto <gabriel@gitlab.com>
Date: Sat, 15 Oct 2016 05:40:15 +0200
Subject: Improved documentation on HA sentinel part and Redis replication
 troubleshooting.

---
 doc/administration/high_availability/redis.md | 316 +++++++++++++++++++++-----
 1 file changed, 256 insertions(+), 60 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md
index 9fca7bfb8b4..840f5896bd7 100644
--- a/doc/administration/high_availability/redis.md
+++ b/doc/administration/high_availability/redis.md
@@ -8,6 +8,27 @@ that comes bundled with GitLab Omnibus packages.
   information. We recommend using a combination of a Redis password and tight
   firewall rules to secure your Redis service.
 
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**
+
+- [Configure your own Redis server](#configure-your-own-redis-server)
+- [Configure Redis using Omnibus](#configure-redis-using-omnibus)
+- [Experimental Redis Sentinel support](#experimental-redis-sentinel-support)
+  - [Redis setup](#redis-setup)
+    - [Source install](#source-install)
+    - [Omnibus Install](#omnibus-install)
+    - [Troubleshooting Replication](#troubleshooting-replication)
+  - [Sentinel](#sentinel)
+    - [Sentinel setup (Community Edition)](#sentinel-setup-community-edition)
+    - [Sentinel setup (EE Only)](#sentinel-setup-ee-only)
+  - [GitLab setup](#gitlab-setup)
+  - [Sentinel troubleshooting](#sentinel-troubleshooting)
+    - [Omnibus install](#omnibus-install)
+    - [Source install](#source-install-1)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 ## Configure your own Redis server
 
 If you're hosting GitLab on a cloud provider, you can optionally use a
@@ -37,6 +58,7 @@ Redis.
     unicorn['enable'] = false
     sidekiq['enable'] = false
     postgresql['enable'] = false
+    gitlab_rails['enable'] = false
     gitlab_workhorse['enable'] = false
     mailroom['enable'] = false
 
@@ -59,120 +81,294 @@ Redis.
 
 ## Experimental Redis Sentinel support
 
-> [Introduced][ce-1877] in GitLab 8.11.
+> [Introduced][ce-1877] in GitLab 8.11, improved in 8.13.
 
 Since GitLab 8.11, you can configure a list of Redis Sentinel servers that
 will monitor a group of Redis servers to provide you with a standard failover
 support.
 
-There is currently one exception to the Sentinel support: `mail_room`, the
-component that processes incoming emails. It doesn't support Sentinel yet, but
-we hope to integrate a future release that does support it.
-
 To get a better understanding on how to correctly setup Sentinel, please read
 the [Redis Sentinel documentation](http://redis.io/topics/sentinel) first, as
 failing to configure it correctly can lead to data loss.
 
+Redis Sentinel can handle the most important tasks in a HA environment to help
+keep servers online with minimal to no downtime:
+
+- Monitors master and slave instances to see if they are available
+- Promote a slave to master when the master fails.
+- Demote a master to slave when failed master comes back online (to prevent
+  data-partitioning).
+- Can be queried by clients to always connect to the correct master server.
+
+There is currently one exception to the Sentinel support: `mail_room`, the
+component that processes incoming emails. It doesn't support Sentinel yet, but
+we hope to integrate a future release that does support it soon.
+
 The configuration consists of three parts:
 
-- Redis setup
-- Sentinel setup
-- GitLab setup
+- Setup Redis Master and Slave nodes
+- Setup Sentinel nodes
+- Setup GitLab
+
+> **IMPORTANT**: You need at least 3 independent machines: physical, or VMs
+running into distinct physical machines. If you fail to provision the
+machines in that specific way, any issue with the shared environment can
+bring your entire setup down.
 
 Read carefully how to configure those components below.
 
 ### Redis setup
 
-You must have at least 2 Redis servers: 1 Master, 1 or more Slaves.
+You must have at least `3` Redis servers: `1` Master, `2` Slaves, and they need to
+be each in a independent machine (see explanation above).
+
 They should be configured the same way and with similar server specs, as
-in a failover situation, any Slave can be elected as the new Master by
+in a failover situation, any `Slave` can be elected as the new `Master` by
 the Sentinel servers.
 
-In a minimal setup, the only required change for the slaves in `redis.conf`
-is the addition of a `slaveof` line pointing to the initial master.
-You can increase the security by defining a `requirepass` configuration in
-the master, and `masterauth` in slaves.
+With Sentinel, you must define a password to protect the access as both
+Sentinel instances and other redis instances should be able to talk to
+each other over the network.
 
----
+You'll need to define both `requirepass` and `masterauth` in all
+nodes because they can be re-configured at any time by the Sentinels
+during a failover, and change it's status as `Master` or `Slave`.
 
-**Configuring your own Redis server**
+Initial `Slave` nodes will have in `redis.conf` an additional `slaveof` line
+pointing to the initial `Master`.
 
-1. Add to the slaves' `redis.conf`:
+#### Source install
 
-    ```conf
-    # IP and port of the master Redis server
-    slaveof 10.10.10.10 6379
-    ```
+**Master Redis instance**
 
-1. Optionally, set up password authentication for increased security.
-   Add the following to master's `redis.conf`:
+You need to make the following changes in `redis.conf`:
 
-    ```conf
-    # Optional password authentication for increased security
-    requirepass "<password>"
-    ```
+1. Define a `bind` address pointing to a local IP that your other machines
+   can reach you. If you really need to bind to an external acessible IP, make
+   sure you add extra firewall rules to prevent unauthorized access:
 
-1. Then add this line to all the slave servers' `redis.conf`:
+   ```conf
+   # By default, if no "bind" configuration directive is specified, Redis listens
+   # for connections from all the network interfaces available on the server.
+   # It is possible to listen to just one or multiple selected interfaces using
+   # the "bind" configuration directive, followed by one or more IP addresses.
+   #
+   # Examples:
+   #
+   # bind 192.168.1.100 10.0.0.1
+   # bind 127.0.0.1 ::1
+   bind 0.0.0.0 # This will bind to all interfaces
+   ```
+
+1. Define a `port` to force redis to listin on TCP so other machines can
+   connect to it:
+
+   ```conf
+   # Accept connections on the specified port, default is 6379 (IANA #815344).
+   # If port 0 is specified Redis will not listen on a TCP socket.
+   port 6379
+   ```
+
+1. Set up password authentication (use the same password in all nodes)
 
     ```conf
-    masterauth "<password>"
+    requirepass "redis-password-goes-here"
+    masterauth "redis-password-goes-here"
     ```
 
 1. Restart the Redis services for the changes to take effect.
 
----
+**Slave Redis instance**
 
-**Using Redis via Omnibus**
+1. Follow same instructions from master with the extra change in `redis.conf`:
 
-1. Edit `/etc/gitlab/gitlab.rb` of a master Redis machine (usualy a single machine):
+   ```conf
+   # IP and port of the master Redis server
+   slaveof 10.10.10.10 6379
+   ```
 
-    ```ruby
-    ## Redis TCP support (will disable UNIX socket transport)
-    redis['bind'] = '0.0.0.0' # or specify an IP to bind to a single one
-    redis['port'] = 6379
+1. Restart the Redis services for the changes to take effect.
 
-    ## Master redis instance
-    redis['password'] = 'redis-password-goes-here'
-    ```
+#### Omnibus Install
 
-1. Edit `/etc/gitlab/gitlab.rb` of a slave Redis machine (should be one or more machines):
+You need to install the omnibus package in 3 different and independent machines.
+We will elect one as the initial `Master` and the other 2 as `Slaves`.
 
-    ```ruby
-    ## Redis TCP support (will disable UNIX socket transport)
-    redis['bind'] = '0.0.0.0' # or specify an IP to bind to a single one
-    redis['port'] = 6379
+If you are migrating from a single machine install, you may want to setup the
+machines as Slaves, pointing to the original machine as `Master`, to migrate
+the data first, and than switch to this setup.
 
-    ## Slave redis instance
-    redis['master'] = false
-    redis['master_ip'] = '10.10.10.10' # IP of master Redis server
-    redis['master_port'] = 6379 # Port of master Redis server
-    redis['master_password'] = "redis-password-goes-here"
-    ```
+To disable redis in the single install, edit `/etc/gitlab/gitlab.rb`:
+
+```ruby
+redis['enable'] = false
+```
+
+**Master Redis instances**
+
+You need to make the following changes in `/etc/gitlab/gitlab.rb`:
+
+1. Define a `redis['bind']` address pointing to a local IP that your other machines
+   can reach you. If you really need to bind to an external acessible IP, make
+   sure you add extra firewall rules to prevent unauthorized access.
+1. Define a `redis['port']` to force redis to listin on TCP so other machines can
+   connect to it.
+1. Set up password authentication with `redis['master_password']` (use the same
+   password in all nodes).
 
-1. Reconfigure the GitLab for the changes to take effect: `sudo gitlab-ctl reconfigure`
+```ruby
+## Redis TCP support (will disable UNIX socket transport)
+redis['bind'] = '0.0.0.0' # or specify an IP to bind to a single one
+redis['port'] = 6379
+redis['requirepass'] = 'redis-password-goes-here'
+redis['master_password'] = 'redis-password-goes-here'
+```
+
+Reconfigure GitLab Omnibus for the changes to take effect: `sudo gitlab-ctl reconfigure`
+
+**Slave Redis instances**
+
+You need to make the same changes listed for the `Master` instance,
+with an additional `Slave` section as in the example below:
+
+```ruby
+## Redis TCP support (will disable UNIX socket transport)
+redis['bind'] = '0.0.0.0' # or specify an IP to bind to a single one
+redis['port'] = 6379
+redis['requirepass'] = 'redis-password-goes-here'
+redis['master_password'] = 'redis-password-goes-here'
+
+## Slave redis instance
+redis['master'] = false
+redis['master_ip'] = '10.10.10.10' # IP of master Redis server
+redis['master_port'] = 6379 # Port of master Redis server
+```
+
+Reconfigure GitLab Omnibus for the changes to take effect: `sudo gitlab-ctl reconfigure`
+
+#### Troubleshooting Replication
+
+You can check if everything is correct by connecting to each server using
+`redis-cli` application, and sending the `INFO` command.
+
+If authentication was correctly defined, it should fail with:
+`NOAUTH Authentication required` error. Try to authenticate with the
+previous defined password with `AUTH redis-password-goes-here` and
+try the `INFO` command again.
+
+Look for the `# Replication` section where you should see some important
+information like the `role` of the server.
+
+When connected to a `master` redis, you will see the number of connected
+`slaves`, and a list of each with connection details.
+
+When it's a `slave`, you will see details of the master connection and if
+its `up` or `down`.
 
 ---
 
 Now that the Redis servers are all set up, let's configure the Sentinel
 servers.
 
-### Sentinel setup
+If you are not sure if your Redis servers are working and replicating
+correctly, please read the [Troubleshooting  Replication](#troubleshooting-replication)
+and fix it before proceeding with Sentinel setup.
+
+### Sentinel
+
+You must have at least `3` Redis Sentinel servers, and they need to
+be each in a independent machine. You can install them in the same
+machines you installed the other `3` Redis servers.
+
+This number is required for the consensus algorithm to be effective
+in the case of a failure. You should always have and `odd` number
+of Sentinel nodes provisioned.
 
-We provide an automated way to setup and run the Sentinel daemon
-with GitLab EE.
+Here is a simple explanation on how Sentinel handles a failover:
 
-See the instructions below how to setup it by yourself.
+When a number of Sentinels (`quorum` value) agree the fact the `master` is
+not reachable, the **majority** of the sentinels must elect a temporary
+Sentinel `leader`, that will be responsible to start the failover proceedings.
 
-Here is an example configuration file (`sentinel.conf`) for a Sentinel node:
+As an example, for a cluster of `3` Sentinels, at least `2` must agree on a
+`leader`. If you have total of `5` at least `3` must agree on the leader.
+
+The `quorum` is only used to detect failure, not to elect the `leader`.
+
+Official [Sentinel documentation](http://redis.io/topics/sentinel#example-sentinel-deployments)
+also lists different network topologies and warns againts situations like
+network partition and how it can affect the state of the HA solution. Make
+sure you read it carefully and understand the implications in your current
+setup.
+
+To make Sentinel setup easier, ee provide an [automated way to setup and run](#sentinel-setup-ee-only)
+the Sentinel daemon with GitLab EE.
+
+#### Sentinel setup (Community Edition)
+
+For GitLab CE, you need to install, configure, execute and monitor Sentinel
+by yourself.
+
+Here is an example configuration file (`sentinel.conf`) for a minimal Sentinel
+node:
 
 ```conf
-port 26379
-sentinel monitor gitlab-redis 10.0.0.1 6379 1
+bind 0.0.0.0 # bind to all interfaces or change to a specific IP
+port 26379 # default sentinel port
+sentinel auth-pass gitlab-redis redis-password-goes-here
+sentinel monitor gitlab-redis 10.0.0.1 6379 2
 sentinel down-after-milliseconds gitlab-redis 10000
 sentinel config-epoch gitlab-redis 0
 sentinel leader-epoch gitlab-redis 0
 ```
 
+#### Sentinel setup (EE Only)
+
+To setup sentinel, you must edit `/etc/gitlab/gitlab.rb` file.
+This is a minimal configuration required to run the daemon:
+
+```ruby
+redis['master_name'] = 'gitlab-redis' # must be the same in every sentinel node
+redis['master_ip'] = '10.0.0.1' # ip of the initial master redis instance
+redis['master_port'] = 6379 # port of the initial master redis instance
+redis['master_password'] = 'your-secure-password-here' # the same value defined in redis['password'] in the master instance
+
+sentinel['enable'] = true
+# sentinel['port'] = 26379
+
+## Quorum must reflect the amount of voting sentinels it take to start a failover.
+sentinel['quorum'] = 2
+
+## Consider unresponsive server down after x amount of ms.
+# sentinel['down_after_milliseconds'] = 10000
+
+# sentinel['failover_timeout'] = 60000
+```
+
+When you install Sentinel in a separate machine, you need to control which
+other services will be running in it. Take a look at the following variables
+and enable or disable whenever it fits your strategy:
+
+```ruby
+# Enabled Redis and Sentinel services
+redis['enable'] = true
+sentinel['enable'] = true
+
+# Disabled all other services
+redis['enable'] = false
+bootstrap['enable'] = false
+nginx['enable'] = false
+unicorn['enable'] = false
+sidekiq['enable'] = false
+postgresql['enable'] = false
+gitlab_workhorse['enable'] = false
+gitlab_rails['enable'] = false
+mailroom['enable'] = false
+```
+
+Remember that enabling a new service may also require additional configuration
+params (like `redis` for example).
+
 ---
 
 The final part is to inform the main GitLab application server of the Redis
@@ -243,7 +439,7 @@ or `gitlab-rails['redis_*']` in Omnibus):
 
 ```conf
 # sentinel.conf:
-sentinel monitor gitlab-redis 10.10.10.10 6379 1
+sentinel monitor gitlab-redis 10.10.10.10 6379 2
 sentinel down-after-milliseconds gitlab-redis 10000
 sentinel config-epoch gitlab-redis 0
 sentinel leader-epoch gitlab-redis 0
@@ -276,7 +472,7 @@ To make sure your configuration is correct:
     sudo gitlab-rails console
 
     # For source installations
-    sudo -u git rails console RAILS_ENV=production
+    sudo -u git rails console production
     ```
 
 1. Run in the console:
-- 
cgit v1.2.1


From 3242ea6d40442f19c3932715521864ac5eb3700b Mon Sep 17 00:00:00 2001
From: Gabriel Mazetto <gabriel@gitlab.com>
Date: Tue, 18 Oct 2016 19:45:57 +0200
Subject: Improved Redis HA and Sentinel documentation.

---
 doc/administration/high_availability/redis.md | 327 +++++++++++++++++---------
 1 file changed, 210 insertions(+), 117 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md
index 840f5896bd7..29bf2c54a08 100644
--- a/doc/administration/high_availability/redis.md
+++ b/doc/administration/high_availability/redis.md
@@ -1,7 +1,7 @@
 # Configuring Redis for GitLab HA
 
 You can choose to install and manage Redis yourself, or you can use the one
-that comes bundled with GitLab Omnibus packages.
+that comes bundled with Omnibus GitLab packages.
 
 > **Note:** Redis does not require authentication by default. See
   [Redis Security](http://redis.io/topics/security) documentation for more
@@ -15,17 +15,22 @@ that comes bundled with GitLab Omnibus packages.
 - [Configure your own Redis server](#configure-your-own-redis-server)
 - [Configure Redis using Omnibus](#configure-redis-using-omnibus)
 - [Experimental Redis Sentinel support](#experimental-redis-sentinel-support)
+- [Redis Sentinel support](#redis-sentinel-support)
   - [Redis setup](#redis-setup)
-    - [Source install](#source-install)
-    - [Omnibus Install](#omnibus-install)
-    - [Troubleshooting Replication](#troubleshooting-replication)
-  - [Sentinel](#sentinel)
-    - [Sentinel setup (Community Edition)](#sentinel-setup-community-edition)
-    - [Sentinel setup (EE Only)](#sentinel-setup-ee-only)
+    - [Existing single-machine installation](#existing-single-machine-installation)
+    - [Installation from source](#installation-from-source)
+    - [Omnibus packages](#omnibus-packages)
+  - [Configuring Sentinel](#configuring-sentinel)
+    - [How sentinel handles a failover](#how-sentinel-handles-a-failover)
+    - [Sentinel setup](#sentinel-setup)
+      - [Community Edition](#community-edition)
+      - [Enterprise Edition](#enterprise-edition)
   - [GitLab setup](#gitlab-setup)
-  - [Sentinel troubleshooting](#sentinel-troubleshooting)
+- [Troubleshooting](#troubleshooting)
+  - [Redis replication](#redis-replication)
+  - [Sentinel](#sentinel)
     - [Omnibus install](#omnibus-install)
-    - [Source install](#source-install-1)
+    - [Source install](#source-install)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -41,7 +46,7 @@ If you don't want to bother setting up your own Redis server, you can use the
 one bundled with Omnibus. In this case, you should disable all services except
 Redis.
 
-1. Download/install GitLab Omnibus using **steps 1 and 2** from
+1. Download/install Omnibus GitLab using **steps 1 and 2** from
    [GitLab downloads](https://about.gitlab.com/downloads). Do not complete other
    steps on the download page.
 1. Create/edit `/etc/gitlab/gitlab.rb` and use the following configuration.
@@ -70,7 +75,7 @@ Redis.
     redis['password'] = 'redis-password-goes-here'
     ```
 
-1. Run `sudo gitlab-ctl reconfigure` to install and configure PostgreSQL.
+1. Run `sudo gitlab-ctl reconfigure` to install and configure Redis.
 
     > **Note**: This `reconfigure` step will result in some errors.
       That's OK - don't be alarmed.
@@ -81,7 +86,12 @@ Redis.
 
 ## Experimental Redis Sentinel support
 
-> [Introduced][ce-1877] in GitLab 8.11, improved in 8.13.
+   > Experimental Redis Sentinel support was [Introduced][ce-1877] in GitLab 8.11.
+     Starting with 8.13, Redis Sentinel is no longer experimental.
+     If you used with versions `< 8.13` before, please check the updated
+     documentation below.
+
+## Redis Sentinel support
 
 Since GitLab 8.11, you can configure a list of Redis Sentinel servers that
 will monitor a group of Redis servers to provide you with a standard failover
@@ -100,20 +110,19 @@ keep servers online with minimal to no downtime:
   data-partitioning).
 - Can be queried by clients to always connect to the correct master server.
 
-There is currently one exception to the Sentinel support: `mail_room`, the
-component that processes incoming emails. It doesn't support Sentinel yet, but
-we hope to integrate a future release that does support it soon.
-
 The configuration consists of three parts:
 
 - Setup Redis Master and Slave nodes
 - Setup Sentinel nodes
 - Setup GitLab
 
-> **IMPORTANT**: You need at least 3 independent machines: physical, or VMs
-running into distinct physical machines. If you fail to provision the
-machines in that specific way, any issue with the shared environment can
-bring your entire setup down.
+### Prerequisites
+
+You need at least `3` independent machines: physical, or VMs running into
+distinct physical machines.
+
+If you fail to provision the machines in that specific way, any issue with
+the shared environment can bring your entire setup down.
 
 Read carefully how to configure those components below.
 
@@ -131,15 +140,35 @@ Sentinel instances and other redis instances should be able to talk to
 each other over the network.
 
 You'll need to define both `requirepass` and `masterauth` in all
-nodes because they can be re-configured at any time by the Sentinels
-during a failover, and change it's status as `Master` or `Slave`.
+nodes. At any time during a failover the Sentinels can reconfigure a node
+and change it's status from `Master` to `Slave` and vice versa.
 
-Initial `Slave` nodes will have in `redis.conf` an additional `slaveof` line
+Initial `Slave` nodes require an additional `slaveof` setting in `redis.conf`
 pointing to the initial `Master`.
 
-#### Source install
+#### Existing single-machine installation
+
+If you already have a single-machine GitLab install running, you will need to
+replicate from this machine first, before de-activating the Redis instance
+inside it.
+
+Your single-machine install will be the initial `Master`, and the `3` others
+should be configured as `Slave` pointing to this machine.
+
+After replication catchs-up, you will need to stop services in the
+single-machine install, to rotate the `Master` to one of the new nodes.
+
+Make the required changes in configuration and restart the new nodes again.
+
+To disable redis in the single install, edit `/etc/gitlab/gitlab.rb`:
 
-**Master Redis instance**
+```ruby
+redis['enable'] = false
+```
+
+#### Installation from source
+
+**Configuring Master Redis instance**
 
 You need to make the following changes in `redis.conf`:
 
@@ -178,9 +207,9 @@ You need to make the following changes in `redis.conf`:
 
 1. Restart the Redis services for the changes to take effect.
 
-**Slave Redis instance**
+**Configuring Slave Redis instance**
 
-1. Follow same instructions from master with the extra change in `redis.conf`:
+1. Follow same instructions from master, with the extra change in `redis.conf`:
 
    ```conf
    # IP and port of the master Redis server
@@ -189,33 +218,24 @@ You need to make the following changes in `redis.conf`:
 
 1. Restart the Redis services for the changes to take effect.
 
-#### Omnibus Install
-
-You need to install the omnibus package in 3 different and independent machines.
-We will elect one as the initial `Master` and the other 2 as `Slaves`.
+#### Omnibus packages
 
-If you are migrating from a single machine install, you may want to setup the
-machines as Slaves, pointing to the original machine as `Master`, to migrate
-the data first, and than switch to this setup.
-
-To disable redis in the single install, edit `/etc/gitlab/gitlab.rb`:
-
-```ruby
-redis['enable'] = false
-```
+You need to install the Omnibus GitLab package in `3` independent machines.
 
-**Master Redis instances**
+**Configuring Master Redis instance**
 
-You need to make the following changes in `/etc/gitlab/gitlab.rb`:
+You will need to configure the following:
 
 1. Define a `redis['bind']` address pointing to a local IP that your other machines
    can reach you. If you really need to bind to an external acessible IP, make
    sure you add extra firewall rules to prevent unauthorized access.
-1. Define a `redis['port']` to force redis to listin on TCP so other machines can
-   connect to it.
-1. Set up password authentication with `redis['master_password']` (use the same
+1. Define a `redis['port']` so redis can listen for TCP requests which will
+   allow other machines to connect to it.
+1. Set up a password authentication with `redis['master_password']` (use the same
    password in all nodes).
 
+In `/etc/gitlab/gitlab.rb`:
+
 ```ruby
 ## Redis TCP support (will disable UNIX socket transport)
 redis['bind'] = '0.0.0.0' # or specify an IP to bind to a single one
@@ -224,15 +244,14 @@ redis['requirepass'] = 'redis-password-goes-here'
 redis['master_password'] = 'redis-password-goes-here'
 ```
 
-Reconfigure GitLab Omnibus for the changes to take effect: `sudo gitlab-ctl reconfigure`
+Reconfigure Omnibus GitLab for the changes to take effect: `sudo gitlab-ctl reconfigure`
 
-**Slave Redis instances**
+**Configuring Slave Redis instances**
 
 You need to make the same changes listed for the `Master` instance,
 with an additional `Slave` section as in the example below:
 
 ```ruby
-## Redis TCP support (will disable UNIX socket transport)
 redis['bind'] = '0.0.0.0' # or specify an IP to bind to a single one
 redis['port'] = 6379
 redis['requirepass'] = 'redis-password-goes-here'
@@ -244,26 +263,7 @@ redis['master_ip'] = '10.10.10.10' # IP of master Redis server
 redis['master_port'] = 6379 # Port of master Redis server
 ```
 
-Reconfigure GitLab Omnibus for the changes to take effect: `sudo gitlab-ctl reconfigure`
-
-#### Troubleshooting Replication
-
-You can check if everything is correct by connecting to each server using
-`redis-cli` application, and sending the `INFO` command.
-
-If authentication was correctly defined, it should fail with:
-`NOAUTH Authentication required` error. Try to authenticate with the
-previous defined password with `AUTH redis-password-goes-here` and
-try the `INFO` command again.
-
-Look for the `# Replication` section where you should see some important
-information like the `role` of the server.
-
-When connected to a `master` redis, you will see the number of connected
-`slaves`, and a list of each with connection details.
-
-When it's a `slave`, you will see details of the master connection and if
-its `up` or `down`.
+Reconfigure Omnibus GitLab for the changes to take effect: `sudo gitlab-ctl reconfigure`
 
 ---
 
@@ -274,26 +274,29 @@ If you are not sure if your Redis servers are working and replicating
 correctly, please read the [Troubleshooting  Replication](#troubleshooting-replication)
 and fix it before proceeding with Sentinel setup.
 
-### Sentinel
+### Configuring Sentinel
 
 You must have at least `3` Redis Sentinel servers, and they need to
-be each in a independent machine. You can install them in the same
-machines you installed the other `3` Redis servers.
+be each in a independent machine. You can configure them in the same
+machines where you've configured the other Redis servers.
 
 This number is required for the consensus algorithm to be effective
-in the case of a failure. You should always have and `odd` number
-of Sentinel nodes provisioned.
+in the case of a failure. **You should always have and `odd` number
+of Sentinel nodes provisioned**.
+
+#### How sentinel handles a failover
 
-Here is a simple explanation on how Sentinel handles a failover:
+If (`quorum` value of) Sentinels  agree the fact the `master` is not reachable,
+Sentinels will try to elect a temporary `Leader`. The **Majority** of the
+Sentinels must agree to start a failover.
 
-When a number of Sentinels (`quorum` value) agree the fact the `master` is
-not reachable, the **majority** of the sentinels must elect a temporary
-Sentinel `leader`, that will be responsible to start the failover proceedings.
+If you don't have the **Majority** of the Sentinels online (for example if you
+are under a network partitioning), a failover **will not be started**.
 
-As an example, for a cluster of `3` Sentinels, at least `2` must agree on a
-`leader`. If you have total of `5` at least `3` must agree on the leader.
+For example, for a cluster of `3` Sentinels, at least `2` must agree on a
+`Leader`. If you have total of `5` at least `3` must agree on a `Leader`.
 
-The `quorum` is only used to detect failure, not to elect the `leader`.
+The `quorum` is only used to detect failure, not to elect the `Leader`.
 
 Official [Sentinel documentation](http://redis.io/topics/sentinel#example-sentinel-deployments)
 also lists different network topologies and warns againts situations like
@@ -301,16 +304,16 @@ network partition and how it can affect the state of the HA solution. Make
 sure you read it carefully and understand the implications in your current
 setup.
 
-To make Sentinel setup easier, ee provide an [automated way to setup and run](#sentinel-setup-ee-only)
-the Sentinel daemon with GitLab EE.
+GitLab Enterprise Edition provides [automated way to setup and run](#sentinel-setup-ee-only) the Sentinel daemon.
 
-#### Sentinel setup (Community Edition)
+#### Sentinel setup
 
-For GitLab CE, you need to install, configure, execute and monitor Sentinel
-by yourself.
+##### Community Edition
+With GitLab Community Edition, you need to install, configure, execute and
+monitor Sentinel from source. Omnibus GitLab Community Edition package does
+not support Sentinel configuration.
 
-Here is an example configuration file (`sentinel.conf`) for a minimal Sentinel
-node:
+A minimal configuration file (`sentinel.conf`) should contain the following:
 
 ```conf
 bind 0.0.0.0 # bind to all interfaces or change to a specific IP
@@ -322,35 +325,17 @@ sentinel config-epoch gitlab-redis 0
 sentinel leader-epoch gitlab-redis 0
 ```
 
-#### Sentinel setup (EE Only)
+##### Enterprise Edition
 
-To setup sentinel, you must edit `/etc/gitlab/gitlab.rb` file.
-This is a minimal configuration required to run the daemon:
+To setup sentinel, you edit `/etc/gitlab/gitlab.rb` file:
 
 ```ruby
-redis['master_name'] = 'gitlab-redis' # must be the same in every sentinel node
-redis['master_ip'] = '10.0.0.1' # ip of the initial master redis instance
-redis['master_port'] = 6379 # port of the initial master redis instance
-redis['master_password'] = 'your-secure-password-here' # the same value defined in redis['password'] in the master instance
 
-sentinel['enable'] = true
-# sentinel['port'] = 26379
+## When you install Sentinel in a separate machine, you need to control which
+## other services will be running in it. Take a look at the following variables
+## and enable or disable whenever it fits your strategy:
 
-## Quorum must reflect the amount of voting sentinels it take to start a failover.
-sentinel['quorum'] = 2
-
-## Consider unresponsive server down after x amount of ms.
-# sentinel['down_after_milliseconds'] = 10000
-
-# sentinel['failover_timeout'] = 60000
-```
-
-When you install Sentinel in a separate machine, you need to control which
-other services will be running in it. Take a look at the following variables
-and enable or disable whenever it fits your strategy:
-
-```ruby
-# Enabled Redis and Sentinel services
+## Enabled Redis and Sentinel services
 redis['enable'] = true
 sentinel['enable'] = true
 
@@ -364,10 +349,53 @@ postgresql['enable'] = false
 gitlab_workhorse['enable'] = false
 gitlab_rails['enable'] = false
 mailroom['enable'] = false
-```
 
-Remember that enabling a new service may also require additional configuration
-params (like `redis` for example).
+## Configure Redis
+redis['master_name'] = 'gitlab-redis' # must be the same in every sentinel node
+redis['master_ip'] = '10.0.0.1' # ip of the initial master redis instance
+redis['master_port'] = 6379 # port of the initial master redis instance
+redis['master_password'] = 'your-secure-password-here' # the same value defined in redis['password'] in the master instance
+
+## Configure Sentinel
+# sentinel['port'] = 26379 # uncomment to change default port
+
+## Quorum must reflect the amount of voting sentinels it take to start a failover.
+## Value must NOT be greater then the ammount of sentinels.
+##
+## The quorum can be used to tune Sentinel in two ways:
+## 1. If a the quorum is set to a value smaller than the majority of Sentinels
+##    we deploy, we are basically making Sentinel more sensible to master failures,
+##    triggering a failover as soon as even just a minority of Sentinels is no longer
+##    able to talk with the master.
+## 1. If a quorum is set to a value greater than the majority of Sentinels, we are
+##    making Sentinel able to failover only when there are a very large number (larger
+##    than majority) of well connected Sentinels which agree about the master being down.s
+sentinel['quorum'] = 2
+
+## Consider unresponsive server down after x amount of ms.
+# sentinel['down_after_milliseconds'] = 10000
+
+## Specifies the failover timeout in milliseconds. It is used in many ways:
+##
+## - The time needed to re-start a failover after a previous failover was
+##   already tried against the same master by a given Sentinel, is two
+##   times the failover timeout.
+##
+## - The time needed for a slave replicating to a wrong master according
+##   to a Sentinel current configuration, to be forced to replicate
+##   with the right master, is exactly the failover timeout (counting since
+##   the moment a Sentinel detected the misconfiguration).
+##
+## - The time needed to cancel a failover that is already in progress but
+##   did not produced any configuration change (SLAVEOF NO ONE yet not
+##   acknowledged by the promoted slave).
+##
+## - The maximum time a failover in progress waits for all the slaves to be
+##   reconfigured as slaves of the new master. However even after this time
+##   the slaves will be reconfigured by the Sentinels anyway, but not with
+##   the exact parallel-syncs progression as specified.
+# sentinel['failover_timeout'] = 60000
+```
 
 ---
 
@@ -409,9 +437,74 @@ The following steps should be performed in the [GitLab application server](gitla
 
 1. [Reconfigure] the GitLab for the changes to take effect.
 
-### Sentinel troubleshooting
+## Troubleshooting
+
+There are a lot of moving parts that needs to be taken care carefully
+in order for the HA setup to work as expected.
+
+Before proceeding with the troubleshooting below, check your firewall
+rules:
+- Redis machines
+   - Accept TCP connection in `6379`
+   - Connect to the other Redis machines via TCP in `6379`
+- Sentinel machines
+   - Accept TCP connection in `26379`
+   - Connect to other Sentinel machines via TCP in `26379`
+   - Connect to the Redis machines via TCP in `6379`
+
+### Redis replication
+
+You can check if everything is correct by connecting to each server using
+`redis-cli` application, and sending the `INFO` command.
+
+If authentication was correctly defined, it should fail with:
+`NOAUTH Authentication required` error. Try to authenticate with the
+previous defined password with `AUTH redis-password-goes-here` and
+try the `INFO` command again.
+
+Look for the `# Replication` section where you should see some important
+information like the `role` of the server.
+
+When connected to a `master` redis, you will see the number of connected
+`slaves`, and a list of each with connection details:
+
+```
+# Replication
+role:master
+connected_slaves:1
+slave0:ip=10.133.5.21,port=6379,state=online,offset=208037514,lag=1
+master_repl_offset:208037658
+repl_backlog_active:1
+repl_backlog_size:1048576
+repl_backlog_first_byte_offset:206989083
+repl_backlog_histlen:1048576
+```
+
+When it's a `slave`, you will see details of the master connection and if
+its `up` or `down`:
+
+```
+# Replication
+role:slave
+master_host:10.133.1.58
+master_port:6379
+master_link_status:up
+master_last_io_seconds_ago:1
+master_sync_in_progress:0
+slave_repl_offset:208096498
+slave_priority:100
+slave_read_only:1
+connected_slaves:0
+master_repl_offset:0
+repl_backlog_active:0
+repl_backlog_size:1048576
+repl_backlog_first_byte_offset:0
+repl_backlog_histlen:0
+```
+
+### Sentinel
 
-#### Omnibus install
+#### Omnibus GitLab
 
 If you get an error like: `Redis::CannotConnectError: No sentinels available.`,
 there may be something wrong with your configuration files or it can be related
@@ -424,7 +517,7 @@ The way the redis connector `redis-rb` works with sentinel is a bit
 non-intuitive. We try to hide the complexity in omnibus, but it still requires
 a few extra configs.
 
-#### Source install
+#### Install from Source
 
 If you get an error like: `Redis::CannotConnectError: No sentinels available.`,
 there may be something wrong with your configuration files or it can be related
-- 
cgit v1.2.1


From 0ca14544df6f8053a998009043290a4242d0362c Mon Sep 17 00:00:00 2001
From: Gabriel Mazetto <gabriel@gitlab.com>
Date: Tue, 18 Oct 2016 19:52:19 +0200
Subject: Reduce the ammount of lines to disable services and update TOC

---
 doc/administration/high_availability/redis.md | 12 +++---------
 1 file changed, 3 insertions(+), 9 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md
index 29bf2c54a08..aa334a8a0f6 100644
--- a/doc/administration/high_availability/redis.md
+++ b/doc/administration/high_availability/redis.md
@@ -16,6 +16,7 @@ that comes bundled with Omnibus GitLab packages.
 - [Configure Redis using Omnibus](#configure-redis-using-omnibus)
 - [Experimental Redis Sentinel support](#experimental-redis-sentinel-support)
 - [Redis Sentinel support](#redis-sentinel-support)
+  - [Prerequisites](#prerequisites)
   - [Redis setup](#redis-setup)
     - [Existing single-machine installation](#existing-single-machine-installation)
     - [Installation from source](#installation-from-source)
@@ -29,8 +30,8 @@ that comes bundled with Omnibus GitLab packages.
 - [Troubleshooting](#troubleshooting)
   - [Redis replication](#redis-replication)
   - [Sentinel](#sentinel)
-    - [Omnibus install](#omnibus-install)
-    - [Source install](#source-install)
+    - [Omnibus GitLab](#omnibus-gitlab)
+    - [Install from Source](#install-from-source)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -60,11 +61,8 @@ Redis.
     redis['enable'] = true
     bootstrap['enable'] = false
     nginx['enable'] = false
-    unicorn['enable'] = false
-    sidekiq['enable'] = false
     postgresql['enable'] = false
     gitlab_rails['enable'] = false
-    gitlab_workhorse['enable'] = false
     mailroom['enable'] = false
 
     # Redis configuration
@@ -340,13 +338,9 @@ redis['enable'] = true
 sentinel['enable'] = true
 
 # Disabled all other services
-redis['enable'] = false
 bootstrap['enable'] = false
 nginx['enable'] = false
-unicorn['enable'] = false
-sidekiq['enable'] = false
 postgresql['enable'] = false
-gitlab_workhorse['enable'] = false
 gitlab_rails['enable'] = false
 mailroom['enable'] = false
 
-- 
cgit v1.2.1


From 1dcbff1c4b07a0893f6d4a676895e8a01b8cfb14 Mon Sep 17 00:00:00 2001
From: Gabriel Mazetto <gabriel@gitlab.com>
Date: Thu, 20 Oct 2016 18:11:00 +0200
Subject: Few more fixes to Sentinel documentation to address MR feedback

---
 doc/administration/high_availability/redis.md | 11 ++++-------
 1 file changed, 4 insertions(+), 7 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md
index aa334a8a0f6..d60852814bb 100644
--- a/doc/administration/high_availability/redis.md
+++ b/doc/administration/high_availability/redis.md
@@ -63,13 +63,10 @@ Redis.
     nginx['enable'] = false
     postgresql['enable'] = false
     gitlab_rails['enable'] = false
-    mailroom['enable'] = false
 
     # Redis configuration
     redis['port'] = 6379
     redis['bind'] = '0.0.0.0'
-
-    # If you wish to use Redis authentication (recommended)
     redis['password'] = 'redis-password-goes-here'
     ```
 
@@ -85,8 +82,8 @@ Redis.
 ## Experimental Redis Sentinel support
 
    > Experimental Redis Sentinel support was [Introduced][ce-1877] in GitLab 8.11.
-     Starting with 8.13, Redis Sentinel is no longer experimental.
-     If you used with versions `< 8.13` before, please check the updated
+     Starting with 8.14, Redis Sentinel is no longer experimental.
+     If you used with versions `< 8.14` before, please check the updated
      documentation below.
 
 ## Redis Sentinel support
@@ -279,7 +276,7 @@ be each in a independent machine. You can configure them in the same
 machines where you've configured the other Redis servers.
 
 This number is required for the consensus algorithm to be effective
-in the case of a failure. **You should always have and `odd` number
+in the case of a failure. **You should always have an `odd` number
 of Sentinel nodes provisioned**.
 
 #### How sentinel handles a failover
@@ -400,7 +397,7 @@ master and the new sentinels servers.
 
 You can enable or disable sentinel support at any time in new or existing
 installations. From the GitLab application perspective, all it requires is
-the correct credentials for the master Redis and for a few Sentinel nodes.
+the correct credentials for the master Redis and for all Sentinel nodes.
 
 It doesn't require a list of all Sentinel nodes, as in case of a failure,
 the application will need to query only one of them.
-- 
cgit v1.2.1


From 92e603727fd93ab862f7c6b5b46dfa2b1dd3a44e Mon Sep 17 00:00:00 2001
From: Gabriel Mazetto <gabriel@gitlab.com>
Date: Sat, 29 Oct 2016 00:40:28 +0200
Subject: Fixed documentation and added redis/sentinel roles instruction

---
 doc/administration/high_availability/redis.md | 68 +++++++++++++++++++++------
 1 file changed, 54 insertions(+), 14 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md
index d60852814bb..bfad3047385 100644
--- a/doc/administration/high_availability/redis.md
+++ b/doc/administration/high_availability/redis.md
@@ -235,7 +235,7 @@ In `/etc/gitlab/gitlab.rb`:
 ## Redis TCP support (will disable UNIX socket transport)
 redis['bind'] = '0.0.0.0' # or specify an IP to bind to a single one
 redis['port'] = 6379
-redis['requirepass'] = 'redis-password-goes-here'
+redis['password'] = 'redis-password-goes-here'
 redis['master_password'] = 'redis-password-goes-here'
 ```
 
@@ -249,7 +249,7 @@ with an additional `Slave` section as in the example below:
 ```ruby
 redis['bind'] = '0.0.0.0' # or specify an IP to bind to a single one
 redis['port'] = 6379
-redis['requirepass'] = 'redis-password-goes-here'
+redis['password'] = 'redis-password-goes-here'
 redis['master_password'] = 'redis-password-goes-here'
 
 ## Slave redis instance
@@ -327,27 +327,25 @@ To setup sentinel, you edit `/etc/gitlab/gitlab.rb` file:
 ```ruby
 
 ## When you install Sentinel in a separate machine, you need to control which
-## other services will be running in it. Take a look at the following variables
-## and enable or disable whenever it fits your strategy:
+## other services will be running in it.
+## We've simplified the choice using special "roles" settings:
 
-## Enabled Redis and Sentinel services
-redis['enable'] = true
-sentinel['enable'] = true
+## Enabled Sentinel and Redis Master services
+redis_sentinel_role['enable'] = true
+redis_master_role['enable'] = true
 
-# Disabled all other services
-bootstrap['enable'] = false
-nginx['enable'] = false
-postgresql['enable'] = false
-gitlab_rails['enable'] = false
-mailroom['enable'] = false
+## Enabled Sentinel and Redis Slave services
+redis_sentinel_role['enable'] = true
+redis_master_role['enable'] = true
 
 ## Configure Redis
 redis['master_name'] = 'gitlab-redis' # must be the same in every sentinel node
 redis['master_ip'] = '10.0.0.1' # ip of the initial master redis instance
 redis['master_port'] = 6379 # port of the initial master redis instance
-redis['master_password'] = 'your-secure-password-here' # the same value defined in redis['password'] in the master instance
+redis['master_password'] = 'redis-password-goes-here' # the same value defined in redis['password'] in the master instance
 
 ## Configure Sentinel
+sentinel['bind'] = '0.0.0.0' # or specify an IP to bind to a single one
 # sentinel['port'] = 26379 # uncomment to change default port
 
 ## Quorum must reflect the amount of voting sentinels it take to start a failover.
@@ -388,6 +386,48 @@ sentinel['quorum'] = 2
 # sentinel['failover_timeout'] = 60000
 ```
 
+In the example above we've used `redis_sentinel_role` and `redis_master_role`
+which simplify the ammount of configuration changes.
+
+If you want more control, here is what each one sets for you automatically
+when enabled:
+
+```ruby
+## Redis Sentinel Role
+redis_sentinel_role['enable'] = true
+
+# When Sentinel Role is enabled, the following services are enabled/disabled:
+sentinel['enable'] = true
+
+# This others are disabled:
+redis['enable'] = false
+bootstrap['enable'] = false
+nginx['enable'] = false
+postgresql['enable'] = false
+gitlab_rails['enable'] = false
+mailroom['enable'] = false
+
+## Redis master/slave Role:
+redis_master_role['enable'] = true # enable only one of them
+redis_slave_role['enable'] = true # enable only one of them
+
+# When Redis Master or Slave role are enabled, the following services are enabled/disabled:
+# (Note that if redis and sentinel roles are combined both services will be enabled)
+
+# When Sentinel Role is enabled, the following services are enabled/disabled:
+redis['enable'] = true
+
+# This others are disabled:
+sentinel['enable'] = false
+bootstrap['enable'] = false
+nginx['enable'] = false
+postgresql['enable'] = false
+gitlab_rails['enable'] = false
+mailroom['enable'] = false
+
+# Redis Slave role also change this setting from default 'true' to 'false':
+redis['master'] = false
+```
 ---
 
 The final part is to inform the main GitLab application server of the Redis
-- 
cgit v1.2.1


From 494c2785fdc6a2f67edf20cbfc2106ffdba3ef28 Mon Sep 17 00:00:00 2001
From: Gabriel Mazetto <gabriel@gitlab.com>
Date: Tue, 8 Nov 2016 06:24:43 +0100
Subject: Fixed some documentation and moved Source install specific to other
 file.

---
 doc/administration/high_availability/redis.md      | 135 +---------
 .../high_availability/redis_source.md              | 286 +++++++++++++++++++++
 2 files changed, 300 insertions(+), 121 deletions(-)
 create mode 100644 doc/administration/high_availability/redis_source.md

(limited to 'doc/administration')

diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md
index bfad3047385..f49bf1d4ab5 100644
--- a/doc/administration/high_availability/redis.md
+++ b/doc/administration/high_availability/redis.md
@@ -19,7 +19,6 @@ that comes bundled with Omnibus GitLab packages.
   - [Prerequisites](#prerequisites)
   - [Redis setup](#redis-setup)
     - [Existing single-machine installation](#existing-single-machine-installation)
-    - [Installation from source](#installation-from-source)
     - [Omnibus packages](#omnibus-packages)
   - [Configuring Sentinel](#configuring-sentinel)
     - [How sentinel handles a failover](#how-sentinel-handles-a-failover)
@@ -31,7 +30,6 @@ that comes bundled with Omnibus GitLab packages.
   - [Redis replication](#redis-replication)
   - [Sentinel](#sentinel)
     - [Omnibus GitLab](#omnibus-gitlab)
-    - [Install from Source](#install-from-source)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -161,58 +159,6 @@ To disable redis in the single install, edit `/etc/gitlab/gitlab.rb`:
 redis['enable'] = false
 ```
 
-#### Installation from source
-
-**Configuring Master Redis instance**
-
-You need to make the following changes in `redis.conf`:
-
-1. Define a `bind` address pointing to a local IP that your other machines
-   can reach you. If you really need to bind to an external acessible IP, make
-   sure you add extra firewall rules to prevent unauthorized access:
-
-   ```conf
-   # By default, if no "bind" configuration directive is specified, Redis listens
-   # for connections from all the network interfaces available on the server.
-   # It is possible to listen to just one or multiple selected interfaces using
-   # the "bind" configuration directive, followed by one or more IP addresses.
-   #
-   # Examples:
-   #
-   # bind 192.168.1.100 10.0.0.1
-   # bind 127.0.0.1 ::1
-   bind 0.0.0.0 # This will bind to all interfaces
-   ```
-
-1. Define a `port` to force redis to listin on TCP so other machines can
-   connect to it:
-
-   ```conf
-   # Accept connections on the specified port, default is 6379 (IANA #815344).
-   # If port 0 is specified Redis will not listen on a TCP socket.
-   port 6379
-   ```
-
-1. Set up password authentication (use the same password in all nodes)
-
-    ```conf
-    requirepass "redis-password-goes-here"
-    masterauth "redis-password-goes-here"
-    ```
-
-1. Restart the Redis services for the changes to take effect.
-
-**Configuring Slave Redis instance**
-
-1. Follow same instructions from master, with the extra change in `redis.conf`:
-
-   ```conf
-   # IP and port of the master Redis server
-   slaveof 10.10.10.10 6379
-   ```
-
-1. Restart the Redis services for the changes to take effect.
-
 #### Omnibus packages
 
 You need to install the Omnibus GitLab package in `3` independent machines.
@@ -304,25 +250,16 @@ GitLab Enterprise Edition provides [automated way to setup and run](#sentinel-se
 #### Sentinel setup
 
 ##### Community Edition
+
 With GitLab Community Edition, you need to install, configure, execute and
 monitor Sentinel from source. Omnibus GitLab Community Edition package does
 not support Sentinel configuration.
 
-A minimal configuration file (`sentinel.conf`) should contain the following:
-
-```conf
-bind 0.0.0.0 # bind to all interfaces or change to a specific IP
-port 26379 # default sentinel port
-sentinel auth-pass gitlab-redis redis-password-goes-here
-sentinel monitor gitlab-redis 10.0.0.1 6379 2
-sentinel down-after-milliseconds gitlab-redis 10000
-sentinel config-epoch gitlab-redis 0
-sentinel leader-epoch gitlab-redis 0
-```
+See documentation for Source Install [here](redis_source.md).
 
 ##### Enterprise Edition
 
-To setup sentinel, you edit `/etc/gitlab/gitlab.rb` file:
+To setup sentinel, edit `/etc/gitlab/gitlab.rb` file:
 
 ```ruby
 
@@ -336,7 +273,7 @@ redis_master_role['enable'] = true
 
 ## Enabled Sentinel and Redis Slave services
 redis_sentinel_role['enable'] = true
-redis_master_role['enable'] = true
+redis_slave_role['enable'] = true
 
 ## Configure Redis
 redis['master_name'] = 'gitlab-redis' # must be the same in every sentinel node
@@ -345,7 +282,7 @@ redis['master_port'] = 6379 # port of the initial master redis instance
 redis['master_password'] = 'redis-password-goes-here' # the same value defined in redis['password'] in the master instance
 
 ## Configure Sentinel
-sentinel['bind'] = '0.0.0.0' # or specify an IP to bind to a single one
+# sentinel['bind'] = '0.0.0.0' # bind to all interfaces, uncomment to specify an IP and bind to a single one
 # sentinel['port'] = 26379 # uncomment to change default port
 
 ## Quorum must reflect the amount of voting sentinels it take to start a failover.
@@ -435,24 +372,16 @@ master and the new sentinels servers.
 
 ### GitLab setup
 
-You can enable or disable sentinel support at any time in new or existing
+You can enable or disable Sentinel support at any time in new or existing
 installations. From the GitLab application perspective, all it requires is
-the correct credentials for the master Redis and for all Sentinel nodes.
+the correct credentials for the Sentinel nodes.
 
-It doesn't require a list of all Sentinel nodes, as in case of a failure,
-the application will need to query only one of them.
+While it doesn't require a list of all Sentinel nodes, in case of a failure,
+it needs to access at one of listed ones.
 
 >**Note:**
-The following steps should be performed in the [GitLab application server](gitlab.md).
-
-**For source based installations**
-
-1. Edit `/home/git/gitlab/config/resque.yml` following the example in
-   `/home/git/gitlab/config/resque.yml.example`, and uncomment the sentinels
-   line, changing to the correct server credentials.
-1. Restart GitLab for the changes to take effect.
-
-**For Omnibus installations**
+The following steps should be performed in the [GitLab application server](gitlab.md)
+which ideally should not have Redis or Sentinels in the same machine for a HA setup.
 
 1. Edit `/etc/gitlab/gitlab.rb` and add/change the following lines:
 
@@ -466,7 +395,7 @@ The following steps should be performed in the [GitLab application server](gitla
     ]
     ```
 
-1. [Reconfigure] the GitLab for the changes to take effect.
+1. [Reconfigure] GitLab for the changes to take effect.
 
 ## Troubleshooting
 
@@ -548,42 +477,6 @@ The way the redis connector `redis-rb` works with sentinel is a bit
 non-intuitive. We try to hide the complexity in omnibus, but it still requires
 a few extra configs.
 
-#### Install from Source
-
-If you get an error like: `Redis::CannotConnectError: No sentinels available.`,
-there may be something wrong with your configuration files or it can be related
-to [this issue][gh-531].
-
-It's a bit non-intuitive the way you have to config `resque.yml` and
-`sentinel.conf`, otherwise `redis-rb` will not work properly.
-
-The `master-group-name` ('gitlab-redis') defined in (`sentinel.conf`)
-**must** be used as the hostname in GitLab (`resque.yml` for source installations
-or `gitlab-rails['redis_*']` in Omnibus):
-
-```conf
-# sentinel.conf:
-sentinel monitor gitlab-redis 10.10.10.10 6379 2
-sentinel down-after-milliseconds gitlab-redis 10000
-sentinel config-epoch gitlab-redis 0
-sentinel leader-epoch gitlab-redis 0
-```
-
-```yaml
-# resque.yaml
-production:
-  url: redis://:myredispassword@gitlab-redis/
-  sentinels:
-    -
-      host: slave1.example.com # or use ip
-      port: 26380 # point to sentinel, not to redis port
-    -
-      host: slave2.exampl.com # or use ip
-      port: 26381 # point to sentinel, not to redis port
-```
-
-When in doubt, please read [Redis Sentinel documentation](http://redis.io/topics/sentinel)
-
 ---
 
 To make sure your configuration is correct:
@@ -611,8 +504,8 @@ To make sure your configuration is correct:
 1. To simulate a failover on master Redis, SSH into the Redis server and run:
 
     ```bash
-    # port must match your master redis port
-     redis-cli -h localhost -p 6379 DEBUG sleep 60
+    # port must match your master redis port, and the sleep time must be a few seconds bigger than defined one
+     redis-cli -h localhost -p 6379 DEBUG sleep 20
     ```
 
 1. Then back in the Rails console from the first step, run:
diff --git a/doc/administration/high_availability/redis_source.md b/doc/administration/high_availability/redis_source.md
new file mode 100644
index 00000000000..7e8c8c2b4b9
--- /dev/null
+++ b/doc/administration/high_availability/redis_source.md
@@ -0,0 +1,286 @@
+# Configuring Redis for GitLab HA (Source Install)
+
+We highly recommend that you use Omnibus GitLab packages, as we can optimize
+required packages specifically for GitLab, and we will take care of upgrading
+to the latest supported version.
+
+If you are building packages for a specific distro, or trying to build some
+internal automation, you can check this documentation to learn about the
+minimal setup, required changes, etc.
+
+If you want to see the documentation for Omnibus GitLab Install, please [read it here](redis.md).
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**
+
+- [Configure your own Redis server](#configure-your-own-redis-server)
+  - [Configuring Master Redis instance](#configuring-master-redis-instance)
+  - [Configuring Slave Redis instances](#configuring-slave-redis-instances)
+  - [Configuring Redis Sentinel instances](#configuring-redis-sentinel-instances)
+- [GitLab setup](#gitlab-setup)
+- [Example configurations](#example-configurations)
+  - [Configuring Redis Master](#configuring-redis-master)
+  - [Configuring Redis Slaves](#configuring-redis-slaves)
+  - [Configuring Redis Sentinel](#configuring-redis-sentinel)
+- [Troubleshooting](#troubleshooting)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Configure your own Redis server
+
+Redis server must be configured to use TCP connection instead of socket,
+and since Redis `3.2`, you must define a password to receive external
+connections (`requirepass`).
+
+You will also need to define equal password for slave password definition
+(`masterauth`), in the same instance, if you are using Redis with Sentinel.
+
+To configure Redis to use TCP connection you need to define both
+`bind` and `port`. You can bind to all interfaces (`0.0.0.0`) or specify the
+ip of the desired interface (for ex. one from an internal network).
+
+
+### Configuring Master Redis instance
+
+You need to make the following changes in `redis.conf`:
+
+1. Define a `bind` address pointing to a local IP that your other machines
+   can reach you. If you really need to bind to an external acessible IP, make
+   sure you add extra firewall rules to prevent unauthorized access:
+
+1. Define a `port` to force redis to listen on TCP so other machines can
+   connect to it (default port is `6379`).
+
+1. Set up password authentication (use the same password in all nodes).
+   The password should be defined equal for both `requirepass` and `masterauth`
+   when setting up Redis to use with Sentinel.
+
+1. Restart the Redis services for the changes to take effect.
+
+See [example configuration](#configuring-redis-master) below.
+
+### Configuring Slave Redis instances
+
+1. Follow same instructions for Redis Master
+
+1. Define `slaveof` pointing to the Redis master instance with **IP** and **port**.
+
+1. Restart the Redis services for the changes to take effect.
+
+See [example configuration](#configuring-redis-slaves) below.
+
+### Configuring Redis Sentinel instances
+
+Sentinel is a special type of Redis server. It inherits most of the basic
+configuration options you can define in `redis.conf`, with specific ones
+starting with `sentinel` prefix.
+
+You will need to define the initial configs to enable connectivity:
+
+1. Define a `bind` address pointing to a local IP that your other machines
+   can reach you. If you really need to bind to an external acessible IP, make
+   sure you add extra firewall rules to prevent unauthorized access:
+
+1. Define a `port` to force sentinel to listen on TCP so other machines can
+   connect to it (default port is `26379`).
+
+And the sentinel specific ones:
+
+1. Define with `sentinel auth-pass` the same shared password you have
+   defined for both Redis **Master** and **Slaves** instances.
+
+1. Define with `sentinel monitor` the **IP** and **port** of the Redis
+   **Master** node, and the **quorum** required to start a failover.
+   If you need more information to understand about quorum, please
+   read the detailed explanation in the [HA documentation for Omnibus Installs](redis.md).
+
+1. Define with `sentinel down-after-milliseconds` the ammount in `ms` of time
+   that an unresponsive server will be considered down.
+
+1. Define a value for `sentinel failover_timeout` in `ms`. This has multiple
+   meanings:
+
+   * The time needed to re-start a failover after a previous failover was
+     already tried against the same master by a given Sentinel, is two
+     times the failover timeout.
+
+   * The time needed for a slave replicating to a wrong master according
+     to a Sentinel current configuration, to be forced to replicate
+     with the right master, is exactly the failover timeout (counting since
+     the moment a Sentinel detected the misconfiguration).
+
+   * The time needed to cancel a failover that is already in progress but
+     did not produced any configuration change (SLAVEOF NO ONE yet not
+     acknowledged by the promoted slave).
+
+   * The maximum time a failover in progress waits for all the slaves to be
+     reconfigured as slaves of the new master. However even after this time
+     the slaves will be reconfigured by the Sentinels anyway, but not with
+     the exact parallel-syncs progression as specified.
+
+See [example configuration](#configuring-redis-sentinel) below.
+
+## GitLab setup
+
+You can enable or disable Sentinel support at any time in new or existing
+installations. From the GitLab application perspective, all it requires is
+the correct credentials for the Sentinel nodes.
+
+While it doesn't require a list of all Sentinel nodes, in case of a failure,
+it needs to access at one of listed ones.
+
+>**Note:**
+The following steps should be performed in the [GitLab application server](gitlab.md)
+which ideally should not have Redis or Sentinels in the same machine for a HA setup.
+
+1. Edit `/home/git/gitlab/config/resque.yml` following the example in
+   `/home/git/gitlab/config/resque.yml.example`, and uncomment the sentinels
+   lines, pointing to the correct server credentials.
+
+1. Restart GitLab for the changes to take effect.
+
+## Example configurations
+
+In this example we consider that all servers have an internal network
+interface with IPs in the `10.0.0.x` range, and that they can connect
+to each other using these IPs.
+
+In a real world usage, you would also setup firewall rules to prevent
+unauthorized access from other machines, and block traffic from the
+outside (Internet).
+
+We will use the same `3` nodes with **Redis** + **Sentinel** topology
+discussed in the [Configuring Redis for GitLab HA](redis.md) documentation.
+
+Here is a list and description of each **machine** and the assined **ip**:
+
+* `10.0.0.1`: Redis Master + Sentinel 1
+* `10.0.0.2`: Redis Slave 1 + Sentinel 2
+* `10.0.0.2`: Redis Slave 2 + Sentinel 3
+
+Please note that after the initial configuration, if a failover is initiated
+by the Sentinel nodes, the Redis nodes will be reconfigured and the **Master**
+will change permanently (including in `redis.conf`) from one node to the other,
+until a new failover is initiated again.
+
+The same thing will happen with `sentinel.conf` that will be overriten after the
+initial execution, after any new sentinel node starts watching the **Master**,
+or a failover promotes a different **Master** node.
+
+### Configuring Redis Master
+
+`redis.conf`:
+
+```conf
+bind 10.0.0.1
+port 6379
+requirepass redis-password-goes-here
+masterauth redis-password-goes-here
+```
+
+### Configuring Redis Slaves
+
+**Slave 1 - `redis.conf`:**
+
+```conf
+bind 10.0.0.2
+port 6379
+requirepass redis-password-goes-here
+masterauth redis-password-goes-here
+
+# IP and port of the master Redis server
+slaveof 10.0.0.1 6379
+```
+
+**Slave 2 - `redis.conf`:**
+
+```conf
+bind 10.0.0.3
+port 6379
+requirepass redis-password-goes-here
+masterauth redis-password-goes-here
+
+# IP and port of the master Redis server
+slaveof 10.0.0.1 6379
+```
+
+### Configuring Redis Sentinel
+
+For this example, **Sentinel 1** will be configured in the same machine as the
+**Redis Master**, **Sentinel 2** and **Sentinel 3** in the same machines as the
+**Slave 1** and **Slave 2** respectively.
+
+Sentinel 1 - `sentinel.conf`
+
+```conf
+bind 10.0.0.1
+port 26379
+sentinel auth-pass gitlab-redis redis-password-goes-here
+sentinel monitor gitlab-redis 10.0.0.1 6379 2
+sentinel down-after-milliseconds gitlab-redis 10000
+sentinel failover_timeout 30000
+```
+
+Sentinel 2 - `sentinel.conf`
+
+```conf
+bind 10.0.0.2
+port 26379
+sentinel auth-pass gitlab-redis redis-password-goes-here
+sentinel monitor gitlab-redis 10.0.0.1 6379 2
+sentinel down-after-milliseconds gitlab-redis 10000
+sentinel failover_timeout 30000
+```
+
+Sentinel 3 - `sentinel.conf`
+
+```conf
+bind 10.0.0.3
+port 26379
+sentinel auth-pass gitlab-redis redis-password-goes-here
+sentinel monitor gitlab-redis 10.0.0.1 6379 2
+sentinel down-after-milliseconds gitlab-redis 10000
+sentinel failover_timeout 30000
+```
+
+## Troubleshooting
+
+We have a more detailed [Troubleshooting](redis.md#troubleshooting) explained in the documentation for Omnibus
+Install. Here we will list only the things that are specific to a **Source** install.
+
+If you get an error in GitLab like: `Redis::CannotConnectError: No sentinels available.`,
+there may be something wrong with your configuration files or it can be related
+to [this issue][gh-531].
+
+It's a bit non-intuitive the way you have to config `resque.yml` and
+`sentinel.conf`, otherwise `redis-rb` will not work properly.
+
+The `master-group-name` ('gitlab-redis') defined in (`sentinel.conf`)
+**must** be used as the hostname in GitLab (`resque.yml`):
+
+```conf
+# sentinel.conf:
+sentinel monitor gitlab-redis 10.0.0.1 6379 2
+sentinel down-after-milliseconds gitlab-redis 10000
+sentinel config-epoch gitlab-redis 0
+sentinel leader-epoch gitlab-redis 0
+```
+
+```yaml
+# resque.yaml
+production:
+  url: redis://:myredispassword@gitlab-redis/
+  sentinels:
+    -
+      host: 10.0.0.1
+      port: 26379 # point to sentinel, not to redis port
+    -
+      host: 10.0.0.2
+      port: 26379 # point to sentinel, not to redis port
+    -
+      host: 10.0.0.3
+      port: 26379 # point to sentinel, not to redis port
+```
+
+When in doubt, please read [Redis Sentinel documentation](http://redis.io/topics/sentinel)
-- 
cgit v1.2.1


From dc307830571aaca1ff20b409d7075eee83f21fb9 Mon Sep 17 00:00:00 2001
From: Drew Blessing <drew@gitlab.com>
Date: Thu, 29 Sep 2016 14:08:27 -0500
Subject: Introduce better credential and error checking to `rake
 gitlab:ldap:check`

It was previously possible for invalid credential errors to go unnoticed
in this task. Users would believe everything was configured correctly and
then sign in would fail with 'invalid credentials'. This adds a specific
bind check, plus catches errors connecting to the server. Also, specs :)
---
 doc/administration/auth/ldap.md                    |   4 +
 .../img/raketasks/check_repos_output.png           | Bin 0 -> 35333 bytes
 doc/administration/raketasks/check.md              |  97 +++++++++++++++++++++
 3 files changed, 101 insertions(+)
 create mode 100644 doc/administration/img/raketasks/check_repos_output.png
 create mode 100644 doc/administration/raketasks/check.md

(limited to 'doc/administration')

diff --git a/doc/administration/auth/ldap.md b/doc/administration/auth/ldap.md
index bf7814875bf..fd23047f027 100644
--- a/doc/administration/auth/ldap.md
+++ b/doc/administration/auth/ldap.md
@@ -35,6 +35,10 @@ of one hour.
 To enable LDAP integration you need to add your LDAP server settings in
 `/etc/gitlab/gitlab.rb` or `/home/git/gitlab/config/gitlab.yml`.
 
+There is a Rake task to check LDAP configuration. After configuring LDAP
+using the documentation below, see [LDAP check Rake task](../raketasks/check.md#ldap-check)
+for information on the LDAP check Rake task.
+
 >**Note**: In GitLab EE, you can configure multiple LDAP servers to connect to
 one GitLab server.
 
diff --git a/doc/administration/img/raketasks/check_repos_output.png b/doc/administration/img/raketasks/check_repos_output.png
new file mode 100644
index 00000000000..1f632566b00
Binary files /dev/null and b/doc/administration/img/raketasks/check_repos_output.png differ
diff --git a/doc/administration/raketasks/check.md b/doc/administration/raketasks/check.md
new file mode 100644
index 00000000000..d1d2fed4861
--- /dev/null
+++ b/doc/administration/raketasks/check.md
@@ -0,0 +1,97 @@
+# Check Rake Tasks
+
+## Repository Integrity
+
+Even though Git is very resilient and tries to prevent data integrity issues,
+there are times when things go wrong. The following Rake tasks intend to
+help GitLab administrators diagnose problem repositories so they can be fixed.
+
+There are 3 things that are checked to determine integrity.
+
+1. Git repository file system check ([git fsck](https://git-scm.com/docs/git-fsck)).
+   This step verifies the connectivity and validity of objects in the repository.
+1. Check for `config.lock` in the repository directory.
+1. Check for any branch/references lock files in `refs/heads`.
+
+It's important to note that the existence of `config.lock` or reference locks
+alone do not necessarily indicate a problem. Lock files are routinely created
+and removed as Git and GitLab perform operations on the repository. They serve
+to prevent data integrity issues. However, if a Git operation is interrupted these
+locks may not be cleaned up properly.
+
+The following symptoms may indicate a problem with repository integrity. If users
+experience these symptoms you may use the rake tasks described below to determine
+exactly which repositories are causing the trouble.
+
+- Receiving an error when trying to push code - `remote: error: cannot lock ref`
+- A 500 error when viewing the GitLab dashboard or when accessing a specific project.
+
+### Check all GitLab repositories
+
+This task loops through all repositories on the GitLab server and runs the
+3 integrity checks described previously.
+
+**Omnibus Installation**
+
+```
+sudo gitlab-rake gitlab:repo:check
+```
+
+**Source Installation**
+
+```bash
+sudo -u git -H bundle exec rake gitlab:repo:check RAILS_ENV=production
+```
+
+### Check repositories for a specific user
+
+This task checks all repositories that a specific user has access to. This is important
+because sometimes you know which user is experiencing trouble but you don't know
+which project might be the cause.
+
+If the rake task is executed without brackets at the end, you will be prompted
+to enter a username.
+
+**Omnibus Installation**
+
+```bash
+sudo gitlab-rake gitlab:user:check_repos
+sudo gitlab-rake gitlab:user:check_repos[<username>]
+```
+
+**Source Installation**
+
+```bash
+sudo -u git -H bundle exec rake gitlab:user:check_repos RAILS_ENV=production
+sudo -u git -H bundle exec rake gitlab:user:check_repos[<username>] RAILS_ENV=production
+```
+
+Example output:
+
+![gitlab:user:check_repos output](../img/raketasks/check_repos_output.png)
+
+## LDAP Check
+
+The LDAP check Rake task will test the bind_dn and password credentials
+(if configured) and will list a sample of LDAP users. This task is also
+executed as part of the `gitlab:check` task, but can run independently
+using the command below.
+
+**Omnibus Installation**
+
+```
+sudo gitlab-rake gitlab:ldap:check
+```
+
+**Source Installation**
+
+```bash
+sudo -u git -H bundle exec rake gitlab:ldap:check RAILS_ENV=production
+```
+
+By default, the task will return a sample of 100 LDAP users. Change this
+limit by passing a number to the check task:
+
+```bash
+rake gitlab:ldap:check[50]
+```
-- 
cgit v1.2.1


From 1e4f86744627fbf0d0190c7d76f30cd77480db37 Mon Sep 17 00:00:00 2001
From: Gabriel Mazetto <gabriel@gitlab.com>
Date: Thu, 10 Nov 2016 07:07:30 +0100
Subject: Remade documentation for Redis HA with Omnibus

---
 doc/administration/high_availability/redis.md      | 648 +++++++++++++++------
 .../high_availability/redis_source.md              |  14 +-
 2 files changed, 480 insertions(+), 182 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md
index f49bf1d4ab5..6b16f9e791f 100644
--- a/doc/administration/high_availability/redis.md
+++ b/doc/administration/high_availability/redis.md
@@ -1,9 +1,14 @@
 # Configuring Redis for GitLab HA
 
-You can choose to install and manage Redis yourself, or you can use the one
+High Availability with Redis is possible using a **Master** x **Slave**
+topology with **Sentinel** service to watch and automatically start
+failover proceedings.
+
+You can choose to install and manage Redis and Sentinel yourself, use
+a hosted, managed clouse solution or you can use or you can use the one
 that comes bundled with Omnibus GitLab packages.
 
-> **Note:** Redis does not require authentication by default. See
+> **Note:** Redis requires authentication for High Availability. See
   [Redis Security](http://redis.io/topics/security) documentation for more
   information. We recommend using a combination of a Redis password and tight
   firewall rules to secure your Redis service.
@@ -12,20 +17,26 @@ that comes bundled with Omnibus GitLab packages.
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 **Table of Contents**
 
-- [Configure your own Redis server](#configure-your-own-redis-server)
-- [Configure Redis using Omnibus](#configure-redis-using-omnibus)
-- [Experimental Redis Sentinel support](#experimental-redis-sentinel-support)
-- [Redis Sentinel support](#redis-sentinel-support)
+- [Using an external Redis server](#using-an-external-redis-server)
+- [High Availability with Sentinel](#high-availability-with-sentinel)
   - [Prerequisites](#prerequisites)
   - [Redis setup](#redis-setup)
-    - [Existing single-machine installation](#existing-single-machine-installation)
-    - [Omnibus packages](#omnibus-packages)
-  - [Configuring Sentinel](#configuring-sentinel)
-    - [How sentinel handles a failover](#how-sentinel-handles-a-failover)
-    - [Sentinel setup](#sentinel-setup)
+  - [Experimental Redis Sentinel support](#experimental-redis-sentinel-support)
+  - [Sentinel setup](#sentinel-setup)
+  - [Recommended setup](#recommended-setup)
+- [Configuring instances using Omnibus](#configuring-instances-using-omnibus)
+  - [Existing single-machine installation](#existing-single-machine-installation)
+  - [Configuring Master Redis instance](#configuring-master-redis-instance)
+  - [Configuring Slave Redis instances](#configuring-slave-redis-instances)
+  - [Configuring Sentinel instances](#configuring-sentinel-instances)
       - [Community Edition](#community-edition)
       - [Enterprise Edition](#enterprise-edition)
   - [GitLab setup](#gitlab-setup)
+- [Example Configurations](#example-configurations)
+  - [Configuration for Redis Master](#configuration-for-redis-master)
+  - [Configuration for Redis Slave](#configuration-for-redis-slave)
+  - [Configuration for Sentinel (EE only)](#configuration-for-sentinel-ee-only)
+  - [Control running services](#control-running-services)
 - [Troubleshooting](#troubleshooting)
   - [Redis replication](#redis-replication)
   - [Sentinel](#sentinel)
@@ -33,75 +44,57 @@ that comes bundled with Omnibus GitLab packages.
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
-## Configure your own Redis server
+## Using an external Redis server
 
 If you're hosting GitLab on a cloud provider, you can optionally use a
 managed service for Redis. For example, AWS offers a managed ElastiCache service
 that runs Redis.
 
-## Configure Redis using Omnibus
+Managed services can provide High Availability using their own proprietary
+technology and provide a transparent proxy, which means that GitLab doesn't
+need any additional change, or will use Sentinel and manage it for you.
 
-If you don't want to bother setting up your own Redis server, you can use the
-one bundled with Omnibus. In this case, you should disable all services except
-Redis.
+If your provider, uses Sentinel method, see [GitLab Setup](#gitlab-setup)
+to understant where you need to provide the list of servers and credentials.
 
-1. Download/install Omnibus GitLab using **steps 1 and 2** from
-   [GitLab downloads](https://about.gitlab.com/downloads). Do not complete other
-   steps on the download page.
-1. Create/edit `/etc/gitlab/gitlab.rb` and use the following configuration.
-   Be sure to change the `external_url` to match your eventual GitLab front-end
-   URL:
+If you want to setup Redis by yourself, without using Omnibus, you can
+read our documentation: [Configuring Redis for GitLab HA (Source Install)](redis_source.md)
 
-    ```ruby
-    external_url 'https://gitlab.example.com'
-
-    # Disable all services except Redis
-    redis['enable'] = true
-    bootstrap['enable'] = false
-    nginx['enable'] = false
-    postgresql['enable'] = false
-    gitlab_rails['enable'] = false
-
-    # Redis configuration
-    redis['port'] = 6379
-    redis['bind'] = '0.0.0.0'
-    redis['password'] = 'redis-password-goes-here'
-    ```
+## High Availability with Sentinel
 
-1. Run `sudo gitlab-ctl reconfigure` to install and configure Redis.
+> Since GitLab `8.11`, you can configure a list of Redis Sentinel servers that
+will monitor a group of Redis servers to provide failover support.
 
-    > **Note**: This `reconfigure` step will result in some errors.
-      That's OK - don't be alarmed.
+> With GitLab `8.14`, we bundled Redis Sentinel as part of Omnibus package and
+improved the way you use and configure it.
 
-1. Run `touch /etc/gitlab/skip-auto-migrations` to prevent database migrations
-   from running on upgrade. Only the primary GitLab application server should
-   handle migrations.
+High Availability with Redis requires a few things:
 
-## Experimental Redis Sentinel support
+- Multiple Redis instances
+- Run Redis in a **Master** x **Slave** topology
+- Multiple Sentinel instances
+- Application support and visiblity to all Sentinel and Redis instances
 
-   > Experimental Redis Sentinel support was [Introduced][ce-1877] in GitLab 8.11.
-     Starting with 8.14, Redis Sentinel is no longer experimental.
-     If you used with versions `< 8.14` before, please check the updated
-     documentation below.
+Redis Sentinel can handle the most important tasks in a HA environment to help
+keep servers online with minimal to no downtime:
 
-## Redis Sentinel support
+- Monitors **Master** and **Slaves** instances to see if they are available
+- Promote a **Slave** to **Master** when the **Master** fails.
+- Demote a **Master** to **Slave** when failed **Master** comes back online (to prevent
+  data-partitioning).
+- Can be queried by clients to always connect to the current **Master** server.
 
-Since GitLab 8.11, you can configure a list of Redis Sentinel servers that
-will monitor a group of Redis servers to provide you with a standard failover
-support.
+When a **Master** fails to respond, it's the client responsability to handle timeout
+and reconnect (querying a **Sentinel** for a new **Master**).
 
 To get a better understanding on how to correctly setup Sentinel, please read
 the [Redis Sentinel documentation](http://redis.io/topics/sentinel) first, as
-failing to configure it correctly can lead to data loss.
+failing to configure it correctly can lead to data loss, or can bring your
+whole cluster down, invalidating the failover effort.
 
-Redis Sentinel can handle the most important tasks in a HA environment to help
-keep servers online with minimal to no downtime:
-
-- Monitors master and slave instances to see if they are available
-- Promote a slave to master when the master fails.
-- Demote a master to slave when failed master comes back online (to prevent
-  data-partitioning).
-- Can be queried by clients to always connect to the correct master server.
+This documentation will provide you with a minimal and a recommended topology
+that can resist to some levels of failure. Usually the more Redis and Sentinel
+instances you have provisioned, the better will be your availability.
 
 The configuration consists of three parts:
 
@@ -112,44 +105,191 @@ The configuration consists of three parts:
 ### Prerequisites
 
 You need at least `3` independent machines: physical, or VMs running into
-distinct physical machines.
+distinct physical machines. They must be believed to fail in an
+independent way.
 
 If you fail to provision the machines in that specific way, any issue with
 the shared environment can bring your entire setup down.
 
-Read carefully how to configure those components below.
+You also need to take in consideration the underlying network topology,
+making sure you have redundant connectivity between Redis / Sentinel and
+GitLab instances, otherwhise the networks will become a single point of
+failure.
+
+Read carefully how to configure the components below.
 
 ### Redis setup
 
-You must have at least `3` Redis servers: `1` Master, `2` Slaves, and they need to
-be each in a independent machine (see explanation above).
+You must have at least `3` Redis servers: `1` Master, `2` Slaves, and they
+need to be each in a independent machine (see explanation above).
 
-They should be configured the same way and with similar server specs, as
-in a failover situation, any `Slave` can be elected as the new `Master` by
+You can have additional Redis nodes, that will help survive a situation
+where more nodes goes down. Whenever there is only `2` nodes online, a failover
+will not be initiated.
+
+As an example, if you have `6` Redis nodes, a maximum of `3` can be
+simultaneously down.
+
+Please note that there are different requirements for Sentinel nodes.
+If you host them in the same Redis machines, you may need to take
+that restrictions into consideration when calculating the ammount of
+nodes to be provisioned. See [Sentinel setup](#sentinel-setup)
+documentation for more information.
+
+All Redis nodes should be configured the same way and with similar server specs, as
+in a failover situation, any **Slave** can be promoted as the new **Master** by
 the Sentinel servers.
 
-With Sentinel, you must define a password to protect the access as both
-Sentinel instances and other redis instances should be able to talk to
+The replication requires authentication, so you need to define a password to
+protect all Redis nodes and the Sentinels. They will all share the same
+password, and all instances must be able to talk to
 each other over the network.
 
-You'll need to define both `requirepass` and `masterauth` in all
-nodes. At any time during a failover the Sentinels can reconfigure a node
-and change it's status from `Master` to `Slave` and vice versa.
+Redis nodes will need the same password defined in `redis['password']` and
+`redis['master_password']`, no matter if **Master** or **Slave**. At any time
+during a failover the Sentinels can reconfigure a node and change it's status
+from **Master** to **Slave** and vice versa.
+
+Initial **Slave** nodes requires `redis['master']` defined to `false` and
+`redis['master_ip']` pointing to the initial **Master**. If you use the
+simplified configuration by enabling `redis_slave_role['enable']`, you
+just need to fill in the `redis['master_ip']`.
+
+This values doesn't have to be changed again in `/etc/gitlab/gitlab.rb` after
+a failover, as the nodes will be managed by the Sentinels, and even after a
+`gitlab-ctl reconfigure`, they will get their configuration restored by
+the same Sentinels.
+
+### Experimental Redis Sentinel support
+
+   > Experimental Redis Sentinel support was [Introduced][ce-1877] in GitLab 8.11.
+     Starting with 8.14, Redis Sentinel is no longer experimental.
+     If you used with versions `< 8.14` before, please check the updated
+     documentation here.
+
+### Sentinel setup
+
+Sentinels watches both other sentinels and Redis nodes. Whenever a Sentinel
+detects that a Redis node is not responding, it will announce that to the
+other sentinels. You have to reach the **quorum**, the minimum ammount of
+sentinels that agrees that a node is down, to be able to start a failover.
+
+Whenver the **quorum** is met, you need the **majority** of all known
+Sentinel nodes to be available and reachable, to elect the Sentinel **leader**
+who will take all the decisions to restore the service availability by:
+
+- Promoting a new **Master**
+- Reconfiguring the other **Slaves** and make them point to the new **Master**
+- Announce the new **Master** to every other Sentinel peer
+- Reconfigure the old **Master** and demote to **Slave** when it comes back online
+
+You must have at least `3` Redis Sentinel servers, and they need to
+be each in a independent machine (that are believed to fail independently).
+
+You can configure them in the same machines where you've configured the other
+Redis servers, but understand that if a whole node goes down, you loose both
+a Sentinel and a Redis instance.
 
-Initial `Slave` nodes require an additional `slaveof` setting in `redis.conf`
-pointing to the initial `Master`.
+The number of sentinels should ideally always be an **odd** number, for the
+consensus algorithm to be effective in the case of a failure.
 
-#### Existing single-machine installation
+In a `3` nodes topology, you can only afford `1` Sentinel node going down.
+Whenever the **majority** of the Sentinels goes down, the network partition
+protection prevents destructive actions and a failover **will not be started**.
+
+Here are some examples:
+
+- With `5` or `6` sentinels, a maximum of `2` can go down for a failover begin.
+- With `7` sentinels, a maximum of `3` nodes can go down.
+
+The **Leader** election can sometimes fail the voting round when **consensus**,
+is not achieved (see the odd number of nodes requirement above). In that case,
+a new attempt will be made after the amount of time defined in
+`sentinel['failover_timeout']` (in milliseconds).
+
+The `failover_time` variable have a lot of different usages, according to
+official documentation:
+
+- The time needed to re-start a failover after a previous failover was
+  already tried against the same master by a given Sentinel, is two
+  times the failover timeout.
+
+- The time needed for a slave replicating to a wrong master according
+  to a Sentinel current configuration, to be forced to replicate
+  with the right master, is exactly the failover timeout (counting since
+  the moment a Sentinel detected the misconfiguration).
+
+- The time needed to cancel a failover that is already in progress but
+  did not produced any configuration change (SLAVEOF NO ONE yet not
+  acknowledged by the promoted slave).
+
+- The maximum time a failover in progress waits for all the slaves to be
+  reconfigured as slaves of the new master. However even after this time
+  the slaves will be reconfigured by the Sentinels anyway, but not with
+  the exact parallel-syncs progression as specified.
+
+### Recommended setup
+
+For a minimal setup, you will install the Omnibus GitLab package in `3`
+independent machines, both with **Redis** and **Sentinel**:
+
+- Redis Master + Sentinel
+- Redis Slave + Sentinel
+- Redis Slave + Sentinel
+
+Make sure you've read [Redis Setup](#redis-setup) and [Sentinel Setup](#sentinel-setup)
+before, to understant how and why the ammount of nodes came from.
+
+For a recommended setup, that can resist more failures, you will install
+the Omnibus GitLab package in `5` independent machines, both with
+**Redis** and **Sentinel**:
+
+- Redis Master + Sentinel
+- Redis Slave + Sentinel
+- Redis Slave + Sentinel
+- Redis Slave + Sentinel
+- Redis Slave + Sentinel
+
+## Configuring instances using Omnibus
+
+This is a summary of what are we going to do:
+
+1. Provision the required number of instances specified previously
+   - You can opt to install Redis and Sentinel in the same machine or each in
+     independent ones.
+   - Don't install Redis and Sentinel in the same machines your GitLab instance
+     is running on.
+   - All machines must be able to talk to each other and accept incomming
+     connection over Redis (`6379`) and Sentinel (`26379`) ports.
+   - GitLab machines must be able to access these machines and with the same
+     permissions.
+   - Protected them from indiscriminated access from external networks (Internet),
+     to harden the security.
+
+1. Download/install Omnibus GitLab using **steps 1 and 2** from
+   [GitLab downloads](https://about.gitlab.com/downloads) in each node.
+   - Do not complete other steps on the download page.
+   - Make sure you select the correct Omnibus package, with the same version
+   and type (Community, Enterprise editions) of your current install.
+
+1. Run `touch /etc/gitlab/skip-auto-migrations` to prevent database migrations
+   from running on upgrade. Only the primary GitLab application server should
+   handle migrations.
+
+1. Create/edit `/etc/gitlab/gitlab.rb` and make the changes based on the
+   [Example Configurations](#example-configurations).
+
+### Existing single-machine installation
 
 If you already have a single-machine GitLab install running, you will need to
 replicate from this machine first, before de-activating the Redis instance
 inside it.
 
-Your single-machine install will be the initial `Master`, and the `3` others
-should be configured as `Slave` pointing to this machine.
+Your single-machine install will be the initial **Master**, and the `3` others
+should be configured as **Slave** pointing to this machine.
 
 After replication catchs-up, you will need to stop services in the
-single-machine install, to rotate the `Master` to one of the new nodes.
+single-machine install, to rotate the **Master** to one of the new nodes.
 
 Make the required changes in configuration and restart the new nodes again.
 
@@ -159,130 +299,317 @@ To disable redis in the single install, edit `/etc/gitlab/gitlab.rb`:
 redis['enable'] = false
 ```
 
-#### Omnibus packages
+If you fail to replicate first, you may loose data (unprocessed background jobs).
+
+### Configuring Master Redis instance
+
+You will need to configure the following in `/etc/gitlab/gitlab.rb`:
+
+1. Define `redis_master_role['enable']` to `true`, to disable other services
+   in the machine (you can still enable Sentinel)
+
+1. Define a `redis['bind']` address pointing to a local IP that your other machines
+   can reach you.
+   - If you really need to bind to an external acessible IP, make
+   sure you add extra firewall rules to prevent unauthorized access.
+   - You can also set bind to `0.0.0.0` which listen in all interfaces.
+
+1. Define a `redis['port']` so redis can listen for TCP requests which will
+   allow other machines to connect to it.
+
+1. Set up a password authentication with `redis['password']` and
+   `redis['master_password']` (use the same password in all nodes).
+
+Reconfigure Omnibus GitLab for the changes to take effect: `sudo gitlab-ctl reconfigure`
 
-You need to install the Omnibus GitLab package in `3` independent machines.
+### Configuring Slave Redis instances
 
-**Configuring Master Redis instance**
+You will need to configure the following in `/etc/gitlab/gitlab.rb`:
 
-You will need to configure the following:
+1. Define `redis_slaves_role['enable']` to `true`, to disable other services
+   in the machine (you can still enable Sentinel)
+   - This will also set automatically `redis['master'] = false`.
 
 1. Define a `redis['bind']` address pointing to a local IP that your other machines
-   can reach you. If you really need to bind to an external acessible IP, make
+   can reach you.
+   - If you really need to bind to an external acessible IP, make
    sure you add extra firewall rules to prevent unauthorized access.
+   - You can also set bind to `0.0.0.0` which listen in all interfaces.
+
 1. Define a `redis['port']` so redis can listen for TCP requests which will
    allow other machines to connect to it.
-1. Set up a password authentication with `redis['master_password']` (use the same
-   password in all nodes).
+
+1. Set up a password authentication with `redis['password']` and
+   `redis['master_password']` (use the same password in all nodes).
+
+1. Define `redis['master_ip']` with the IP of the **Master** Redis.
+
+1. Define `redis['master_port']` with the port of the **Master** Redis (default to `6379`).
+
+### Configuring Sentinel instances
+
+Now that the Redis servers are all set up, let's configure the Sentinel
+servers.
+
+If you are not sure if your Redis servers are working and replicating
+correctly, please read the [Troubleshooting Replication](#troubleshooting-replication)
+and fix it before proceeding with Sentinel setup.
+
+You must have at least `3` Redis Sentinel servers, and they need to
+be each in a independent machine. You can configure them in the same
+machines where you've configured the other Redis servers.
+
+##### Community Edition
+
+With GitLab Community Edition, you need to install, configure, execute and
+monitor Sentinel from source. Omnibus GitLab Community Edition package does
+not support Sentinel configuration.
+
+See [documentation for Source Install](redis_source.md).
+
+##### Enterprise Edition
+
+With GitLab Enterprise Edition, you can use Omnibus package to setup multiple
+machines with Sentinel daemon.
+
+See [example configuration](#configuration-for-sentinel-ee-only) below.
+
+### GitLab setup
+
+The final part is to inform the main GitLab application server of the Redis
+Sentinels servers and authentication credentials.
+
+You can enable or disable Sentinel support at any time in new or existing
+installations. From the GitLab application perspective, all it requires is
+the correct credentials for the Sentinel nodes.
+
+While it doesn't require a list of all Sentinel nodes, in case of a failure,
+it needs to access at least one of listeds.
+
+>**Note:**
+The following steps should be performed in the [GitLab application server](gitlab.md)
+which ideally should not have Redis or Sentinels in the same machine for a HA setup.
+
+1. Edit `/etc/gitlab/gitlab.rb` and add/change the following lines:
+
+  - `redis['master_name']` - this is the `master-group-name` from sentinel (default: `gitlab-redis`)
+  - `redis['master_password']` - the same password you've defined before for Redis and Sentinels
+  - `gitlab_rails['redis_sentinels']` - a list of sentinels with `host` and `port`
+
+1. [Reconfigure] GitLab for the changes to take effect.
+
+See [example configuration](#configuration-for-gitlab) below.
+
+## Example Configurations
+
+In this example we consider that all servers have an internal network
+interface with IPs in the `10.0.0.x` range, and that they can connect
+to each other using these IPs.
+
+In a real world usage, you would also setup firewall rules to prevent
+unauthorized access from other machines, and block traffic from the
+outside (Internet).
+
+We will use the same `3` nodes with **Redis** + **Sentinel** topology
+discussed in [Redis Setup](#redis-setup) and [Sentinel Setup](#sentinel-setup)
+documentation.
+
+Here is a list and description of each **machine** and the assigned **IP**:
+
+* `10.0.0.1`: Redis Master + Sentinel 1
+* `10.0.0.2`: Redis Slave 1 + Sentinel 2
+* `10.0.0.2`: Redis Slave 2 + Sentinel 3
+
+Please note that after the initial configuration, if a failover is initiated
+by the Sentinel nodes, the Redis nodes will be reconfigured and the **Master**
+will change permanently (including in `redis.conf`) from one node to the other,
+until a new failover is initiated again.
+
+The same thing will happen with `sentinel.conf` that will be overriten after the
+initial execution, after any new sentinel node starts watching the **Master**,
+or a failover promotes a different **Master** node.
+
+### Configuration for Redis Master
+
+**Example configation for Redis Master:**
 
 In `/etc/gitlab/gitlab.rb`:
 
 ```ruby
-## Redis TCP support (will disable UNIX socket transport)
-redis['bind'] = '0.0.0.0' # or specify an IP to bind to a single one
+redis_master_role['enable'] = true
+
+redis['bind'] = '10.0.0.1'
 redis['port'] = 6379
 redis['password'] = 'redis-password-goes-here'
 redis['master_password'] = 'redis-password-goes-here'
 ```
-
 Reconfigure Omnibus GitLab for the changes to take effect: `sudo gitlab-ctl reconfigure`
 
-**Configuring Slave Redis instances**
+### Configuration for Redis Slave
+
+**Example configation for Slave 1:**
 
-You need to make the same changes listed for the `Master` instance,
-with an additional `Slave` section as in the example below:
+In `/etc/gitlab/gitlab.rb`:
 
 ```ruby
-redis['bind'] = '0.0.0.0' # or specify an IP to bind to a single one
+redis_slave_role['enable'] = true
+
+redis['bind'] = '10.0.0.2'
 redis['port'] = 6379
 redis['password'] = 'redis-password-goes-here'
 redis['master_password'] = 'redis-password-goes-here'
 
-## Slave redis instance
-redis['master'] = false
-redis['master_ip'] = '10.10.10.10' # IP of master Redis server
-redis['master_port'] = 6379 # Port of master Redis server
+redis['master_ip'] = '10.0.0.1' # IP of master Redis server
+#redis['master_port'] = 6379 # Port of master Redis server, uncomment to change to non default
 ```
 
 Reconfigure Omnibus GitLab for the changes to take effect: `sudo gitlab-ctl reconfigure`
 
----
-
-Now that the Redis servers are all set up, let's configure the Sentinel
-servers.
+**Example configation for Slave 2:**
 
-If you are not sure if your Redis servers are working and replicating
-correctly, please read the [Troubleshooting  Replication](#troubleshooting-replication)
-and fix it before proceeding with Sentinel setup.
+In `/etc/gitlab/gitlab.rb`:
 
-### Configuring Sentinel
+```ruby
+redis_slave_role['enable'] = true
 
-You must have at least `3` Redis Sentinel servers, and they need to
-be each in a independent machine. You can configure them in the same
-machines where you've configured the other Redis servers.
+redis['bind'] = '10.0.0.3'
+redis['port'] = 6379
+redis['password'] = 'redis-password-goes-here'
+redis['master_password'] = 'redis-password-goes-here'
 
-This number is required for the consensus algorithm to be effective
-in the case of a failure. **You should always have an `odd` number
-of Sentinel nodes provisioned**.
+redis['master_ip'] = '10.0.0.1' # IP of master Redis server
+#redis['master_port'] = 6379 # Port of master Redis server, uncomment to change to non default
+```
 
-#### How sentinel handles a failover
+Reconfigure Omnibus GitLab for the changes to take effect: `sudo gitlab-ctl reconfigure`
 
-If (`quorum` value of) Sentinels  agree the fact the `master` is not reachable,
-Sentinels will try to elect a temporary `Leader`. The **Majority** of the
-Sentinels must agree to start a failover.
+### Configuration for Sentinel (EE only)
 
-If you don't have the **Majority** of the Sentinels online (for example if you
-are under a network partitioning), a failover **will not be started**.
+Please note that some of the variables are already configured previously
+as they are required for Redis replication.
 
-For example, for a cluster of `3` Sentinels, at least `2` must agree on a
-`Leader`. If you have total of `5` at least `3` must agree on a `Leader`.
+**Example configation for Sentinel 1:**
 
-The `quorum` is only used to detect failure, not to elect the `Leader`.
+In `/etc/gitlab/gitlab.rb`:
 
-Official [Sentinel documentation](http://redis.io/topics/sentinel#example-sentinel-deployments)
-also lists different network topologies and warns againts situations like
-network partition and how it can affect the state of the HA solution. Make
-sure you read it carefully and understand the implications in your current
-setup.
+```ruby
+redis_sentinel_role['enable'] = true
 
-GitLab Enterprise Edition provides [automated way to setup and run](#sentinel-setup-ee-only) the Sentinel daemon.
+redis['master_name'] = 'gitlab-redis' # must be the same in every sentinel node
+redis['master_ip'] = '10.0.0.1' # ip of the initial master redis instance
+#redis['master_port'] = 6379 # port of the initial master redis instance, uncomment to change to non default
+redis['master_password'] = 'redis-password-goes-here' # the same value defined in redis['password'] in the master instance
 
-#### Sentinel setup
+## Configure Sentinel
+sentinel['bind'] = '10.0.0.1'
+# sentinel['port'] = 26379 # uncomment to change default port
 
-##### Community Edition
+## Quorum must reflect the amount of voting sentinels it take to start a failover.
+## Value must NOT be greater then the ammount of sentinels.
+##
+## The quorum can be used to tune Sentinel in two ways:
+## 1. If a the quorum is set to a value smaller than the majority of Sentinels
+##    we deploy, we are basically making Sentinel more sensible to master failures,
+##    triggering a failover as soon as even just a minority of Sentinels is no longer
+##    able to talk with the master.
+## 1. If a quorum is set to a value greater than the majority of Sentinels, we are
+##    making Sentinel able to failover only when there are a very large number (larger
+##    than majority) of well connected Sentinels which agree about the master being down.s
+sentinel['quorum'] = 2
 
-With GitLab Community Edition, you need to install, configure, execute and
-monitor Sentinel from source. Omnibus GitLab Community Edition package does
-not support Sentinel configuration.
+## Consider unresponsive server down after x amount of ms.
+# sentinel['down_after_milliseconds'] = 10000
 
-See documentation for Source Install [here](redis_source.md).
+## Specifies the failover timeout in milliseconds. It is used in many ways:
+##
+## - The time needed to re-start a failover after a previous failover was
+##   already tried against the same master by a given Sentinel, is two
+##   times the failover timeout.
+##
+## - The time needed for a slave replicating to a wrong master according
+##   to a Sentinel current configuration, to be forced to replicate
+##   with the right master, is exactly the failover timeout (counting since
+##   the moment a Sentinel detected the misconfiguration).
+##
+## - The time needed to cancel a failover that is already in progress but
+##   did not produced any configuration change (SLAVEOF NO ONE yet not
+##   acknowledged by the promoted slave).
+##
+## - The maximum time a failover in progress waits for all the slaves to be
+##   reconfigured as slaves of the new master. However even after this time
+##   the slaves will be reconfigured by the Sentinels anyway, but not with
+##   the exact parallel-syncs progression as specified.
+# sentinel['failover_timeout'] = 60000
+```
 
-##### Enterprise Edition
+**Example configation for Sentinel 2:**
 
-To setup sentinel, edit `/etc/gitlab/gitlab.rb` file:
+In `/etc/gitlab/gitlab.rb`:
 
 ```ruby
+redis_sentinel_role['enable'] = true
 
-## When you install Sentinel in a separate machine, you need to control which
-## other services will be running in it.
-## We've simplified the choice using special "roles" settings:
+redis['master_name'] = 'gitlab-redis' # must be the same in every sentinel node
+redis['master_ip'] = '10.0.0.1' # ip of the initial master redis instance
+#redis['master_port'] = 6379 # port of the initial master redis instance, uncomment to change to non default
+redis['master_password'] = 'redis-password-goes-here' # the same value defined in redis['password'] in the master instance
 
-## Enabled Sentinel and Redis Master services
-redis_sentinel_role['enable'] = true
-redis_master_role['enable'] = true
+## Configure Sentinel
+sentinel['bind'] = '10.0.0.2'
+# sentinel['port'] = 26379 # uncomment to change default port
+
+## Quorum must reflect the amount of voting sentinels it take to start a failover.
+## Value must NOT be greater then the ammount of sentinels.
+##
+## The quorum can be used to tune Sentinel in two ways:
+## 1. If a the quorum is set to a value smaller than the majority of Sentinels
+##    we deploy, we are basically making Sentinel more sensible to master failures,
+##    triggering a failover as soon as even just a minority of Sentinels is no longer
+##    able to talk with the master.
+## 1. If a quorum is set to a value greater than the majority of Sentinels, we are
+##    making Sentinel able to failover only when there are a very large number (larger
+##    than majority) of well connected Sentinels which agree about the master being down.s
+sentinel['quorum'] = 2
 
-## Enabled Sentinel and Redis Slave services
+## Consider unresponsive server down after x amount of ms.
+# sentinel['down_after_milliseconds'] = 10000
+
+## Specifies the failover timeout in milliseconds. It is used in many ways:
+##
+## - The time needed to re-start a failover after a previous failover was
+##   already tried against the same master by a given Sentinel, is two
+##   times the failover timeout.
+##
+## - The time needed for a slave replicating to a wrong master according
+##   to a Sentinel current configuration, to be forced to replicate
+##   with the right master, is exactly the failover timeout (counting since
+##   the moment a Sentinel detected the misconfiguration).
+##
+## - The time needed to cancel a failover that is already in progress but
+##   did not produced any configuration change (SLAVEOF NO ONE yet not
+##   acknowledged by the promoted slave).
+##
+## - The maximum time a failover in progress waits for all the slaves to be
+##   reconfigured as slaves of the new master. However even after this time
+##   the slaves will be reconfigured by the Sentinels anyway, but not with
+##   the exact parallel-syncs progression as specified.
+# sentinel['failover_timeout'] = 60000
+```
+
+**Example configation for Sentinel 3:**
+
+In `/etc/gitlab/gitlab.rb`:
+
+```ruby
 redis_sentinel_role['enable'] = true
-redis_slave_role['enable'] = true
 
-## Configure Redis
 redis['master_name'] = 'gitlab-redis' # must be the same in every sentinel node
 redis['master_ip'] = '10.0.0.1' # ip of the initial master redis instance
-redis['master_port'] = 6379 # port of the initial master redis instance
+#redis['master_port'] = 6379 # port of the initial master redis instance, uncomment to change to non default
 redis['master_password'] = 'redis-password-goes-here' # the same value defined in redis['password'] in the master instance
 
 ## Configure Sentinel
-# sentinel['bind'] = '0.0.0.0' # bind to all interfaces, uncomment to specify an IP and bind to a single one
+sentinel['bind'] = '10.0.0.3'
 # sentinel['port'] = 26379 # uncomment to change default port
 
 ## Quorum must reflect the amount of voting sentinels it take to start a failover.
@@ -323,6 +650,8 @@ sentinel['quorum'] = 2
 # sentinel['failover_timeout'] = 60000
 ```
 
+### Control running services
+
 In the example above we've used `redis_sentinel_role` and `redis_master_role`
 which simplify the ammount of configuration changes.
 
@@ -365,37 +694,6 @@ mailroom['enable'] = false
 # Redis Slave role also change this setting from default 'true' to 'false':
 redis['master'] = false
 ```
----
-
-The final part is to inform the main GitLab application server of the Redis
-master and the new sentinels servers.
-
-### GitLab setup
-
-You can enable or disable Sentinel support at any time in new or existing
-installations. From the GitLab application perspective, all it requires is
-the correct credentials for the Sentinel nodes.
-
-While it doesn't require a list of all Sentinel nodes, in case of a failure,
-it needs to access at one of listed ones.
-
->**Note:**
-The following steps should be performed in the [GitLab application server](gitlab.md)
-which ideally should not have Redis or Sentinels in the same machine for a HA setup.
-
-1. Edit `/etc/gitlab/gitlab.rb` and add/change the following lines:
-
-    ```ruby
-    redis['master_name'] = "gitlab-redis"
-    redis['master_password'] = 'redis-password-goes-here'
-    gitlab_rails['redis_sentinels'] = [
-      {'host' => '10.10.10.1', 'port' => 26379},
-      {'host' => '10.10.10.2', 'port' => 26379},
-      {'host' => '10.10.10.3', 'port' => 26379}
-    ]
-    ```
-
-1. [Reconfigure] GitLab for the changes to take effect.
 
 ## Troubleshooting
 
diff --git a/doc/administration/high_availability/redis_source.md b/doc/administration/high_availability/redis_source.md
index 7e8c8c2b4b9..ab5bb13f070 100644
--- a/doc/administration/high_availability/redis_source.md
+++ b/doc/administration/high_availability/redis_source.md
@@ -153,7 +153,7 @@ outside (Internet).
 We will use the same `3` nodes with **Redis** + **Sentinel** topology
 discussed in the [Configuring Redis for GitLab HA](redis.md) documentation.
 
-Here is a list and description of each **machine** and the assined **ip**:
+Here is a list and description of each **machine** and the assigned **IP**:
 
 * `10.0.0.1`: Redis Master + Sentinel 1
 * `10.0.0.2`: Redis Slave 1 + Sentinel 2
@@ -170,7 +170,7 @@ or a failover promotes a different **Master** node.
 
 ### Configuring Redis Master
 
-`redis.conf`:
+**Example configation for Redis Master - `redis.conf`:**
 
 ```conf
 bind 10.0.0.1
@@ -181,7 +181,7 @@ masterauth redis-password-goes-here
 
 ### Configuring Redis Slaves
 
-**Slave 1 - `redis.conf`:**
+**Example configation for Slave 1 - `redis.conf`:**
 
 ```conf
 bind 10.0.0.2
@@ -193,7 +193,7 @@ masterauth redis-password-goes-here
 slaveof 10.0.0.1 6379
 ```
 
-**Slave 2 - `redis.conf`:**
+**Example configation for Slave 2 - `redis.conf`:**
 
 ```conf
 bind 10.0.0.3
@@ -211,7 +211,7 @@ For this example, **Sentinel 1** will be configured in the same machine as the
 **Redis Master**, **Sentinel 2** and **Sentinel 3** in the same machines as the
 **Slave 1** and **Slave 2** respectively.
 
-Sentinel 1 - `sentinel.conf`
+**Example configation for Sentinel 1 - `sentinel.conf`:**
 
 ```conf
 bind 10.0.0.1
@@ -222,7 +222,7 @@ sentinel down-after-milliseconds gitlab-redis 10000
 sentinel failover_timeout 30000
 ```
 
-Sentinel 2 - `sentinel.conf`
+**Example configation for Sentinel 2 - `sentinel.conf`:**
 
 ```conf
 bind 10.0.0.2
@@ -233,7 +233,7 @@ sentinel down-after-milliseconds gitlab-redis 10000
 sentinel failover_timeout 30000
 ```
 
-Sentinel 3 - `sentinel.conf`
+**Example configation for Sentinel 3 - `sentinel.conf`:**
 
 ```conf
 bind 10.0.0.3
-- 
cgit v1.2.1


From 646f81afac23b74b604c77af61254f90e205505f Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axilleas@axilleas.me>
Date: Thu, 10 Nov 2016 13:14:22 +0100
Subject: Fix typos of Redis sentinel docs

---
 doc/administration/high_availability/redis.md | 44 +++++++++++++--------------
 1 file changed, 22 insertions(+), 22 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md
index 6b16f9e791f..ca773ea20aa 100644
--- a/doc/administration/high_availability/redis.md
+++ b/doc/administration/high_availability/redis.md
@@ -5,7 +5,7 @@ topology with **Sentinel** service to watch and automatically start
 failover proceedings.
 
 You can choose to install and manage Redis and Sentinel yourself, use
-a hosted, managed clouse solution or you can use or you can use the one
+a hosted, managed cloud solution or you can use or you can use the one
 that comes bundled with Omnibus GitLab packages.
 
 > **Note:** Redis requires authentication for High Availability. See
@@ -55,10 +55,10 @@ technology and provide a transparent proxy, which means that GitLab doesn't
 need any additional change, or will use Sentinel and manage it for you.
 
 If your provider, uses Sentinel method, see [GitLab Setup](#gitlab-setup)
-to understant where you need to provide the list of servers and credentials.
+to understand where you need to provide the list of servers and credentials.
 
 If you want to setup Redis by yourself, without using Omnibus, you can
-read our documentation: [Configuring Redis for GitLab HA (Source Install)](redis_source.md)
+read our documentation: [Configuring Redis for GitLab HA (source install)](redis_source.md).
 
 ## High Availability with Sentinel
 
@@ -73,19 +73,19 @@ High Availability with Redis requires a few things:
 - Multiple Redis instances
 - Run Redis in a **Master** x **Slave** topology
 - Multiple Sentinel instances
-- Application support and visiblity to all Sentinel and Redis instances
+- Application support and visibility to all Sentinel and Redis instances
 
 Redis Sentinel can handle the most important tasks in a HA environment to help
 keep servers online with minimal to no downtime:
 
 - Monitors **Master** and **Slaves** instances to see if they are available
-- Promote a **Slave** to **Master** when the **Master** fails.
+- Promote a **Slave** to **Master** when the **Master** fails
 - Demote a **Master** to **Slave** when failed **Master** comes back online (to prevent
-  data-partitioning).
-- Can be queried by clients to always connect to the current **Master** server.
+  data-partitioning)
+- Can be queried by clients to always connect to the current **Master** server
 
-When a **Master** fails to respond, it's the client responsability to handle timeout
-and reconnect (querying a **Sentinel** for a new **Master**).
+When a **Master** fails to respond, it's the client's responsibility to handle
+timeout and reconnect (querying a **Sentinel** for a new **Master**).
 
 To get a better understanding on how to correctly setup Sentinel, please read
 the [Redis Sentinel documentation](http://redis.io/topics/sentinel) first, as
@@ -113,7 +113,7 @@ the shared environment can bring your entire setup down.
 
 You also need to take in consideration the underlying network topology,
 making sure you have redundant connectivity between Redis / Sentinel and
-GitLab instances, otherwhise the networks will become a single point of
+GitLab instances, otherwise the networks will become a single point of
 failure.
 
 Read carefully how to configure the components below.
@@ -132,7 +132,7 @@ simultaneously down.
 
 Please note that there are different requirements for Sentinel nodes.
 If you host them in the same Redis machines, you may need to take
-that restrictions into consideration when calculating the ammount of
+that restrictions into consideration when calculating the amount of
 nodes to be provisioned. See [Sentinel setup](#sentinel-setup)
 documentation for more information.
 
@@ -171,10 +171,10 @@ the same Sentinels.
 
 Sentinels watches both other sentinels and Redis nodes. Whenever a Sentinel
 detects that a Redis node is not responding, it will announce that to the
-other sentinels. You have to reach the **quorum**, the minimum ammount of
+other sentinels. You have to reach the **quorum**, the minimum amount of
 sentinels that agrees that a node is down, to be able to start a failover.
 
-Whenver the **quorum** is met, you need the **majority** of all known
+Whenever the **quorum** is met, you need the **majority** of all known
 Sentinel nodes to be available and reachable, to elect the Sentinel **leader**
 who will take all the decisions to restore the service availability by:
 
@@ -238,7 +238,7 @@ independent machines, both with **Redis** and **Sentinel**:
 - Redis Slave + Sentinel
 
 Make sure you've read [Redis Setup](#redis-setup) and [Sentinel Setup](#sentinel-setup)
-before, to understant how and why the ammount of nodes came from.
+before, to understand how and why the amount of nodes came from.
 
 For a recommended setup, that can resist more failures, you will install
 the Omnibus GitLab package in `5` independent machines, both with
@@ -259,11 +259,11 @@ This is a summary of what are we going to do:
      independent ones.
    - Don't install Redis and Sentinel in the same machines your GitLab instance
      is running on.
-   - All machines must be able to talk to each other and accept incomming
+   - All machines must be able to talk to each other and accept incoming
      connection over Redis (`6379`) and Sentinel (`26379`) ports.
    - GitLab machines must be able to access these machines and with the same
      permissions.
-   - Protected them from indiscriminated access from external networks (Internet),
+   - Protected them from indiscriminating access from external networks (Internet),
      to harden the security.
 
 1. Download/install Omnibus GitLab using **steps 1 and 2** from
@@ -288,7 +288,7 @@ inside it.
 Your single-machine install will be the initial **Master**, and the `3` others
 should be configured as **Slave** pointing to this machine.
 
-After replication catchs-up, you will need to stop services in the
+After replication catches up, you will need to stop services in the
 single-machine install, to rotate the **Master** to one of the new nodes.
 
 Make the required changes in configuration and restart the new nodes again.
@@ -310,7 +310,7 @@ You will need to configure the following in `/etc/gitlab/gitlab.rb`:
 
 1. Define a `redis['bind']` address pointing to a local IP that your other machines
    can reach you.
-   - If you really need to bind to an external acessible IP, make
+   - If you really need to bind to an external accessible IP, make
    sure you add extra firewall rules to prevent unauthorized access.
    - You can also set bind to `0.0.0.0` which listen in all interfaces.
 
@@ -332,7 +332,7 @@ You will need to configure the following in `/etc/gitlab/gitlab.rb`:
 
 1. Define a `redis['bind']` address pointing to a local IP that your other machines
    can reach you.
-   - If you really need to bind to an external acessible IP, make
+   - If you really need to bind to an external accessible IP, make
    sure you add extra firewall rules to prevent unauthorized access.
    - You can also set bind to `0.0.0.0` which listen in all interfaces.
 
@@ -384,7 +384,7 @@ installations. From the GitLab application perspective, all it requires is
 the correct credentials for the Sentinel nodes.
 
 While it doesn't require a list of all Sentinel nodes, in case of a failure,
-it needs to access at least one of listeds.
+it needs to access at least one of the listed.
 
 >**Note:**
 The following steps should be performed in the [GitLab application server](gitlab.md)
@@ -425,7 +425,7 @@ by the Sentinel nodes, the Redis nodes will be reconfigured and the **Master**
 will change permanently (including in `redis.conf`) from one node to the other,
 until a new failover is initiated again.
 
-The same thing will happen with `sentinel.conf` that will be overriten after the
+The same thing will happen with `sentinel.conf` that will be overridden after the
 initial execution, after any new sentinel node starts watching the **Master**,
 or a failover promotes a different **Master** node.
 
@@ -653,7 +653,7 @@ sentinel['quorum'] = 2
 ### Control running services
 
 In the example above we've used `redis_sentinel_role` and `redis_master_role`
-which simplify the ammount of configuration changes.
+which simplify the amount of configuration changes.
 
 If you want more control, here is what each one sets for you automatically
 when enabled:
-- 
cgit v1.2.1


From c43b540095b6de03e679dc4dd56df97f08a6aed0 Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axilleas@axilleas.me>
Date: Thu, 10 Nov 2016 13:21:34 +0100
Subject: Move experimental heading at the bottom under changelog

---
 doc/administration/high_availability/redis.md | 59 +++++++++++++++------------
 1 file changed, 33 insertions(+), 26 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md
index ca773ea20aa..3837a8a0a88 100644
--- a/doc/administration/high_availability/redis.md
+++ b/doc/administration/high_availability/redis.md
@@ -19,28 +19,29 @@ that comes bundled with Omnibus GitLab packages.
 
 - [Using an external Redis server](#using-an-external-redis-server)
 - [High Availability with Sentinel](#high-availability-with-sentinel)
-  - [Prerequisites](#prerequisites)
-  - [Redis setup](#redis-setup)
-  - [Experimental Redis Sentinel support](#experimental-redis-sentinel-support)
-  - [Sentinel setup](#sentinel-setup)
-  - [Recommended setup](#recommended-setup)
+    - [Prerequisites](#prerequisites)
+    - [Redis setup](#redis-setup)
+    - [Sentinel setup](#sentinel-setup)
+    - [Recommended setup](#recommended-setup)
 - [Configuring instances using Omnibus](#configuring-instances-using-omnibus)
-  - [Existing single-machine installation](#existing-single-machine-installation)
-  - [Configuring Master Redis instance](#configuring-master-redis-instance)
-  - [Configuring Slave Redis instances](#configuring-slave-redis-instances)
-  - [Configuring Sentinel instances](#configuring-sentinel-instances)
-      - [Community Edition](#community-edition)
-      - [Enterprise Edition](#enterprise-edition)
-  - [GitLab setup](#gitlab-setup)
+    - [Existing single-machine installation](#existing-single-machine-installation)
+    - [Configuring Master Redis instance](#configuring-master-redis-instance)
+    - [Configuring Slave Redis instances](#configuring-slave-redis-instances)
+    - [Configuring Sentinel instances](#configuring-sentinel-instances)
+            - [Community Edition](#community-edition)
+            - [Enterprise Edition](#enterprise-edition)
+    - [GitLab setup](#gitlab-setup)
 - [Example Configurations](#example-configurations)
-  - [Configuration for Redis Master](#configuration-for-redis-master)
-  - [Configuration for Redis Slave](#configuration-for-redis-slave)
-  - [Configuration for Sentinel (EE only)](#configuration-for-sentinel-ee-only)
-  - [Control running services](#control-running-services)
+    - [Configuration for Redis Master](#configuration-for-redis-master)
+    - [Configuration for Redis Slave](#configuration-for-redis-slave)
+    - [Configuration for Sentinel (EE only)](#configuration-for-sentinel-ee-only)
+    - [Control running services](#control-running-services)
 - [Troubleshooting](#troubleshooting)
-  - [Redis replication](#redis-replication)
-  - [Sentinel](#sentinel)
-    - [Omnibus GitLab](#omnibus-gitlab)
+    - [Redis replication](#redis-replication)
+    - [Sentinel](#sentinel)
+        - [Omnibus GitLab](#omnibus-gitlab)
+- [Changelog](#changelog)
+    - [Experimental Redis Sentinel support](#experimental-redis-sentinel-support)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -160,13 +161,6 @@ a failover, as the nodes will be managed by the Sentinels, and even after a
 `gitlab-ctl reconfigure`, they will get their configuration restored by
 the same Sentinels.
 
-### Experimental Redis Sentinel support
-
-   > Experimental Redis Sentinel support was [Introduced][ce-1877] in GitLab 8.11.
-     Starting with 8.14, Redis Sentinel is no longer experimental.
-     If you used with versions `< 8.14` before, please check the updated
-     documentation here.
-
 ### Sentinel setup
 
 Sentinels watches both other sentinels and Redis nodes. Whenever a Sentinel
@@ -815,6 +809,19 @@ To make sure your configuration is correct:
     You should see a different port after a few seconds delay
     (the failover/reconnect time).
 
+
+## Changelog
+
+Changes to Redis HA over time.
+
+### Experimental Redis Sentinel support
+
+>
+Experimental Redis Sentinel support was [Introduced][ce-1877] in GitLab 8.11.
+Starting with 8.14, Redis Sentinel is no longer experimental.
+If you used with versions `< 8.14` before, please check the updated
+documentation here.
+
 ---
 
 Read more on high-availability configuration:
-- 
cgit v1.2.1


From fb0dff6ea848f58a068030f93e8728ce0143c592 Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axilleas@axilleas.me>
Date: Thu, 10 Nov 2016 15:51:13 +0100
Subject: Move some things over

---
 doc/administration/high_availability/redis.md | 195 +++++++++++++++-----------
 1 file changed, 112 insertions(+), 83 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md
index 3837a8a0a88..5d4dfe22779 100644
--- a/doc/administration/high_availability/redis.md
+++ b/doc/administration/high_availability/redis.md
@@ -1,73 +1,105 @@
 # Configuring Redis for GitLab HA
 
-High Availability with Redis is possible using a **Master** x **Slave**
-topology with **Sentinel** service to watch and automatically start
-failover proceedings.
+High Availability with [Redis] is possible using a **Master** x **Slave**
+topology with a [Redis Sentinel][sentinel] service to watch and automatically
+start failover proceedings.
 
 You can choose to install and manage Redis and Sentinel yourself, use
-a hosted, managed cloud solution or you can use or you can use the one
-that comes bundled with Omnibus GitLab packages.
+a hosted cloud solution or you can use the one that comes bundled with
+Omnibus GitLab packages.
 
-> **Note:** Redis requires authentication for High Availability. See
+> **Notes:**
+- Redis requires authentication for High Availability. See
   [Redis Security](http://redis.io/topics/security) documentation for more
   information. We recommend using a combination of a Redis password and tight
   firewall rules to secure your Redis service.
+- You are highly encouraged to read the [Redis Sentinel][sentinel] documentation
+  before configuring Redis HA with GitLab to fully understand the topology and
+  architecture.
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 **Table of Contents**
 
-- [Using an external Redis server](#using-an-external-redis-server)
-- [High Availability with Sentinel](#high-availability-with-sentinel)
-    - [Prerequisites](#prerequisites)
-    - [Redis setup](#redis-setup)
-    - [Sentinel setup](#sentinel-setup)
-    - [Recommended setup](#recommended-setup)
+- [Overview](#overview)
+  - [Available setups](#available-setups)
+  - [Using a non-Omnibus external Redis server](#using-a-non-omnibus-external-redis-server)
+  - [High Availability with Sentinel](#high-availability-with-sentinel)
+  - [Prerequisites](#prerequisites)
+  - [Recommended setup](#recommended-setup)
+- [Redis HA configuration](#redis-ha-configuration)
+  - [Redis setup](#redis-setup)
+  - [Sentinel setup](#sentinel-setup)
 - [Configuring instances using Omnibus](#configuring-instances-using-omnibus)
-    - [Existing single-machine installation](#existing-single-machine-installation)
-    - [Configuring Master Redis instance](#configuring-master-redis-instance)
-    - [Configuring Slave Redis instances](#configuring-slave-redis-instances)
-    - [Configuring Sentinel instances](#configuring-sentinel-instances)
-            - [Community Edition](#community-edition)
-            - [Enterprise Edition](#enterprise-edition)
-    - [GitLab setup](#gitlab-setup)
-- [Example Configurations](#example-configurations)
-    - [Configuration for Redis Master](#configuration-for-redis-master)
-    - [Configuration for Redis Slave](#configuration-for-redis-slave)
-    - [Configuration for Sentinel (EE only)](#configuration-for-sentinel-ee-only)
-    - [Control running services](#control-running-services)
+  - [Existing single-machine installation](#existing-single-machine-installation)
+  - [Configuring Master Redis instance](#configuring-master-redis-instance)
+  - [Configuring Slave Redis instances](#configuring-slave-redis-instances)
+  - [Configuring Sentinel instances](#configuring-sentinel-instances)
+      - [Community Edition](#community-edition)
+      - [Enterprise Edition](#enterprise-edition)
+  - [GitLab setup](#gitlab-setup)
+- [Minimal example configuration with 1 master, 2 slaves and 3 sentinels](#minimal-example-configuration-with-1-master-2-slaves-and-3-sentinels)
+  - [Configuration for Redis Master](#configuration-for-redis-master)
+  - [Configuration for Redis Slave](#configuration-for-redis-slave)
+  - [Configuration for Sentinel (EE only)](#configuration-for-sentinel-ee-only)
+  - [Control running services](#control-running-services)
 - [Troubleshooting](#troubleshooting)
-    - [Redis replication](#redis-replication)
-    - [Sentinel](#sentinel)
-        - [Omnibus GitLab](#omnibus-gitlab)
+  - [Redis replication](#redis-replication)
+  - [Sentinel](#sentinel)
+    - [Omnibus GitLab](#omnibus-gitlab)
 - [Changelog](#changelog)
-    - [Experimental Redis Sentinel support](#experimental-redis-sentinel-support)
+  - [Experimental Redis Sentinel support](#experimental-redis-sentinel-support)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
-## Using an external Redis server
+
+## Overview
+
+Before diving into the details of setting up Redis and Redis Sentinel for HA,
+make sure you read this section to better understand the underline architecture.
+
+### Available setups
+
+Based on your infrastructure setup, there are multiple ways to setup Redis HA
+with GitLab. Omnibus GitLab packages have Redis and Redis Sentinel bundled with
+them to save you the hassle to install it yourself. Pick the one that suits your
+needs.
+
+- **Installations from source:** You need to install Redis and Redis Sentinel
+  yourself. Use the [Redis HA source install](redis_source.md) guide.
+- **Omnibus Community Edition (CE):** Redis is bundled so you can use the
+  package with only the Redis service enabled (works for both master and slave
+  setups).
+- **Omnibus Enterprise Edition (EE):** Both Redis and Redis Sentinel are bundled
+  in the Omnibus package so you can use only them to setup the whole Redis HA
+  infrastructure (master, slave and Sentinel).
+
+Note that with the Omnibus packages (both CE and EE), you can also use an
+[external Redis server](#using-a-non-omnibus-external-redis-server).
+
+### Using a non-Omnibus external Redis server
 
 If you're hosting GitLab on a cloud provider, you can optionally use a
 managed service for Redis. For example, AWS offers a managed ElastiCache service
 that runs Redis.
 
 Managed services can provide High Availability using their own proprietary
-technology and provide a transparent proxy, which means that GitLab doesn't
-need any additional change, or will use Sentinel and manage it for you.
+technology and provide a transparent proxy (which means that GitLab doesn't
+need any additional change) or they will use Sentinel and manage it for you.
 
-If your provider, uses Sentinel method, see [GitLab Setup](#gitlab-setup)
+If your provider, uses Sentinel, see [GitLab Setup](#gitlab-setup)
 to understand where you need to provide the list of servers and credentials.
 
 If you want to setup Redis by yourself, without using Omnibus, you can
-read our documentation: [Configuring Redis for GitLab HA (source install)](redis_source.md).
-
-## High Availability with Sentinel
+read the documentation on [configuring Redis HA for source installs](redis_source.md).
 
-> Since GitLab `8.11`, you can configure a list of Redis Sentinel servers that
-will monitor a group of Redis servers to provide failover support.
+### High Availability with Sentinel
 
-> With GitLab `8.14`, we bundled Redis Sentinel as part of Omnibus package and
-improved the way you use and configure it.
+>
+- Since GitLab `8.11`, you can configure a list of Redis Sentinel servers that
+  will monitor a group of Redis servers to provide failover support.
+- With GitLab `8.14`, we bundled Redis Sentinel as part of Omnibus package and
+  improved the way you use and configure it.
 
 High Availability with Redis requires a few things:
 
@@ -77,12 +109,12 @@ High Availability with Redis requires a few things:
 - Application support and visibility to all Sentinel and Redis instances
 
 Redis Sentinel can handle the most important tasks in a HA environment to help
-keep servers online with minimal to no downtime:
+keep servers online with minimal to no downtime. Redis Sentinel:
 
 - Monitors **Master** and **Slaves** instances to see if they are available
-- Promote a **Slave** to **Master** when the **Master** fails
-- Demote a **Master** to **Slave** when failed **Master** comes back online (to prevent
-  data-partitioning)
+- Promotes a **Slave** to **Master** when the **Master** fails
+- Demotes a **Master** to **Slave** when failed **Master** comes back online
+  (to prevent data-partitioning)
 - Can be queried by clients to always connect to the current **Master** server
 
 When a **Master** fails to respond, it's the client's responsibility to handle
@@ -93,24 +125,16 @@ the [Redis Sentinel documentation](http://redis.io/topics/sentinel) first, as
 failing to configure it correctly can lead to data loss, or can bring your
 whole cluster down, invalidating the failover effort.
 
-This documentation will provide you with a minimal and a recommended topology
-that can resist to some levels of failure. Usually the more Redis and Sentinel
-instances you have provisioned, the better will be your availability.
-
-The configuration consists of three parts:
-
-- Setup Redis Master and Slave nodes
-- Setup Sentinel nodes
-- Setup GitLab
-
 ### Prerequisites
 
 You need at least `3` independent machines: physical, or VMs running into
-distinct physical machines. They must be believed to fail in an
-independent way.
+distinct physical machines. It is essential that all master and Redis slaves
+run in different machines. If you fail to provision the machines in that
+specific way, any issue with the shared environment can bring your entire setup
+down.
 
-If you fail to provision the machines in that specific way, any issue with
-the shared environment can bring your entire setup down.
+It is OK to run a Sentinel along with a master or slave Redis instance.
+No more than one though.
 
 You also need to take in consideration the underlying network topology,
 making sure you have redundant connectivity between Redis / Sentinel and
@@ -119,6 +143,30 @@ failure.
 
 Read carefully how to configure the components below.
 
+### Recommended setup
+
+For a minimal setup, you will install the Omnibus GitLab package in `3`
+independent machines, both with **Redis** and **Sentinel**:
+
+- Redis Master + Sentinel
+- Redis Slave + Sentinel
+- Redis Slave + Sentinel
+
+Make sure you've read [Redis Setup](#redis-setup) and [Sentinel Setup](#sentinel-setup)
+before, to understand how and why the amount of nodes came from.
+
+For a recommended setup, that can resist more failures, you will install
+the Omnibus GitLab package in `5` independent machines, both with
+**Redis** and **Sentinel**:
+
+- Redis Master + Sentinel
+- Redis Slave + Sentinel
+- Redis Slave + Sentinel
+- Redis Slave + Sentinel
+- Redis Slave + Sentinel
+
+## Redis HA configuration
+
 ### Redis setup
 
 You must have at least `3` Redis servers: `1` Master, `2` Slaves, and they
@@ -156,14 +204,14 @@ Initial **Slave** nodes requires `redis['master']` defined to `false` and
 simplified configuration by enabling `redis_slave_role['enable']`, you
 just need to fill in the `redis['master_ip']`.
 
-This values doesn't have to be changed again in `/etc/gitlab/gitlab.rb` after
+This values don't have to be changed again in `/etc/gitlab/gitlab.rb` after
 a failover, as the nodes will be managed by the Sentinels, and even after a
 `gitlab-ctl reconfigure`, they will get their configuration restored by
 the same Sentinels.
 
 ### Sentinel setup
 
-Sentinels watches both other sentinels and Redis nodes. Whenever a Sentinel
+Sentinels watch both other sentinels and Redis nodes. Whenever a Sentinel
 detects that a Redis node is not responding, it will announce that to the
 other sentinels. You have to reach the **quorum**, the minimum amount of
 sentinels that agrees that a node is down, to be able to start a failover.
@@ -222,33 +270,12 @@ official documentation:
   the slaves will be reconfigured by the Sentinels anyway, but not with
   the exact parallel-syncs progression as specified.
 
-### Recommended setup
-
-For a minimal setup, you will install the Omnibus GitLab package in `3`
-independent machines, both with **Redis** and **Sentinel**:
-
-- Redis Master + Sentinel
-- Redis Slave + Sentinel
-- Redis Slave + Sentinel
-
-Make sure you've read [Redis Setup](#redis-setup) and [Sentinel Setup](#sentinel-setup)
-before, to understand how and why the amount of nodes came from.
-
-For a recommended setup, that can resist more failures, you will install
-the Omnibus GitLab package in `5` independent machines, both with
-**Redis** and **Sentinel**:
-
-- Redis Master + Sentinel
-- Redis Slave + Sentinel
-- Redis Slave + Sentinel
-- Redis Slave + Sentinel
-- Redis Slave + Sentinel
-
 ## Configuring instances using Omnibus
 
 This is a summary of what are we going to do:
 
 1. Provision the required number of instances specified previously
+
    - You can opt to install Redis and Sentinel in the same machine or each in
      independent ones.
    - Don't install Redis and Sentinel in the same machines your GitLab instance
@@ -257,7 +284,7 @@ This is a summary of what are we going to do:
      connection over Redis (`6379`) and Sentinel (`26379`) ports.
    - GitLab machines must be able to access these machines and with the same
      permissions.
-   - Protected them from indiscriminating access from external networks (Internet),
+   - Protect them from access from external networks (Internet),
      to harden the security.
 
 1. Download/install Omnibus GitLab using **steps 1 and 2** from
@@ -394,7 +421,7 @@ which ideally should not have Redis or Sentinels in the same machine for a HA se
 
 See [example configuration](#configuration-for-gitlab) below.
 
-## Example Configurations
+## Minimal example configuration with 1 master, 2 slaves and 3 sentinels
 
 In this example we consider that all servers have an internal network
 interface with IPs in the `10.0.0.x` range, and that they can connect
@@ -836,3 +863,5 @@ Read more on high-availability configuration:
 [reconfigure]: ../restart_gitlab.md#omnibus-gitlab-reconfigure
 [gh-531]: https://github.com/redis/redis-rb/issues/531
 [gh-534]: https://github.com/redis/redis-rb/issues/534
+[redis]: http://redis.io/
+[sentinel]: http://redis.io/topics/sentinel
-- 
cgit v1.2.1


From 1d3ada80ad6cb9a4927512fdf4018907bf3098a6 Mon Sep 17 00:00:00 2001
From: Patricio Cano <suprnova32@gmail.com>
Date: Mon, 7 Nov 2016 15:44:55 -0600
Subject: Added documentation and CHANGELOG item.

---
 doc/administration/operations.md                   |   1 +
 .../operations/img/sidekiq_job_throttling.png      | Bin 0 -> 114784 bytes
 .../operations/sidekiq_job_throttling.md           |  32 +++++++++++++++++++++
 3 files changed, 33 insertions(+)
 create mode 100644 doc/administration/operations/img/sidekiq_job_throttling.png
 create mode 100644 doc/administration/operations/sidekiq_job_throttling.md

(limited to 'doc/administration')

diff --git a/doc/administration/operations.md b/doc/administration/operations.md
index 4b582d16b64..0daceb98d99 100644
--- a/doc/administration/operations.md
+++ b/doc/administration/operations.md
@@ -1,6 +1,7 @@
 # GitLab operations
 
 - [Sidekiq MemoryKiller](operations/sidekiq_memory_killer.md)
+- [Sidekiq Job throttling](operations/sidekiq_job_throttling.md)
 - [Cleaning up Redis sessions](operations/cleaning_up_redis_sessions.md)
 - [Understanding Unicorn and unicorn-worker-killer](operations/unicorn.md)
 - [Moving repositories to a new location](operations/moving_repositories.md)
diff --git a/doc/administration/operations/img/sidekiq_job_throttling.png b/doc/administration/operations/img/sidekiq_job_throttling.png
new file mode 100644
index 00000000000..7f29a4d3c46
Binary files /dev/null and b/doc/administration/operations/img/sidekiq_job_throttling.png differ
diff --git a/doc/administration/operations/sidekiq_job_throttling.md b/doc/administration/operations/sidekiq_job_throttling.md
new file mode 100644
index 00000000000..33cedee7ebd
--- /dev/null
+++ b/doc/administration/operations/sidekiq_job_throttling.md
@@ -0,0 +1,32 @@
+# Sidekiq Job throttling
+
+> Note: Introduced with GitLab 8.14
+
+When your GitLab installation needs to handle tens of thousands of background
+jobs, it can be convenient to prioritize queues that need to be executed
+immediately, e.g. user initiated actions like merging a Merge Request.
+
+In order to accomplish this, you can limit the amount of workers that certain
+slow running queues get can have available. This is what we call Sidekiq Job
+Throttling. Depending on your infrastructure, you might have different slow
+running queues, which is why you can choose which queues to throttle and by
+how much you want to throttle them.
+
+These settings are available in the Application Settings of your GitLab
+installation.
+
+![Sidekiq Job Throttling](img/sidekiq_job_throttling.png)
+
+The throttle factor determines the maximum number of workers a queue can run on.
+This value gets multiplied by `:concurrency` value set in the Sidekiq settings
+and rounded up to the closest full integer.
+
+So, for example, you set the `:concurrency` to 25 and the `Throttling factor` to
+0.1, the maximum workers assigned to the selected queues would be 3.
+
+```
+limit = (factor * Sidekiq.options[:concurrency]).ceil
+```
+
+After enabling the job throttling, you will need to restart your GitLab
+instance, in order for the changes to take effect.
\ No newline at end of file
-- 
cgit v1.2.1


From b575b00402da92d15f8edcaab702039e6e92eddc Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axilleas@axilleas.me>
Date: Thu, 10 Nov 2016 19:00:06 +0100
Subject: Rearrange sections in Sentinel docs

[ci skip]
---
 doc/administration/high_availability/redis.md | 343 ++++++++++++++------------
 1 file changed, 181 insertions(+), 162 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md
index 5d4dfe22779..3eaa0ffdcec 100644
--- a/doc/administration/high_availability/redis.md
+++ b/doc/administration/high_availability/redis.md
@@ -16,82 +16,67 @@ Omnibus GitLab packages.
 - You are highly encouraged to read the [Redis Sentinel][sentinel] documentation
   before configuring Redis HA with GitLab to fully understand the topology and
   architecture.
+- This is the documentation for the Omnibus packages. For installations from
+  source, follow the [Redis HA source install](redis_source.md) guide.
+- Redis Sentinel is bundled with Omnibus GitLab Enterprise Edition only. For the
+  Omnibus Community Edition and installations from source, follow the
+  [Redis HA source install](redis_source.md) guide.
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 **Table of Contents**
 
 - [Overview](#overview)
-  - [Available setups](#available-setups)
-  - [Using a non-Omnibus external Redis server](#using-a-non-omnibus-external-redis-server)
-  - [High Availability with Sentinel](#high-availability-with-sentinel)
   - [Prerequisites](#prerequisites)
+  - [High Availability with Sentinel](#high-availability-with-sentinel)
   - [Recommended setup](#recommended-setup)
+  - [Available configuration setups](#available-configuration-setups)
+  - [Using a non-Omnibus external Redis server](#using-a-non-omnibus-external-redis-server)
+  - [Redis setup overview](#redis-setup-overview)
+  - [Sentinel setup overview](#sentinel-setup-overview)
 - [Redis HA configuration](#redis-ha-configuration)
-  - [Redis setup](#redis-setup)
-  - [Sentinel setup](#sentinel-setup)
-- [Configuring instances using Omnibus](#configuring-instances-using-omnibus)
-  - [Existing single-machine installation](#existing-single-machine-installation)
-  - [Configuring Master Redis instance](#configuring-master-redis-instance)
-  - [Configuring Slave Redis instances](#configuring-slave-redis-instances)
-  - [Configuring Sentinel instances](#configuring-sentinel-instances)
-      - [Community Edition](#community-edition)
-      - [Enterprise Edition](#enterprise-edition)
-  - [GitLab setup](#gitlab-setup)
+  - [Configuring the Master Redis instance](#configuring-the-master-redis-instance)
+  - [Configuring the Slave Redis instances](#configuring-the-slave-redis-instances)
+  - [Configuring the Sentinel instances](#configuring-the-sentinel-instances)
+  - [Configuring the GitLab application](#configuring-the-gitlab-application)
+- [Switching from an existing single-machine installation to Redis HA](#switching-from-an-existing-single-machine-installation-to-redis-ha)
 - [Minimal example configuration with 1 master, 2 slaves and 3 sentinels](#minimal-example-configuration-with-1-master-2-slaves-and-3-sentinels)
-  - [Configuration for Redis Master](#configuration-for-redis-master)
-  - [Configuration for Redis Slave](#configuration-for-redis-slave)
-  - [Configuration for Sentinel (EE only)](#configuration-for-sentinel-ee-only)
+  - [Configuration for Redis master](#configuration-for-redis-master)
+  - [Configuration for Redis slaves](#configuration-for-redis-slaves)
+  - [Configuration for Sentinels](#configuration-for-sentinels)
+- [Advanced configuration](#advanced-configuration)
   - [Control running services](#control-running-services)
 - [Troubleshooting](#troubleshooting)
-  - [Redis replication](#redis-replication)
-  - [Sentinel](#sentinel)
-    - [Omnibus GitLab](#omnibus-gitlab)
+  - [Troubleshooting Redis replication](#troubleshooting-redis-replication)
+  - [Troubleshooting Sentinel](#troubleshooting-sentinel)
 - [Changelog](#changelog)
   - [Experimental Redis Sentinel support](#experimental-redis-sentinel-support)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
-
 ## Overview
 
 Before diving into the details of setting up Redis and Redis Sentinel for HA,
-make sure you read this section to better understand the underline architecture.
-
-### Available setups
-
-Based on your infrastructure setup, there are multiple ways to setup Redis HA
-with GitLab. Omnibus GitLab packages have Redis and Redis Sentinel bundled with
-them to save you the hassle to install it yourself. Pick the one that suits your
-needs.
-
-- **Installations from source:** You need to install Redis and Redis Sentinel
-  yourself. Use the [Redis HA source install](redis_source.md) guide.
-- **Omnibus Community Edition (CE):** Redis is bundled so you can use the
-  package with only the Redis service enabled (works for both master and slave
-  setups).
-- **Omnibus Enterprise Edition (EE):** Both Redis and Redis Sentinel are bundled
-  in the Omnibus package so you can use only them to setup the whole Redis HA
-  infrastructure (master, slave and Sentinel).
-
-Note that with the Omnibus packages (both CE and EE), you can also use an
-[external Redis server](#using-a-non-omnibus-external-redis-server).
+make sure you read this Overview section to better understand how the components
+are tied together.
 
-### Using a non-Omnibus external Redis server
+### Prerequisites
 
-If you're hosting GitLab on a cloud provider, you can optionally use a
-managed service for Redis. For example, AWS offers a managed ElastiCache service
-that runs Redis.
+You need at least `3` independent machines: physical, or VMs running into
+distinct physical machines. It is essential that all master and slaves Redis
+instances run in different machines. If you fail to provision the machines in
+that specific way, any issue with the shared environment can bring your entire
+setup down.
 
-Managed services can provide High Availability using their own proprietary
-technology and provide a transparent proxy (which means that GitLab doesn't
-need any additional change) or they will use Sentinel and manage it for you.
+It is OK to run a Sentinel along with a master or slave Redis instance.
+No more than one Sentinel in the same machine though.
 
-If your provider, uses Sentinel, see [GitLab Setup](#gitlab-setup)
-to understand where you need to provide the list of servers and credentials.
+You also need to take in consideration the underlying network topology,
+making sure you have redundant connectivity between Redis / Sentinel and
+GitLab instances, otherwise the networks will become a single point of
+failure.
 
-If you want to setup Redis by yourself, without using Omnibus, you can
-read the documentation on [configuring Redis HA for source installs](redis_source.md).
+Read carefully how to configure the components below.
 
 ### High Availability with Sentinel
 
@@ -108,12 +93,12 @@ High Availability with Redis requires a few things:
 - Multiple Sentinel instances
 - Application support and visibility to all Sentinel and Redis instances
 
-Redis Sentinel can handle the most important tasks in a HA environment to help
-keep servers online with minimal to no downtime. Redis Sentinel:
+Redis Sentinel can handle the most important tasks in a HA environment and that's
+to help keep servers online with minimal to no downtime. Redis Sentinel:
 
 - Monitors **Master** and **Slaves** instances to see if they are available
 - Promotes a **Slave** to **Master** when the **Master** fails
-- Demotes a **Master** to **Slave** when failed **Master** comes back online
+- Demotes a **Master** to **Slave** when the failed **Master** comes back online
   (to prevent data-partitioning)
 - Can be queried by clients to always connect to the current **Master** server
 
@@ -122,41 +107,23 @@ timeout and reconnect (querying a **Sentinel** for a new **Master**).
 
 To get a better understanding on how to correctly setup Sentinel, please read
 the [Redis Sentinel documentation](http://redis.io/topics/sentinel) first, as
-failing to configure it correctly can lead to data loss, or can bring your
+failing to configure it correctly can lead to data loss or can bring your
 whole cluster down, invalidating the failover effort.
 
-### Prerequisites
-
-You need at least `3` independent machines: physical, or VMs running into
-distinct physical machines. It is essential that all master and Redis slaves
-run in different machines. If you fail to provision the machines in that
-specific way, any issue with the shared environment can bring your entire setup
-down.
-
-It is OK to run a Sentinel along with a master or slave Redis instance.
-No more than one though.
-
-You also need to take in consideration the underlying network topology,
-making sure you have redundant connectivity between Redis / Sentinel and
-GitLab instances, otherwise the networks will become a single point of
-failure.
-
-Read carefully how to configure the components below.
-
 ### Recommended setup
 
 For a minimal setup, you will install the Omnibus GitLab package in `3`
-independent machines, both with **Redis** and **Sentinel**:
+**independent** machines, both with **Redis** and **Sentinel**:
 
 - Redis Master + Sentinel
 - Redis Slave + Sentinel
 - Redis Slave + Sentinel
 
-Make sure you've read [Redis Setup](#redis-setup) and [Sentinel Setup](#sentinel-setup)
-before, to understand how and why the amount of nodes came from.
+If you are not sure or don't understand why and where the amount of nodes come
+from, read [Redis Setup](#redis-setup) and [Sentinel Setup](#sentinel-setup).
 
-For a recommended setup, that can resist more failures, you will install
-the Omnibus GitLab package in `5` independent machines, both with
+For a recommended setup that can resist more failures, you will install
+the Omnibus GitLab package in `5` **independent** machines, both with
 **Redis** and **Sentinel**:
 
 - Redis Master + Sentinel
@@ -165,9 +132,42 @@ the Omnibus GitLab package in `5` independent machines, both with
 - Redis Slave + Sentinel
 - Redis Slave + Sentinel
 
-## Redis HA configuration
+### Available configuration setups
+
+Based on your infrastructure setup and how you have installed GitLab, there are
+multiple ways to configure Redis HA. Omnibus GitLab packages have Redis and/or
+Redis Sentinel bundled with them to save you the hassle to install them yourself.
+Pick the one that suits your needs.
+
+- [Installations from source][source]: You need to install Redis and Sentinel
+  yourself. Use the [Redis HA source install](redis_source.md) guide.
+- [Omnibus package Community Edition (CE)][ce]: Redis is bundled, so you can use the
+  package with only the Redis service enabled (works for both master and slave
+  setups).
+- [Omnibus package Enterprise Edition (EE)][ee]: Both Redis and Sentinel are bundled,
+  so you can use the EE package to setup the whole Redis HA infrastructure
+  (master, slave and Sentinel).
+
+Note that if you have installed GitLab using the Omnibus packages (both CE and EE),
+you can also use an [external Redis server](#using-a-non-omnibus-external-redis-server).
+
+### Using a non-Omnibus external Redis server
+
+If you're hosting GitLab on a cloud provider, you can optionally use a
+managed service for Redis. For example, AWS offers a managed ElastiCache service
+that runs Redis.
+
+Managed services can provide High Availability using their own proprietary
+technology and provide a transparent proxy (which means that GitLab doesn't
+need any additional change) or they will use Sentinel and manage it for you.
+
+If your provider uses Sentinel, see [GitLab Setup](#gitlab-setup)
+to understand where you need to provide the list of servers and credentials.
+
+If you want to setup Redis by yourself, without using Omnibus, you can
+read the documentation on [configuring Redis HA for source installs](redis_source.md).
 
-### Redis setup
+### Redis setup overview
 
 You must have at least `3` Redis servers: `1` Master, `2` Slaves, and they
 need to be each in a independent machine (see explanation above).
@@ -194,22 +194,7 @@ protect all Redis nodes and the Sentinels. They will all share the same
 password, and all instances must be able to talk to
 each other over the network.
 
-Redis nodes will need the same password defined in `redis['password']` and
-`redis['master_password']`, no matter if **Master** or **Slave**. At any time
-during a failover the Sentinels can reconfigure a node and change it's status
-from **Master** to **Slave** and vice versa.
-
-Initial **Slave** nodes requires `redis['master']` defined to `false` and
-`redis['master_ip']` pointing to the initial **Master**. If you use the
-simplified configuration by enabling `redis_slave_role['enable']`, you
-just need to fill in the `redis['master_ip']`.
-
-This values don't have to be changed again in `/etc/gitlab/gitlab.rb` after
-a failover, as the nodes will be managed by the Sentinels, and even after a
-`gitlab-ctl reconfigure`, they will get their configuration restored by
-the same Sentinels.
-
-### Sentinel setup
+### Sentinel setup overview
 
 Sentinels watch both other sentinels and Redis nodes. Whenever a Sentinel
 detects that a Redis node is not responding, it will announce that to the
@@ -249,8 +234,11 @@ is not achieved (see the odd number of nodes requirement above). In that case,
 a new attempt will be made after the amount of time defined in
 `sentinel['failover_timeout']` (in milliseconds).
 
-The `failover_time` variable have a lot of different usages, according to
-official documentation:
+>**Note:**
+We will see where `sentinel['failover_timeout']` is defined later.
+
+The `failover_timeout` variable has a lot of different use cases, according to
+the official documentation:
 
 - The time needed to re-start a failover after a previous failover was
   already tried against the same master by a given Sentinel, is two
@@ -270,18 +258,29 @@ official documentation:
   the slaves will be reconfigured by the Sentinels anyway, but not with
   the exact parallel-syncs progression as specified.
 
-## Configuring instances using Omnibus
+## Redis HA configuration
+
+This is the section where we install and setup the new Redis instances.
 
-This is a summary of what are we going to do:
+>**Notes:**
+- We assume that you install GitLab and all HA components from scratch. If you
+  already have it installed and running, read how to
+  [switch from a single-machine installation to Redis HA](#switching-from-an-existing-single-machine-installation-to-redis-ha).
+- Redis nodes (both master and slaves) will need the same password defined in
+  `redis['password']` and `redis['master_password']`. At any time   during a
+  failover the Sentinels can reconfigure a node and change its status
+  from master to slave and vice versa.
 
-1. Provision the required number of instances specified previously
+A summary of what are we going to do:
 
+1. Provision the required number of instances specified previously:
    - You can opt to install Redis and Sentinel in the same machine or each in
      independent ones.
-   - Don't install Redis and Sentinel in the same machines your GitLab instance
+   - Don't install Redis and Sentinel in the same machines your GitLab application
      is running on.
    - All machines must be able to talk to each other and accept incoming
-     connection over Redis (`6379`) and Sentinel (`26379`) ports.
+     connections over Redis (`6379`) and Sentinel (`26379`) ports (unless you
+     change the default ports).
    - GitLab machines must be able to access these machines and with the same
      permissions.
    - Protect them from access from external networks (Internet),
@@ -297,32 +296,10 @@ This is a summary of what are we going to do:
    from running on upgrade. Only the primary GitLab application server should
    handle migrations.
 
-1. Create/edit `/etc/gitlab/gitlab.rb` and make the changes based on the
+1. Edit `/etc/gitlab/gitlab.rb` and make the changes based on the
    [Example Configurations](#example-configurations).
 
-### Existing single-machine installation
-
-If you already have a single-machine GitLab install running, you will need to
-replicate from this machine first, before de-activating the Redis instance
-inside it.
-
-Your single-machine install will be the initial **Master**, and the `3` others
-should be configured as **Slave** pointing to this machine.
-
-After replication catches up, you will need to stop services in the
-single-machine install, to rotate the **Master** to one of the new nodes.
-
-Make the required changes in configuration and restart the new nodes again.
-
-To disable redis in the single install, edit `/etc/gitlab/gitlab.rb`:
-
-```ruby
-redis['enable'] = false
-```
-
-If you fail to replicate first, you may loose data (unprocessed background jobs).
-
-### Configuring Master Redis instance
+### Configuring the Master Redis instance
 
 You will need to configure the following in `/etc/gitlab/gitlab.rb`:
 
@@ -341,9 +318,9 @@ You will need to configure the following in `/etc/gitlab/gitlab.rb`:
 1. Set up a password authentication with `redis['password']` and
    `redis['master_password']` (use the same password in all nodes).
 
-Reconfigure Omnibus GitLab for the changes to take effect: `sudo gitlab-ctl reconfigure`
+1. [Reconfigure Omnibus GitLab][reocnfigure] for the changes to take effect.
 
-### Configuring Slave Redis instances
+### Configuring the Slave Redis instances
 
 You will need to configure the following in `/etc/gitlab/gitlab.rb`:
 
@@ -367,7 +344,22 @@ You will need to configure the following in `/etc/gitlab/gitlab.rb`:
 
 1. Define `redis['master_port']` with the port of the **Master** Redis (default to `6379`).
 
-### Configuring Sentinel instances
+Initial **Slave** nodes require `redis['master']` defined to `false` and
+`redis['master_ip']` pointing to the initial **Master**. If you use the
+simplified configuration by enabling `redis_slave_role['enable']`, you
+just need to fill in the `redis['master_ip']`.
+
+This values don't have to be changed again in `/etc/gitlab/gitlab.rb` after
+a failover, as the nodes will be managed by the Sentinels, and even after a
+`gitlab-ctl reconfigure`, they will get their configuration restored by
+the same Sentinels.
+
+### Configuring the Sentinel instances
+
+>**Note:**
+- Redis Sentinel is bundled with Omnibus GitLab Enterprise Edition only. For the
+  Omnibus Community Edition and installations from source, follow the
+  [Redis HA source install](redis_source.md) guide.
 
 Now that the Redis servers are all set up, let's configure the Sentinel
 servers.
@@ -380,22 +372,12 @@ You must have at least `3` Redis Sentinel servers, and they need to
 be each in a independent machine. You can configure them in the same
 machines where you've configured the other Redis servers.
 
-##### Community Edition
-
-With GitLab Community Edition, you need to install, configure, execute and
-monitor Sentinel from source. Omnibus GitLab Community Edition package does
-not support Sentinel configuration.
-
-See [documentation for Source Install](redis_source.md).
-
-##### Enterprise Edition
-
-With GitLab Enterprise Edition, you can use Omnibus package to setup multiple
-machines with Sentinel daemon.
+With GitLab Enterprise Edition, you can use the Omnibus package to setup multiple
+machines with the Sentinel daemon.
 
 See [example configuration](#configuration-for-sentinel-ee-only) below.
 
-### GitLab setup
+### Configuring the GitLab application
 
 The final part is to inform the main GitLab application server of the Redis
 Sentinels servers and authentication credentials.
@@ -409,7 +391,7 @@ it needs to access at least one of the listed.
 
 >**Note:**
 The following steps should be performed in the [GitLab application server](gitlab.md)
-which ideally should not have Redis or Sentinels in the same machine for a HA setup.
+which ideally should not have Redis or Sentinels on it for a HA setup.
 
 1. Edit `/etc/gitlab/gitlab.rb` and add/change the following lines:
 
@@ -417,10 +399,32 @@ which ideally should not have Redis or Sentinels in the same machine for a HA se
   - `redis['master_password']` - the same password you've defined before for Redis and Sentinels
   - `gitlab_rails['redis_sentinels']` - a list of sentinels with `host` and `port`
 
-1. [Reconfigure] GitLab for the changes to take effect.
+1. [Reconfigure Omnibus GitLab][reconfigure] for the changes to take effect.
 
 See [example configuration](#configuration-for-gitlab) below.
 
+## Switching from an existing single-machine installation to Redis HA
+
+If you already have a single-machine GitLab install running, you will need to
+replicate from this machine first, before de-activating the Redis instance
+inside it.
+
+Your single-machine install will be the initial **Master**, and the `3` others
+should be configured as **Slave** pointing to this machine.
+
+After replication catches up, you will need to stop services in the
+single-machine install, to rotate the **Master** to one of the new nodes.
+
+Make the required changes in configuration and restart the new nodes again.
+
+To disable redis in the single install, edit `/etc/gitlab/gitlab.rb`:
+
+```ruby
+redis['enable'] = false
+```
+
+If you fail to replicate first, you may loose data (unprocessed background jobs).
+
 ## Minimal example configuration with 1 master, 2 slaves and 3 sentinels
 
 In this example we consider that all servers have an internal network
@@ -428,7 +432,7 @@ interface with IPs in the `10.0.0.x` range, and that they can connect
 to each other using these IPs.
 
 In a real world usage, you would also setup firewall rules to prevent
-unauthorized access from other machines, and block traffic from the
+unauthorized access from other machines and block traffic from the
 outside (Internet).
 
 We will use the same `3` nodes with **Redis** + **Sentinel** topology
@@ -450,7 +454,7 @@ The same thing will happen with `sentinel.conf` that will be overridden after th
 initial execution, after any new sentinel node starts watching the **Master**,
 or a failover promotes a different **Master** node.
 
-### Configuration for Redis Master
+### Configuration for Redis master
 
 **Example configation for Redis Master:**
 
@@ -464,9 +468,10 @@ redis['port'] = 6379
 redis['password'] = 'redis-password-goes-here'
 redis['master_password'] = 'redis-password-goes-here'
 ```
-Reconfigure Omnibus GitLab for the changes to take effect: `sudo gitlab-ctl reconfigure`
 
-### Configuration for Redis Slave
+[Reconfigure Omnibus GitLab][reconfigure] for the changes to take effect.
+
+### Configuration for Redis slaves
 
 **Example configation for Slave 1:**
 
@@ -502,9 +507,14 @@ redis['master_ip'] = '10.0.0.1' # IP of master Redis server
 #redis['master_port'] = 6379 # Port of master Redis server, uncomment to change to non default
 ```
 
-Reconfigure Omnibus GitLab for the changes to take effect: `sudo gitlab-ctl reconfigure`
+[Reconfigure Omnibus GitLab][reconfigure] for the changes to take effect.
+
+### Configuration for Sentinels
 
-### Configuration for Sentinel (EE only)
+>**Note:**
+Redis Sentinel is bundled with Omnibus GitLab Enterprise Edition only. For the
+Omnibus Community Edition and installations from source, follow the
+[Redis HA source install](redis_source.md) guide.
 
 Please note that some of the variables are already configured previously
 as they are required for Redis replication.
@@ -517,9 +527,9 @@ In `/etc/gitlab/gitlab.rb`:
 redis_sentinel_role['enable'] = true
 
 redis['master_name'] = 'gitlab-redis' # must be the same in every sentinel node
+redis['master_password'] = 'redis-password-goes-here' # the same value defined in redis['password'] in the master instance
 redis['master_ip'] = '10.0.0.1' # ip of the initial master redis instance
 #redis['master_port'] = 6379 # port of the initial master redis instance, uncomment to change to non default
-redis['master_password'] = 'redis-password-goes-here' # the same value defined in redis['password'] in the master instance
 
 ## Configure Sentinel
 sentinel['bind'] = '10.0.0.1'
@@ -571,9 +581,9 @@ In `/etc/gitlab/gitlab.rb`:
 redis_sentinel_role['enable'] = true
 
 redis['master_name'] = 'gitlab-redis' # must be the same in every sentinel node
+redis['master_password'] = 'redis-password-goes-here' # the same value defined in redis['password'] in the master instance
 redis['master_ip'] = '10.0.0.1' # ip of the initial master redis instance
 #redis['master_port'] = 6379 # port of the initial master redis instance, uncomment to change to non default
-redis['master_password'] = 'redis-password-goes-here' # the same value defined in redis['password'] in the master instance
 
 ## Configure Sentinel
 sentinel['bind'] = '10.0.0.2'
@@ -625,9 +635,9 @@ In `/etc/gitlab/gitlab.rb`:
 redis_sentinel_role['enable'] = true
 
 redis['master_name'] = 'gitlab-redis' # must be the same in every sentinel node
+redis['master_password'] = 'redis-password-goes-here' # the same value defined in redis['password'] in the master instance
 redis['master_ip'] = '10.0.0.1' # ip of the initial master redis instance
 #redis['master_port'] = 6379 # port of the initial master redis instance, uncomment to change to non default
-redis['master_password'] = 'redis-password-goes-here' # the same value defined in redis['password'] in the master instance
 
 ## Configure Sentinel
 sentinel['bind'] = '10.0.0.3'
@@ -671,10 +681,15 @@ sentinel['quorum'] = 2
 # sentinel['failover_timeout'] = 60000
 ```
 
+## Advanced configuration
+
+Omnibus GitLab configures some things behind the curtains to make the sysadmins'
+lives easier. If you want to know what happens underneath keep reading.
+
 ### Control running services
 
-In the example above we've used `redis_sentinel_role` and `redis_master_role`
-which simplify the amount of configuration changes.
+In the previous example above we've used `redis_sentinel_role` and
+`redis_master_role` which simplify the amount of configuration changes.
 
 If you want more control, here is what each one sets for you automatically
 when enabled:
@@ -716,13 +731,15 @@ mailroom['enable'] = false
 redis['master'] = false
 ```
 
+You can find the relevant attributes defined in [gitlab_rails.rb][omnifile].
+
 ## Troubleshooting
 
 There are a lot of moving parts that needs to be taken care carefully
 in order for the HA setup to work as expected.
 
-Before proceeding with the troubleshooting below, check your firewall
-rules:
+Before proceeding with the troubleshooting below, check your firewall rules:
+
 - Redis machines
    - Accept TCP connection in `6379`
    - Connect to the other Redis machines via TCP in `6379`
@@ -731,7 +748,7 @@ rules:
    - Connect to other Sentinel machines via TCP in `26379`
    - Connect to the Redis machines via TCP in `6379`
 
-### Redis replication
+### Troubleshooting Redis replication
 
 You can check if everything is correct by connecting to each server using
 `redis-cli` application, and sending the `INFO` command.
@@ -781,9 +798,7 @@ repl_backlog_first_byte_offset:0
 repl_backlog_histlen:0
 ```
 
-### Sentinel
-
-#### Omnibus GitLab
+### Troubleshooting Sentinel
 
 If you get an error like: `Redis::CannotConnectError: No sentinels available.`,
 there may be something wrong with your configuration files or it can be related
@@ -865,3 +880,7 @@ Read more on high-availability configuration:
 [gh-534]: https://github.com/redis/redis-rb/issues/534
 [redis]: http://redis.io/
 [sentinel]: http://redis.io/topics/sentinel
+[omnifile]: https://gitlab.com/gitlab-org/omnibus-gitlab/blob/82b7345b150f072c8673c79738ce893f92d0d652/files/gitlab-cookbooks/gitlab/libraries/gitlab_rails.rb#L134-159
+[source]: ../../install/installation.md
+[ce]: https://about.gitlab.com/downloads
+[ee]: https://about.gitlab.com/downloads-ee
-- 
cgit v1.2.1


From cc2bf503dbeb23561302bb77ff824e0c30a560b6 Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axilleas@axilleas.me>
Date: Fri, 11 Nov 2016 17:53:26 +0100
Subject: Add missing link to GH issue

---
 doc/administration/high_availability/redis_source.md | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/high_availability/redis_source.md b/doc/administration/high_availability/redis_source.md
index ab5bb13f070..20630b070c0 100644
--- a/doc/administration/high_availability/redis_source.md
+++ b/doc/administration/high_availability/redis_source.md
@@ -8,7 +8,8 @@ If you are building packages for a specific distro, or trying to build some
 internal automation, you can check this documentation to learn about the
 minimal setup, required changes, etc.
 
-If you want to see the documentation for Omnibus GitLab Install, please [read it here](redis.md).
+If you want to see the documentation for Omnibus GitLab Install, please
+[read it here](redis.md).
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
@@ -38,7 +39,7 @@ You will also need to define equal password for slave password definition
 
 To configure Redis to use TCP connection you need to define both
 `bind` and `port`. You can bind to all interfaces (`0.0.0.0`) or specify the
-ip of the desired interface (for ex. one from an internal network).
+IP of the desired interface (for ex. one from an internal network).
 
 
 ### Configuring Master Redis instance
@@ -46,7 +47,7 @@ ip of the desired interface (for ex. one from an internal network).
 You need to make the following changes in `redis.conf`:
 
 1. Define a `bind` address pointing to a local IP that your other machines
-   can reach you. If you really need to bind to an external acessible IP, make
+   can reach you. If you really need to bind to an external accessible IP, make
    sure you add extra firewall rules to prevent unauthorized access:
 
 1. Define a `port` to force redis to listen on TCP so other machines can
@@ -79,7 +80,7 @@ starting with `sentinel` prefix.
 You will need to define the initial configs to enable connectivity:
 
 1. Define a `bind` address pointing to a local IP that your other machines
-   can reach you. If you really need to bind to an external acessible IP, make
+   can reach you. If you really need to bind to an external accessible IP, make
    sure you add extra firewall rules to prevent unauthorized access:
 
 1. Define a `port` to force sentinel to listen on TCP so other machines can
@@ -95,7 +96,7 @@ And the sentinel specific ones:
    If you need more information to understand about quorum, please
    read the detailed explanation in the [HA documentation for Omnibus Installs](redis.md).
 
-1. Define with `sentinel down-after-milliseconds` the ammount in `ms` of time
+1. Define with `sentinel down-after-milliseconds` the amount in `ms` of time
    that an unresponsive server will be considered down.
 
 1. Define a value for `sentinel failover_timeout` in `ms`. This has multiple
@@ -164,7 +165,7 @@ by the Sentinel nodes, the Redis nodes will be reconfigured and the **Master**
 will change permanently (including in `redis.conf`) from one node to the other,
 until a new failover is initiated again.
 
-The same thing will happen with `sentinel.conf` that will be overriten after the
+The same thing will happen with `sentinel.conf` that will be overridden after the
 initial execution, after any new sentinel node starts watching the **Master**,
 or a failover promotes a different **Master** node.
 
@@ -284,3 +285,5 @@ production:
 ```
 
 When in doubt, please read [Redis Sentinel documentation](http://redis.io/topics/sentinel)
+
+[gh-531]: https://github.com/redis/redis-rb/issues/531
-- 
cgit v1.2.1


From e840749b84ceb226e46ebdfb489c735e3370cff7 Mon Sep 17 00:00:00 2001
From: Patricio Cano <suprnova32@gmail.com>
Date: Thu, 10 Nov 2016 11:36:52 -0600
Subject: Refactored Sidekiq Throttler and updated documentation

---
 doc/administration/operations/sidekiq_job_throttling.md | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/operations/sidekiq_job_throttling.md b/doc/administration/operations/sidekiq_job_throttling.md
index 33cedee7ebd..ddeaa22e288 100644
--- a/doc/administration/operations/sidekiq_job_throttling.md
+++ b/doc/administration/operations/sidekiq_job_throttling.md
@@ -3,14 +3,15 @@
 > Note: Introduced with GitLab 8.14
 
 When your GitLab installation needs to handle tens of thousands of background
-jobs, it can be convenient to prioritize queues that need to be executed
-immediately, e.g. user initiated actions like merging a Merge Request.
+jobs, it can be convenient to throttle queues that do not need to be executed
+immediately, e.g. long running jobs like Pipelines, thus allowing jobs that do
+need to be executed immediately to have access to more resources.
 
 In order to accomplish this, you can limit the amount of workers that certain
-slow running queues get can have available. This is what we call Sidekiq Job
+slow running queues can have available. This is what we call Sidekiq Job
 Throttling. Depending on your infrastructure, you might have different slow
-running queues, which is why you can choose which queues to throttle and by
-how much you want to throttle them.
+running queues, which is why you can choose which queues you want to throttle 
+and by how much you want to throttle them.
 
 These settings are available in the Application Settings of your GitLab
 installation.
@@ -24,8 +25,8 @@ and rounded up to the closest full integer.
 So, for example, you set the `:concurrency` to 25 and the `Throttling factor` to
 0.1, the maximum workers assigned to the selected queues would be 3.
 
-```
-limit = (factor * Sidekiq.options[:concurrency]).ceil
+```ruby
+queue_limit = (factor * Sidekiq.options[:concurrency]).ceil
 ```
 
 After enabling the job throttling, you will need to restart your GitLab
-- 
cgit v1.2.1


From 3a1b21febba669f71da13e5b3ab9fd15cf9450b4 Mon Sep 17 00:00:00 2001
From: Ben Bodenmiller <bbodenmiller@hotmail.com>
Date: Sat, 12 Nov 2016 03:45:33 +0000
Subject: add missing sudo skip-auto-migration

---
 doc/administration/high_availability/database.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/administration')

diff --git a/doc/administration/high_availability/database.md b/doc/administration/high_availability/database.md
index 538dada1bae..76f3a0fb387 100644
--- a/doc/administration/high_availability/database.md
+++ b/doc/administration/high_availability/database.md
@@ -102,7 +102,7 @@ If you use a cloud-managed service, or provide your own PostgreSQL:
 1. Exit the database prompt by typing `\q` and Enter.
 1. Exit the `gitlab-psql` user by running `exit` twice.
 1. Run `sudo gitlab-ctl reconfigure` a final time.
-1. Run `touch /etc/gitlab/skip-auto-migrations` to prevent database migrations
+1. Run `sudo touch /etc/gitlab/skip-auto-migrations` to prevent database migrations
    from running on upgrade. Only the primary GitLab application server should
    handle migrations.
 
-- 
cgit v1.2.1


From bfbf23d788901692a490622b6562b383f6f020b6 Mon Sep 17 00:00:00 2001
From: Ben Bodenmiller <bbodenmiller@hotmail.com>
Date: Sat, 12 Nov 2016 04:05:51 +0000
Subject: update redis server details

---
 doc/administration/high_availability/redis.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md
index bc424330656..8656b42f274 100644
--- a/doc/administration/high_availability/redis.md
+++ b/doc/administration/high_availability/redis.md
@@ -48,15 +48,15 @@ Redis.
     redis['password'] = 'Redis Password'
     ```
 
-1. Run `sudo gitlab-ctl reconfigure` to install and configure PostgreSQL.
+1. Run `sudo touch /etc/gitlab/skip-auto-migrations` to prevent database migrations
+   from running on upgrade. Only the primary GitLab application server should
+   handle migrations.
+
+1. Run `sudo gitlab-ctl reconfigure` to install and configure Redis.
 
     > **Note**: This `reconfigure` step will result in some errors.
       That's OK - don't be alarmed.
 
-1. Run `touch /etc/gitlab/skip-auto-migrations` to prevent database migrations
-   from running on upgrade. Only the primary GitLab application server should
-   handle migrations.
-
 ## Experimental Redis Sentinel support
 
 > [Introduced][ce-1877] in GitLab 8.11.
-- 
cgit v1.2.1


From 5b6c633ed71d844ce26b12f5f5a3e8a0ed85a776 Mon Sep 17 00:00:00 2001
From: Ben Bodenmiller <bbodenmiller@hotmail.com>
Date: Sat, 12 Nov 2016 19:18:28 +0000
Subject: use single quote for consistency

---
 doc/administration/high_availability/nfs.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/administration')

diff --git a/doc/administration/high_availability/nfs.md b/doc/administration/high_availability/nfs.md
index 537f4f3501d..5602d70f1ef 100644
--- a/doc/administration/high_availability/nfs.md
+++ b/doc/administration/high_availability/nfs.md
@@ -76,7 +76,7 @@ configuration to move each data location to a subdirectory:
 user['home'] = '/gitlab-data/home'
 git_data_dir '/gitlab-data/git-data'
 gitlab_rails['shared_path'] = '/gitlab-data/shared'
-gitlab_rails['uploads_directory'] = "/gitlab-data/uploads"
+gitlab_rails['uploads_directory'] = '/gitlab-data/uploads'
 gitlab_ci['builds_directory'] = '/gitlab-data/builds'
 ```
 
-- 
cgit v1.2.1


From 39a9af1594bf2365ba0da6457efef238d7e42e24 Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axilleas@axilleas.me>
Date: Tue, 15 Nov 2016 14:07:38 +0100
Subject: Swap HA setups

---
 doc/administration/high_availability/README.md | 33 +++++++++-------
 doc/administration/high_availability/redis.md  | 54 +++++++++++++-------------
 2 files changed, 45 insertions(+), 42 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/high_availability/README.md b/doc/administration/high_availability/README.md
index d74a786ac24..d5a5aef7ec0 100644
--- a/doc/administration/high_availability/README.md
+++ b/doc/administration/high_availability/README.md
@@ -7,19 +7,10 @@ highly available.
 
 ## Architecture
 
-### Active/Passive
-
-For pure high-availability/failover with no scaling you can use an
-active/passive configuration. This utilizes DRBD (Distributed Replicated
-Block Device) to keep all data in sync. DRBD requires a low latency link to
-remain in sync. It is not advisable to attempt to run DRBD between data centers
-or in different cloud availability zones.
+There are two kinds of setups:
 
-Components/Servers Required:
-
-- 2 servers/virtual machines (one active/one passive)
-
-![Active/Passive HA Diagram](../img/high_availability/active-passive-diagram.png)
+- active/active
+- active/passive
 
 ### Active/Active
 
@@ -28,12 +19,24 @@ user requests simultaneously. The database, Redis, and GitLab application are
 all deployed on separate servers. The configuration is **only** highly-available
 if the database, Redis and storage are also configured as such.
 
-![Active/Active HA Diagram](../img/high_availability/active-active-diagram.png)
-
-**Steps to configure active/active:**
+Follow the steps below to configure an active/active setup:
 
 1. [Configure the database](database.md)
 1. [Configure Redis](redis.md)
 1. [Configure NFS](nfs.md)
 1. [Configure the GitLab application servers](gitlab.md)
 1. [Configure the load balancers](load_balancer.md)
+
+![Active/Active HA Diagram](../img/high_availability/active-active-diagram.png)
+
+### Active/Passive
+
+For pure high-availability/failover with no scaling you can use an
+active/passive configuration. This utilizes DRBD (Distributed Replicated
+Block Device) to keep all data in sync. DRBD requires a low latency link to
+remain in sync. It is not advisable to attempt to run DRBD between data centers
+or in different cloud availability zones.
+
+Components/Servers Required: 2 servers/virtual machines (one active/one passive)
+
+![Active/Passive HA Diagram](../img/high_availability/active-passive-diagram.png)
diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md
index 3eaa0ffdcec..bb46de65e3c 100644
--- a/doc/administration/high_availability/redis.md
+++ b/doc/administration/high_availability/redis.md
@@ -16,10 +16,10 @@ Omnibus GitLab packages.
 - You are highly encouraged to read the [Redis Sentinel][sentinel] documentation
   before configuring Redis HA with GitLab to fully understand the topology and
   architecture.
-- This is the documentation for the Omnibus packages. For installations from
-  source, follow the [Redis HA source install](redis_source.md) guide.
-- Redis Sentinel is bundled with Omnibus GitLab Enterprise Edition only. For the
-  Omnibus Community Edition and installations from source, follow the
+- This is the documentation for the Omnibus GitLab packages. For installations
+  from source, follow the [Redis HA source install](redis_source.md) guide.
+- Redis Sentinel daemon is bundled with Omnibus GitLab Enterprise Edition only.
+  For the Omnibus Community Edition and installations from source, follow the
   [Redis HA source install](redis_source.md) guide.
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
@@ -50,7 +50,6 @@ Omnibus GitLab packages.
   - [Troubleshooting Redis replication](#troubleshooting-redis-replication)
   - [Troubleshooting Sentinel](#troubleshooting-sentinel)
 - [Changelog](#changelog)
-  - [Experimental Redis Sentinel support](#experimental-redis-sentinel-support)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -76,15 +75,16 @@ making sure you have redundant connectivity between Redis / Sentinel and
 GitLab instances, otherwise the networks will become a single point of
 failure.
 
-Read carefully how to configure the components below.
+Make sure that you read this document once as a whole before configuring the
+components below.
 
 ### High Availability with Sentinel
 
 >
-- Since GitLab `8.11`, you can configure a list of Redis Sentinel servers that
-  will monitor a group of Redis servers to provide failover support.
-- With GitLab `8.14`, we bundled Redis Sentinel as part of Omnibus package and
-  improved the way you use and configure it.
+- Starting with GitLab `8.11`, you can configure a list of Redis Sentinel
+  servers that will monitor a group of Redis servers to provide failover support.
+- Starting with GitLab `8.14`, the Omnibus GitLab Enterprise Edition package
+  comes with Redis sentinel daemon support.
 
 High Availability with Redis requires a few things:
 
@@ -136,20 +136,21 @@ the Omnibus GitLab package in `5` **independent** machines, both with
 
 Based on your infrastructure setup and how you have installed GitLab, there are
 multiple ways to configure Redis HA. Omnibus GitLab packages have Redis and/or
-Redis Sentinel bundled with them to save you the hassle to install them yourself.
+Redis Sentinel bundled with them so you only need to focus on configuration.
 Pick the one that suits your needs.
 
 - [Installations from source][source]: You need to install Redis and Sentinel
-  yourself. Use the [Redis HA source install](redis_source.md) guide.
-- [Omnibus package Community Edition (CE)][ce]: Redis is bundled, so you can use the
-  package with only the Redis service enabled (works for both master and slave
-  setups).
-- [Omnibus package Enterprise Edition (EE)][ee]: Both Redis and Sentinel are bundled,
-  so you can use the EE package to setup the whole Redis HA infrastructure
-  (master, slave and Sentinel).
-
-Note that if you have installed GitLab using the Omnibus packages (both CE and EE),
-you can also use an [external Redis server](#using-a-non-omnibus-external-redis-server).
+  yourself. Use the [Redis HA installation from source](redis_source.md) guide.
+- [Omnibus package Community Edition (CE) package][ce]: Redis is bundled, so you
+  can use the package with only the Redis service enabled (works for both master
+  and slave setups). To install and configure Sentinel, you can use the
+  [Redis HA installation from source](redis_source.md) guide.
+- [Omnibus package Enterprise Edition (EE) package][ee]: Both Redis and Sentinel
+  are bundled, so you can use the EE package to setup the whole Redis HA
+  infrastructure (master, slave and Sentinel).
+
+Note that if you have installed GitLab using the Omnibus GitLab packages (both
+CE and EE), you can also use an [external Redis server](#using-a-non-omnibus-external-redis-server).
 
 ### Using a non-Omnibus external Redis server
 
@@ -198,7 +199,7 @@ each other over the network.
 
 Sentinels watch both other sentinels and Redis nodes. Whenever a Sentinel
 detects that a Redis node is not responding, it will announce that to the
-other sentinels. You have to reach the **quorum**, the minimum amount of
+other sentinels. They have to reach the **quorum**, the minimum amount of
 sentinels that agrees that a node is down, to be able to start a failover.
 
 Whenever the **quorum** is met, you need the **majority** of all known
@@ -267,9 +268,8 @@ This is the section where we install and setup the new Redis instances.
   already have it installed and running, read how to
   [switch from a single-machine installation to Redis HA](#switching-from-an-existing-single-machine-installation-to-redis-ha).
 - Redis nodes (both master and slaves) will need the same password defined in
-  `redis['password']` and `redis['master_password']`. At any time   during a
-  failover the Sentinels can reconfigure a node and change its status
-  from master to slave and vice versa.
+  `redis['password']`. At any time during a failover the Sentinels can
+  reconfigure a node and change its status from master to slave and vice versa.
 
 A summary of what are we going to do:
 
@@ -354,7 +354,7 @@ a failover, as the nodes will be managed by the Sentinels, and even after a
 `gitlab-ctl reconfigure`, they will get their configuration restored by
 the same Sentinels.
 
-### Configuring the Sentinel instances
+### Configuring the Redis Sentinel instances
 
 >**Note:**
 - Redis Sentinel is bundled with Omnibus GitLab Enterprise Edition only. For the
@@ -425,7 +425,7 @@ redis['enable'] = false
 
 If you fail to replicate first, you may loose data (unprocessed background jobs).
 
-## Minimal example configuration with 1 master, 2 slaves and 3 sentinels
+## Example of a minimal configuration with 1 master, 2 slaves and 3 sentinels
 
 In this example we consider that all servers have an internal network
 interface with IPs in the `10.0.0.x` range, and that they can connect
-- 
cgit v1.2.1


From 6a5891185c6edde0a300adee30e936d44b6180e0 Mon Sep 17 00:00:00 2001
From: Drew Blessing <drew@gitlab.com>
Date: Tue, 15 Nov 2016 15:03:44 -0600
Subject: Clarify LDAP troubleshooting ldap_search example [ci skip]

A customer noted an error/lack of clarity in the LDAP documentation
with the `ldap_search` example. Previously, if taken literally, the
customer may have expected the `$` variables to be automatically
replaced or if they paste the exact `user_filter` contents the
parentheses would have been incorrect. Let's just simply the filter
and use exactly what's in the configuration.
---
 doc/administration/auth/ldap.md | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

(limited to 'doc/administration')

diff --git a/doc/administration/auth/ldap.md b/doc/administration/auth/ldap.md
index fd23047f027..d3f216fb3bf 100644
--- a/doc/administration/auth/ldap.md
+++ b/doc/administration/auth/ldap.md
@@ -257,6 +257,24 @@ the LDAP server's SSL certificate is performed.
 
 ## Troubleshooting
 
+### Debug LDAP user filter with ldapsearch
+
+This example uses ldapsearch and assumes you are using ActiveDirectory. The
+following query returns the login names of the users that will be allowed to
+log in to GitLab if you configure your own user_filter.
+
+```
+ldapsearch -H ldaps://$host:$port -D "$bind_dn" -y bind_dn_password.txt  -b "$base" "$user_filter" sAMAccountName
+```
+
+- Variables beginning with a `$` refer to a variable from the LDAP section of
+  your configuration file.
+- Replace ldaps:// with ldap:// if you are using the plain authentication method.
+  Port `389` is the default `ldap://` port and `636` is the default `ldaps://`
+  port.
+- We are assuming the password for the bind_dn user is in bind_dn_password.txt.
+
+
 ### Invalid credentials when logging in
 
 - Make sure the user you are binding with has enough permissions to read the user's
-- 
cgit v1.2.1


From 9b70c09d07d180229501799f2d440191853aba57 Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axilleas@axilleas.me>
Date: Tue, 15 Nov 2016 16:08:53 +0100
Subject: Refactor Redis HA docs

[ci skip]
---
 doc/administration/high_availability/redis.md | 547 +++++++++++++++-----------
 1 file changed, 314 insertions(+), 233 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md
index bb46de65e3c..6de92ae3741 100644
--- a/doc/administration/high_availability/redis.md
+++ b/doc/administration/high_availability/redis.md
@@ -17,10 +17,11 @@ Omnibus GitLab packages.
   before configuring Redis HA with GitLab to fully understand the topology and
   architecture.
 - This is the documentation for the Omnibus GitLab packages. For installations
-  from source, follow the [Redis HA source install](redis_source.md) guide.
+  from source, follow the [Redis HA source installation](redis_source.md) guide.
 - Redis Sentinel daemon is bundled with Omnibus GitLab Enterprise Edition only.
-  For the Omnibus Community Edition and installations from source, follow the
-  [Redis HA source install](redis_source.md) guide.
+  For configuring Sentinel with the Omnibus GitLab Community Edition and
+  installations from source, follow the
+  [Redis HA source installation](redis_source.md) guide.
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
@@ -31,16 +32,15 @@ Omnibus GitLab packages.
   - [High Availability with Sentinel](#high-availability-with-sentinel)
   - [Recommended setup](#recommended-setup)
   - [Available configuration setups](#available-configuration-setups)
-  - [Using a non-Omnibus external Redis server](#using-a-non-omnibus-external-redis-server)
   - [Redis setup overview](#redis-setup-overview)
   - [Sentinel setup overview](#sentinel-setup-overview)
-- [Redis HA configuration](#redis-ha-configuration)
-  - [Configuring the Master Redis instance](#configuring-the-master-redis-instance)
-  - [Configuring the Slave Redis instances](#configuring-the-slave-redis-instances)
-  - [Configuring the Sentinel instances](#configuring-the-sentinel-instances)
-  - [Configuring the GitLab application](#configuring-the-gitlab-application)
+- [Configuring Redis HA](#configuring-redis-ha)
+  - [Step 1. Configuring the Master Redis instance](#step-1-configuring-the-master-redis-instance)
+  - [Step 2. Configuring the Slave Redis instances](#step-2-configuring-the-slave-redis-instances)
+  - [Step 3. Configuring the Redis Sentinel instances](#step-3-configuring-the-redis-sentinel-instances)
+  - [Step 4. Configuring the GitLab application](#step-4-configuring-the-gitlab-application)
 - [Switching from an existing single-machine installation to Redis HA](#switching-from-an-existing-single-machine-installation-to-redis-ha)
-- [Minimal example configuration with 1 master, 2 slaves and 3 sentinels](#minimal-example-configuration-with-1-master-2-slaves-and-3-sentinels)
+- [Example of a minimal configuration with 1 master, 2 slaves and 3 sentinels](#example-of-a-minimal-configuration-with-1-master-2-slaves-and-3-sentinels)
   - [Configuration for Redis master](#configuration-for-redis-master)
   - [Configuration for Redis slaves](#configuration-for-redis-slaves)
   - [Configuration for Sentinels](#configuration-for-sentinels)
@@ -50,6 +50,7 @@ Omnibus GitLab packages.
   - [Troubleshooting Redis replication](#troubleshooting-redis-replication)
   - [Troubleshooting Sentinel](#troubleshooting-sentinel)
 - [Changelog](#changelog)
+  - [Experimental Redis Sentinel support](#experimental-redis-sentinel-support)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -59,8 +60,6 @@ Before diving into the details of setting up Redis and Redis Sentinel for HA,
 make sure you read this Overview section to better understand how the components
 are tied together.
 
-### Prerequisites
-
 You need at least `3` independent machines: physical, or VMs running into
 distinct physical machines. It is essential that all master and slaves Redis
 instances run in different machines. If you fail to provision the machines in
@@ -84,16 +83,16 @@ components below.
 - Starting with GitLab `8.11`, you can configure a list of Redis Sentinel
   servers that will monitor a group of Redis servers to provide failover support.
 - Starting with GitLab `8.14`, the Omnibus GitLab Enterprise Edition package
-  comes with Redis sentinel daemon support.
+  comes with Redis Sentinel daemon support.
 
 High Availability with Redis requires a few things:
 
 - Multiple Redis instances
-- Run Redis in a **Master** x **Slave** topology
-- Multiple Sentinel instances
+  - Run Redis in a **Master** x **Slave** topology
+  - Multiple Sentinel instances
 - Application support and visibility to all Sentinel and Redis instances
 
-Redis Sentinel can handle the most important tasks in a HA environment and that's
+Redis Sentinel can handle the most important tasks in an HA environment and that's
 to help keep servers online with minimal to no downtime. Redis Sentinel:
 
 - Monitors **Master** and **Slaves** instances to see if they are available
@@ -120,7 +119,8 @@ For a minimal setup, you will install the Omnibus GitLab package in `3`
 - Redis Slave + Sentinel
 
 If you are not sure or don't understand why and where the amount of nodes come
-from, read [Redis Setup](#redis-setup) and [Sentinel Setup](#sentinel-setup).
+from, read [Redis setup overview](#redis-setup-overview) and
+[Sentinel setup overview](#sentinel-setup-overview).
 
 For a recommended setup that can resist more failures, you will install
 the Omnibus GitLab package in `5` **independent** machines, both with
@@ -149,24 +149,9 @@ Pick the one that suits your needs.
   are bundled, so you can use the EE package to setup the whole Redis HA
   infrastructure (master, slave and Sentinel).
 
-Note that if you have installed GitLab using the Omnibus GitLab packages (both
-CE and EE), you can also use an [external Redis server](#using-a-non-omnibus-external-redis-server).
-
-### Using a non-Omnibus external Redis server
-
-If you're hosting GitLab on a cloud provider, you can optionally use a
-managed service for Redis. For example, AWS offers a managed ElastiCache service
-that runs Redis.
-
-Managed services can provide High Availability using their own proprietary
-technology and provide a transparent proxy (which means that GitLab doesn't
-need any additional change) or they will use Sentinel and manage it for you.
-
-If your provider uses Sentinel, see [GitLab Setup](#gitlab-setup)
-to understand where you need to provide the list of servers and credentials.
-
-If you want to setup Redis by yourself, without using Omnibus, you can
-read the documentation on [configuring Redis HA for source installs](redis_source.md).
+Note that even if you have installed GitLab using the Omnibus GitLab packages
+(both CE and EE), you can still use an
+[external Redis server](#using-a-non-omnibus-external-redis-server).
 
 ### Redis setup overview
 
@@ -197,13 +182,13 @@ each other over the network.
 
 ### Sentinel setup overview
 
-Sentinels watch both other sentinels and Redis nodes. Whenever a Sentinel
+Sentinels watch both other Sentinels and Redis nodes. Whenever a Sentinel
 detects that a Redis node is not responding, it will announce that to the
-other sentinels. They have to reach the **quorum**, the minimum amount of
-sentinels that agrees that a node is down, to be able to start a failover.
+other Sentinels. They have to reach the **quorum**, that is the minimum amount
+of Sentinels that agrees a node is down, in order to be able to start a failover.
 
-Whenever the **quorum** is met, you need the **majority** of all known
-Sentinel nodes to be available and reachable, to elect the Sentinel **leader**
+Whenever the **quorum** is met, the **majority** of all known Sentinel nodes
+need to be available and reachable, so that they can elect the Sentinel **leader**
 who will take all the decisions to restore the service availability by:
 
 - Promoting a new **Master**
@@ -212,7 +197,8 @@ who will take all the decisions to restore the service availability by:
 - Reconfigure the old **Master** and demote to **Slave** when it comes back online
 
 You must have at least `3` Redis Sentinel servers, and they need to
-be each in a independent machine (that are believed to fail independently).
+be each in a independent machine (that are believed to fail independently),
+ideally in different geographical areas.
 
 You can configure them in the same machines where you've configured the other
 Redis servers, but understand that if a whole node goes down, you loose both
@@ -230,7 +216,7 @@ Here are some examples:
 - With `5` or `6` sentinels, a maximum of `2` can go down for a failover begin.
 - With `7` sentinels, a maximum of `3` nodes can go down.
 
-The **Leader** election can sometimes fail the voting round when **consensus**,
+The **Leader** election can sometimes fail the voting round when **consensus**
 is not achieved (see the odd number of nodes requirement above). In that case,
 a new attempt will be made after the amount of time defined in
 `sentinel['failover_timeout']` (in milliseconds).
@@ -238,7 +224,7 @@ a new attempt will be made after the amount of time defined in
 >**Note:**
 We will see where `sentinel['failover_timeout']` is defined later.
 
-The `failover_timeout` variable has a lot of different use cases, according to
+The `failover_timeout` variable has a lot of different use cases. According to
 the official documentation:
 
 - The time needed to re-start a failover after a previous failover was
@@ -259,7 +245,7 @@ the official documentation:
   the slaves will be reconfigured by the Sentinels anyway, but not with
   the exact parallel-syncs progression as specified.
 
-## Redis HA configuration
+## Configuring Redis HA
 
 This is the section where we install and setup the new Redis instances.
 
@@ -271,95 +257,138 @@ This is the section where we install and setup the new Redis instances.
   `redis['password']`. At any time during a failover the Sentinels can
   reconfigure a node and change its status from master to slave and vice versa.
 
-A summary of what are we going to do:
+### Prerequisites
 
-1. Provision the required number of instances specified previously:
-   - You can opt to install Redis and Sentinel in the same machine or each in
-     independent ones.
-   - Don't install Redis and Sentinel in the same machines your GitLab application
-     is running on.
-   - All machines must be able to talk to each other and accept incoming
-     connections over Redis (`6379`) and Sentinel (`26379`) ports (unless you
-     change the default ports).
-   - GitLab machines must be able to access these machines and with the same
-     permissions.
-   - Protect them from access from external networks (Internet),
-     to harden the security.
+The prerequisites for a HA Redis setup are the following:
 
-1. Download/install Omnibus GitLab using **steps 1 and 2** from
-   [GitLab downloads](https://about.gitlab.com/downloads) in each node.
-   - Do not complete other steps on the download page.
-   - Make sure you select the correct Omnibus package, with the same version
-   and type (Community, Enterprise editions) of your current install.
+1. Provision the minimum required number of instances as specified in the
+   [recommended setup](#recommended-setup) section.
+1. **Do NOT** install Redis or Redis Sentinel in the same machines your
+   GitLab application is running on. You can however opt in to install Redis
+   and Sentinel in the same machine (each in independent ones is recommended
+   though).
+1. All Redis nodes must be able to talk to each other and accept incoming
+   connections over Redis (`6379`) and Sentinel (`26379`) ports (unless you
+   change the default ones).
+1. The server that hosts the GitLab application must be able to access the
+   Redis nodes.
+1. Protect the nodes from access from external networks (Internet), using
+   firewall.
 
-1. Run `touch /etc/gitlab/skip-auto-migrations` to prevent database migrations
-   from running on upgrade. Only the primary GitLab application server should
-   handle migrations.
+### Step 1. Configuring the master Redis instance
 
-1. Edit `/etc/gitlab/gitlab.rb` and make the changes based on the
-   [Example Configurations](#example-configurations).
+1. SSH into the **master** Redis server and login as root:
 
-### Configuring the Master Redis instance
+    ```
+    sudo -i
+    ```
 
-You will need to configure the following in `/etc/gitlab/gitlab.rb`:
+1. [Download/install](https://about.gitlab.com/installation) the Omnibus GitLab
+   package using **steps 1 and 2** from the GitLab downloads page.
+     - Make sure you select the correct Omnibus package, with the same version
+       and type (Community, Enterprise editions) of your current install.
+     - Do not complete any other steps on the download page.
 
-1. Define `redis_master_role['enable']` to `true`, to disable other services
-   in the machine (you can still enable Sentinel)
+1. Edit `/etc/gitlab/gitlab.rb` and add the contents:
 
-1. Define a `redis['bind']` address pointing to a local IP that your other machines
-   can reach you.
-   - If you really need to bind to an external accessible IP, make
-   sure you add extra firewall rules to prevent unauthorized access.
-   - You can also set bind to `0.0.0.0` which listen in all interfaces.
+    ```ruby
+    # Enable the master role and disable all other services in the machine
+    # (you can still enable Sentinel).
+    redis_master_role['enable'] = true
+
+    # IP address pointing to a local IP that the other machines can reach to.
+    # You can also set bind to '0.0.0.0' which listen in all interfaces.
+    # If you really need to bind to an external accessible IP, make
+    # sure you add extra firewall rules to prevent unauthorized access.
+    redis['bind'] = '10.0.0.1'
+
+    # Define a port so Redis can listen for TCP requests which will allow other
+    # machines to connect to it.
+    redis['port'] = 6379
+
+    # Set up password authentication for Redis (use the same password in all nodes).
+    redis['password'] = 'redis-password-goes-here'
+    ```
+
+1. To prevent database migrations from running on upgrade, run:
+
+    ```
+    touch /etc/gitlab/skip-auto-migrations
+    ```
 
-1. Define a `redis['port']` so redis can listen for TCP requests which will
-   allow other machines to connect to it.
+    Only the primary GitLab application server should handle migrations.
 
-1. Set up a password authentication with `redis['password']` and
-   `redis['master_password']` (use the same password in all nodes).
+1. [Reconfigure Omnibus GitLab][reconfigure] for the changes to take effect.
 
-1. [Reconfigure Omnibus GitLab][reocnfigure] for the changes to take effect.
+### Step 2. Configuring the slave Redis instances
 
-### Configuring the Slave Redis instances
+1. SSH into the **slave** Redis server and login as root:
 
-You will need to configure the following in `/etc/gitlab/gitlab.rb`:
+    ```
+    sudo -i
+    ```
 
-1. Define `redis_slaves_role['enable']` to `true`, to disable other services
-   in the machine (you can still enable Sentinel)
-   - This will also set automatically `redis['master'] = false`.
+1. [Download/install](https://about.gitlab.com/installation) the Omnibus GitLab
+   package using **steps 1 and 2** from the GitLab downloads page.
+     - Make sure you select the correct Omnibus package, with the same version
+       and type (Community, Enterprise editions) of your current install.
+     - Do not complete any other steps on the download page.
 
-1. Define a `redis['bind']` address pointing to a local IP that your other machines
-   can reach you.
-   - If you really need to bind to an external accessible IP, make
-   sure you add extra firewall rules to prevent unauthorized access.
-   - You can also set bind to `0.0.0.0` which listen in all interfaces.
+1. Edit `/etc/gitlab/gitlab.rb` and add the contents:
+
+    ```ruby
+    # Enable the slave role and disable all other services in the machine
+    # (you can still enable Sentinel). This will also set automatically
+    # `redis['master'] = false`.
+    redis_slave_role['enable'] = true
 
-1. Define a `redis['port']` so redis can listen for TCP requests which will
-   allow other machines to connect to it.
+    # IP address pointing to a local IP that the other machines can reach to.
+    # You can also set bind to '0.0.0.0' which listen in all interfaces.
+    # If you really need to bind to an external accessible IP, make
+    # sure you add extra firewall rules to prevent unauthorized access.
+    redis['bind'] = '10.0.0.2'
 
-1. Set up a password authentication with `redis['password']` and
-   `redis['master_password']` (use the same password in all nodes).
 
-1. Define `redis['master_ip']` with the IP of the **Master** Redis.
+    # Define a port so Redis can listen for TCP requests which will allow other
+    # machines to connect to it.
+    redis['port'] = 6379
 
-1. Define `redis['master_port']` with the port of the **Master** Redis (default to `6379`).
+    # The same password for Redeis authentication you set up for the master node.
+    redis['password'] = 'redis-password-goes-here'
 
-Initial **Slave** nodes require `redis['master']` defined to `false` and
-`redis['master_ip']` pointing to the initial **Master**. If you use the
-simplified configuration by enabling `redis_slave_role['enable']`, you
-just need to fill in the `redis['master_ip']`.
+    # The IP of the master Redis node.
+    redis['master_ip'] = '10.0.0.1'
 
-This values don't have to be changed again in `/etc/gitlab/gitlab.rb` after
+    # Port of master Redis server, uncomment to change to non default. Defaults
+    # to `6379`.
+    #redis['master_port'] = 6379
+    ```
+
+1. To prevent database migrations from running on upgrade, run:
+
+    ```
+    touch /etc/gitlab/skip-auto-migrations
+    ```
+
+    Only the primary GitLab application server should handle migrations.
+
+1. [Reconfigure Omnibus GitLab][reconfigure] for the changes to take effect.
+1. Go through the steps again for all the other slave nodes.
+
+---
+
+These values don't have to be changed again in `/etc/gitlab/gitlab.rb` after
 a failover, as the nodes will be managed by the Sentinels, and even after a
 `gitlab-ctl reconfigure`, they will get their configuration restored by
 the same Sentinels.
 
-### Configuring the Redis Sentinel instances
+### Step 3. Configuring the Redis Sentinel instances
 
 >**Note:**
-- Redis Sentinel is bundled with Omnibus GitLab Enterprise Edition only. For the
-  Omnibus Community Edition and installations from source, follow the
-  [Redis HA source install](redis_source.md) guide.
+Redis Sentinel is bundled with Omnibus GitLab Enterprise Edition only. The
+following section assumes you are using Omnibus GitLab Enterprise Edition.
+For the Omnibus Community Edition and installations from source, follow the
+[Redis HA source install](redis_source.md) guide.
 
 Now that the Redis servers are all set up, let's configure the Sentinel
 servers.
@@ -369,15 +398,112 @@ correctly, please read the [Troubleshooting Replication](#troubleshooting-replic
 and fix it before proceeding with Sentinel setup.
 
 You must have at least `3` Redis Sentinel servers, and they need to
-be each in a independent machine. You can configure them in the same
+be each in an independent machine. You can configure them in the same
 machines where you've configured the other Redis servers.
 
-With GitLab Enterprise Edition, you can use the Omnibus package to setup multiple
-machines with the Sentinel daemon.
+With GitLab Enterprise Edition, you can use the Omnibus package to setup
+multiple machines with the Sentinel daemon.
+
+---
+
+1. SSH into the server that will host Redis Sentinel and login as root:
+
+    ```
+    sudo -i
+    ```
+
+1. **You can omit this step if the Sentinels will be hosted in the same node as
+   the other Redis instances.**
+
+     [Download/install](https://about.gitlab.com/downloads-ee) the
+     Omnibus GitLab Enterprise Edition package using **steps 1 and 2** from the
+     GitLab downloads page.
+       - Make sure you select the correct Omnibus package, with the same version
+         the GitLab application is running.
+       - Do not complete any other steps on the download page.
 
-See [example configuration](#configuration-for-sentinel-ee-only) below.
+1. Edit `/etc/gitlab/gitlab.rb` and add the contents (if you are installing the
+   Sentinels in the same node as the other Redis instances, some values might
+   be duplicate below):
 
-### Configuring the GitLab application
+
+    ```ruby
+    redis_sentinel_role['enable'] = true
+
+    # Must be the same in every sentinel node
+    redis['master_name'] = 'gitlab-redis'
+
+    # The same password for Redis authentication you set up for the master node.
+    redis['password'] = 'redis-password-goes-here'
+
+    # The IP of the master Redis node.
+    redis['master_ip'] = '10.0.0.1'
+
+    # Define a port so Redis can listen for TCP requests which will allow other
+    # machines to connect to it.
+    redis['port'] = 6379
+
+    # Port of master Redis server, uncomment to change to non default. Defaults
+    # to `6379`.
+    #redis['master_port'] = 6379
+
+    ## Configure Sentinel
+    sentinel['bind'] = '10.0.0.1'
+
+    # Port that Sentinel listens on, uncomment to change to non default. Defaults
+    # to `26379`.
+    # sentinel['port'] = 26379
+
+    ## Quorum must reflect the amount of voting sentinels it take to start a failover.
+    ## Value must NOT be greater then the amount of sentinels.
+    ##
+    ## The quorum can be used to tune Sentinel in two ways:
+    ## 1. If a the quorum is set to a value smaller than the majority of Sentinels
+    ##    we deploy, we are basically making Sentinel more sensible to master failures,
+    ##    triggering a failover as soon as even just a minority of Sentinels is no longer
+    ##    able to talk with the master.
+    ## 1. If a quorum is set to a value greater than the majority of Sentinels, we are
+    ##    making Sentinel able to failover only when there are a very large number (larger
+    ##    than majority) of well connected Sentinels which agree about the master being down.s
+    sentinel['quorum'] = 2
+
+    ## Consider unresponsive server down after x amount of ms.
+    # sentinel['down_after_milliseconds'] = 10000
+
+    ## Specifies the failover timeout in milliseconds. It is used in many ways:
+    ##
+    ## - The time needed to re-start a failover after a previous failover was
+    ##   already tried against the same master by a given Sentinel, is two
+    ##   times the failover timeout.
+    ##
+    ## - The time needed for a slave replicating to a wrong master according
+    ##   to a Sentinel current configuration, to be forced to replicate
+    ##   with the right master, is exactly the failover timeout (counting since
+    ##   the moment a Sentinel detected the misconfiguration).
+    ##
+    ## - The time needed to cancel a failover that is already in progress but
+    ##   did not produced any configuration change (SLAVEOF NO ONE yet not
+    ##   acknowledged by the promoted slave).
+    ##
+    ## - The maximum time a failover in progress waits for all the slaves to be
+    ##   reconfigured as slaves of the new master. However even after this time
+    ##   the slaves will be reconfigured by the Sentinels anyway, but not with
+    ##   the exact parallel-syncs progression as specified.
+    # sentinel['failover_timeout'] = 60000
+    ```
+
+1. To prevent database migrations from running on upgrade, run:
+
+    ```
+    touch /etc/gitlab/skip-auto-migrations
+    ```
+
+    Only the primary GitLab application server should handle migrations.
+
+1. [Reconfigure Omnibus GitLab][reconfigure] for the changes to take effect.
+1. Go through the steps again for all the other Sentinel nodes.
+
+### Step 4. Configuring the GitLab application
 
 The final part is to inform the main GitLab application server of the Redis
 Sentinels servers and authentication credentials.
@@ -395,14 +521,23 @@ which ideally should not have Redis or Sentinels on it for a HA setup.
 
 1. Edit `/etc/gitlab/gitlab.rb` and add/change the following lines:
 
-  - `redis['master_name']` - this is the `master-group-name` from sentinel (default: `gitlab-redis`)
-  - `redis['master_password']` - the same password you've defined before for Redis and Sentinels
-  - `gitlab_rails['redis_sentinels']` - a list of sentinels with `host` and `port`
+    ```
+    # Must be the same in every sentinel node
+    redis['master_name'] = 'gitlab-redis'
+
+    # The same password for Redis authentication you set up for the master node.
+    redis['password'] = 'redis-password-goes-here'
+
+    # A list of sentinels with `host` and `port`
+    gitlab_rails['redis_sentinels'] = [
+      {'host' => '10.0.0.1', 'port' => 26379},
+      {'host' => '10.0.0.2', 'port' => 26379},
+      {'host' => '10.0.0.3', 'port' => 26379}
+    ]
+    ```
 
 1. [Reconfigure Omnibus GitLab][reconfigure] for the changes to take effect.
 
-See [example configuration](#configuration-for-gitlab) below.
-
 ## Switching from an existing single-machine installation to Redis HA
 
 If you already have a single-machine GitLab install running, you will need to
@@ -436,14 +571,15 @@ unauthorized access from other machines and block traffic from the
 outside (Internet).
 
 We will use the same `3` nodes with **Redis** + **Sentinel** topology
-discussed in [Redis Setup](#redis-setup) and [Sentinel Setup](#sentinel-setup)
-documentation.
+discussed in [Redis setup overview](#redis-setup-overview) and
+[Sentinel setup overview](#sentinel-setup-overview) documentation.
 
 Here is a list and description of each **machine** and the assigned **IP**:
 
 * `10.0.0.1`: Redis Master + Sentinel 1
 * `10.0.0.2`: Redis Slave 1 + Sentinel 2
-* `10.0.0.2`: Redis Slave 2 + Sentinel 3
+* `10.0.0.3`: Redis Slave 2 + Sentinel 3
+* `10.0.0.4`: GitLab application
 
 Please note that after the initial configuration, if a failover is initiated
 by the Sentinel nodes, the Redis nodes will be reconfigured and the **Master**
@@ -454,7 +590,7 @@ The same thing will happen with `sentinel.conf` that will be overridden after th
 initial execution, after any new sentinel node starts watching the **Master**,
 or a failover promotes a different **Master** node.
 
-### Configuration for Redis master
+### Example configuration for Redis master
 
 **Example configation for Redis Master:**
 
@@ -466,14 +602,13 @@ redis_master_role['enable'] = true
 redis['bind'] = '10.0.0.1'
 redis['port'] = 6379
 redis['password'] = 'redis-password-goes-here'
-redis['master_password'] = 'redis-password-goes-here'
 ```
 
 [Reconfigure Omnibus GitLab][reconfigure] for the changes to take effect.
 
-### Configuration for Redis slaves
+### Example configuration for Redis slaves
 
-**Example configation for Slave 1:**
+**Example configuration for Slave 1:**
 
 In `/etc/gitlab/gitlab.rb`:
 
@@ -489,9 +624,9 @@ redis['master_ip'] = '10.0.0.1' # IP of master Redis server
 #redis['master_port'] = 6379 # Port of master Redis server, uncomment to change to non default
 ```
 
-Reconfigure Omnibus GitLab for the changes to take effect: `sudo gitlab-ctl reconfigure`
+[Reconfigure Omnibus GitLab][reconfigure] for the changes to take effect.
 
-**Example configation for Slave 2:**
+**Example configuration for Slave 2:**
 
 In `/etc/gitlab/gitlab.rb`:
 
@@ -509,7 +644,7 @@ redis['master_ip'] = '10.0.0.1' # IP of master Redis server
 
 [Reconfigure Omnibus GitLab][reconfigure] for the changes to take effect.
 
-### Configuration for Sentinels
+### Example configuration for Sentinels
 
 >**Note:**
 Redis Sentinel is bundled with Omnibus GitLab Enterprise Edition only. For the
@@ -519,7 +654,7 @@ Omnibus Community Edition and installations from source, follow the
 Please note that some of the variables are already configured previously
 as they are required for Redis replication.
 
-**Example configation for Sentinel 1:**
+**Example configuration for Sentinel 1:**
 
 In `/etc/gitlab/gitlab.rb`:
 
@@ -534,46 +669,17 @@ redis['master_ip'] = '10.0.0.1' # ip of the initial master redis instance
 ## Configure Sentinel
 sentinel['bind'] = '10.0.0.1'
 # sentinel['port'] = 26379 # uncomment to change default port
-
-## Quorum must reflect the amount of voting sentinels it take to start a failover.
-## Value must NOT be greater then the ammount of sentinels.
-##
-## The quorum can be used to tune Sentinel in two ways:
-## 1. If a the quorum is set to a value smaller than the majority of Sentinels
-##    we deploy, we are basically making Sentinel more sensible to master failures,
-##    triggering a failover as soon as even just a minority of Sentinels is no longer
-##    able to talk with the master.
-## 1. If a quorum is set to a value greater than the majority of Sentinels, we are
-##    making Sentinel able to failover only when there are a very large number (larger
-##    than majority) of well connected Sentinels which agree about the master being down.s
 sentinel['quorum'] = 2
 
 ## Consider unresponsive server down after x amount of ms.
 # sentinel['down_after_milliseconds'] = 10000
 
-## Specifies the failover timeout in milliseconds. It is used in many ways:
-##
-## - The time needed to re-start a failover after a previous failover was
-##   already tried against the same master by a given Sentinel, is two
-##   times the failover timeout.
-##
-## - The time needed for a slave replicating to a wrong master according
-##   to a Sentinel current configuration, to be forced to replicate
-##   with the right master, is exactly the failover timeout (counting since
-##   the moment a Sentinel detected the misconfiguration).
-##
-## - The time needed to cancel a failover that is already in progress but
-##   did not produced any configuration change (SLAVEOF NO ONE yet not
-##   acknowledged by the promoted slave).
-##
-## - The maximum time a failover in progress waits for all the slaves to be
-##   reconfigured as slaves of the new master. However even after this time
-##   the slaves will be reconfigured by the Sentinels anyway, but not with
-##   the exact parallel-syncs progression as specified.
 # sentinel['failover_timeout'] = 60000
 ```
 
-**Example configation for Sentinel 2:**
+[Reconfigure Omnibus GitLab][reconfigure] for the changes to take effect.
+
+**Example configuration for Sentinel 2:**
 
 In `/etc/gitlab/gitlab.rb`:
 
@@ -589,45 +695,17 @@ redis['master_ip'] = '10.0.0.1' # ip of the initial master redis instance
 sentinel['bind'] = '10.0.0.2'
 # sentinel['port'] = 26379 # uncomment to change default port
 
-## Quorum must reflect the amount of voting sentinels it take to start a failover.
-## Value must NOT be greater then the ammount of sentinels.
-##
-## The quorum can be used to tune Sentinel in two ways:
-## 1. If a the quorum is set to a value smaller than the majority of Sentinels
-##    we deploy, we are basically making Sentinel more sensible to master failures,
-##    triggering a failover as soon as even just a minority of Sentinels is no longer
-##    able to talk with the master.
-## 1. If a quorum is set to a value greater than the majority of Sentinels, we are
-##    making Sentinel able to failover only when there are a very large number (larger
-##    than majority) of well connected Sentinels which agree about the master being down.s
 sentinel['quorum'] = 2
 
 ## Consider unresponsive server down after x amount of ms.
 # sentinel['down_after_milliseconds'] = 10000
 
-## Specifies the failover timeout in milliseconds. It is used in many ways:
-##
-## - The time needed to re-start a failover after a previous failover was
-##   already tried against the same master by a given Sentinel, is two
-##   times the failover timeout.
-##
-## - The time needed for a slave replicating to a wrong master according
-##   to a Sentinel current configuration, to be forced to replicate
-##   with the right master, is exactly the failover timeout (counting since
-##   the moment a Sentinel detected the misconfiguration).
-##
-## - The time needed to cancel a failover that is already in progress but
-##   did not produced any configuration change (SLAVEOF NO ONE yet not
-##   acknowledged by the promoted slave).
-##
-## - The maximum time a failover in progress waits for all the slaves to be
-##   reconfigured as slaves of the new master. However even after this time
-##   the slaves will be reconfigured by the Sentinels anyway, but not with
-##   the exact parallel-syncs progression as specified.
 # sentinel['failover_timeout'] = 60000
 ```
 
-**Example configation for Sentinel 3:**
+[Reconfigure Omnibus GitLab][reconfigure] for the changes to take effect.
+
+**Example configuration for Sentinel 3:**
 
 In `/etc/gitlab/gitlab.rb`:
 
@@ -643,44 +721,37 @@ redis['master_ip'] = '10.0.0.1' # ip of the initial master redis instance
 sentinel['bind'] = '10.0.0.3'
 # sentinel['port'] = 26379 # uncomment to change default port
 
-## Quorum must reflect the amount of voting sentinels it take to start a failover.
-## Value must NOT be greater then the ammount of sentinels.
-##
-## The quorum can be used to tune Sentinel in two ways:
-## 1. If a the quorum is set to a value smaller than the majority of Sentinels
-##    we deploy, we are basically making Sentinel more sensible to master failures,
-##    triggering a failover as soon as even just a minority of Sentinels is no longer
-##    able to talk with the master.
-## 1. If a quorum is set to a value greater than the majority of Sentinels, we are
-##    making Sentinel able to failover only when there are a very large number (larger
-##    than majority) of well connected Sentinels which agree about the master being down.s
 sentinel['quorum'] = 2
 
 ## Consider unresponsive server down after x amount of ms.
 # sentinel['down_after_milliseconds'] = 10000
 
-## Specifies the failover timeout in milliseconds. It is used in many ways:
-##
-## - The time needed to re-start a failover after a previous failover was
-##   already tried against the same master by a given Sentinel, is two
-##   times the failover timeout.
-##
-## - The time needed for a slave replicating to a wrong master according
-##   to a Sentinel current configuration, to be forced to replicate
-##   with the right master, is exactly the failover timeout (counting since
-##   the moment a Sentinel detected the misconfiguration).
-##
-## - The time needed to cancel a failover that is already in progress but
-##   did not produced any configuration change (SLAVEOF NO ONE yet not
-##   acknowledged by the promoted slave).
-##
-## - The maximum time a failover in progress waits for all the slaves to be
-##   reconfigured as slaves of the new master. However even after this time
-##   the slaves will be reconfigured by the Sentinels anyway, but not with
-##   the exact parallel-syncs progression as specified.
 # sentinel['failover_timeout'] = 60000
 ```
 
+[Reconfigure Omnibus GitLab][reconfigure] for the changes to take effect.
+
+### Example configuration for the GitLab application
+
+In `/etc/gitlab/gitlab.rb`:
+
+```
+# Must be the same in every sentinel node
+redis['master_name'] = 'gitlab-redis'
+
+# The same password for Redis authentication you set up for the master node.
+redis['password'] = 'redis-password-goes-here'
+
+# A list of sentinels with `host` and `port`
+gitlab_rails['redis_sentinels'] = [
+  {'host' => '10.0.0.1', 'port' => 26379},
+  {'host' => '10.0.0.2', 'port' => 26379},
+  {'host' => '10.0.0.3', 'port' => 26379}
+]
+```
+
+[Reconfigure Omnibus GitLab][reconfigure] for the changes to take effect.
+
 ## Advanced configuration
 
 Omnibus GitLab configures some things behind the curtains to make the sysadmins'
@@ -688,8 +759,8 @@ lives easier. If you want to know what happens underneath keep reading.
 
 ### Control running services
 
-In the previous example above we've used `redis_sentinel_role` and
-`redis_master_role` which simplify the amount of configuration changes.
+In the previous example, we've used `redis_sentinel_role` and
+`redis_master_role` which simplifies the amount of configuration changes.
 
 If you want more control, here is what each one sets for you automatically
 when enabled:
@@ -698,10 +769,10 @@ when enabled:
 ## Redis Sentinel Role
 redis_sentinel_role['enable'] = true
 
-# When Sentinel Role is enabled, the following services are enabled/disabled:
+# When Sentinel Role is enabled, the following services are also enabled
 sentinel['enable'] = true
 
-# This others are disabled:
+# The following services are disabled
 redis['enable'] = false
 bootstrap['enable'] = false
 nginx['enable'] = false
@@ -709,17 +780,17 @@ postgresql['enable'] = false
 gitlab_rails['enable'] = false
 mailroom['enable'] = false
 
-## Redis master/slave Role:
+-------
+
+## Redis master/slave Role
 redis_master_role['enable'] = true # enable only one of them
 redis_slave_role['enable'] = true # enable only one of them
 
-# When Redis Master or Slave role are enabled, the following services are enabled/disabled:
-# (Note that if redis and sentinel roles are combined both services will be enabled)
+# When Redis Master or Slave role are enabled, the following services are
+# enabled/disabled. Note that if Redis and Sentinel roles are combined, both
+# services will be enabled.
 
-# When Sentinel Role is enabled, the following services are enabled/disabled:
-redis['enable'] = true
-
-# This others are disabled:
+# The following services are disabled
 sentinel['enable'] = false
 bootstrap['enable'] = false
 nginx['enable'] = false
@@ -727,7 +798,7 @@ postgresql['enable'] = false
 gitlab_rails['enable'] = false
 mailroom['enable'] = false
 
-# Redis Slave role also change this setting from default 'true' to 'false':
+# For Redis Slave role, also change this setting from default 'true' to 'false':
 redis['master'] = false
 ```
 
@@ -856,6 +927,16 @@ To make sure your configuration is correct:
 
 Changes to Redis HA over time.
 
+**8.14**
+
+- Redis Sentinel support is production-ready and bundled in the Omnibus GitLab
+  Enterprise Edition package
+- Documentation restructure for better readability
+
+**8.11**
+
+- Experimental Redis Sentinel support was added
+
 ### Experimental Redis Sentinel support
 
 >
@@ -880,7 +961,7 @@ Read more on high-availability configuration:
 [gh-534]: https://github.com/redis/redis-rb/issues/534
 [redis]: http://redis.io/
 [sentinel]: http://redis.io/topics/sentinel
-[omnifile]: https://gitlab.com/gitlab-org/omnibus-gitlab/blob/82b7345b150f072c8673c79738ce893f92d0d652/files/gitlab-cookbooks/gitlab/libraries/gitlab_rails.rb#L134-159
+[omnifile]: https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-cookbooks/gitlab/libraries/gitlab_rails.rb
 [source]: ../../install/installation.md
 [ce]: https://about.gitlab.com/downloads
 [ee]: https://about.gitlab.com/downloads-ee
-- 
cgit v1.2.1


From a75c5f195124c12d3776d8c553bc71721cee121d Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axilleas@axilleas.me>
Date: Wed, 16 Nov 2016 10:20:59 +0100
Subject: Add clear instructions for the different Redis HA setups

---
 doc/administration/high_availability/redis.md | 75 ++++++++++++++-------------
 1 file changed, 40 insertions(+), 35 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md
index 6de92ae3741..7ea49a2c22a 100644
--- a/doc/administration/high_availability/redis.md
+++ b/doc/administration/high_availability/redis.md
@@ -20,8 +20,9 @@ Omnibus GitLab packages.
   from source, follow the [Redis HA source installation](redis_source.md) guide.
 - Redis Sentinel daemon is bundled with Omnibus GitLab Enterprise Edition only.
   For configuring Sentinel with the Omnibus GitLab Community Edition and
-  installations from source, follow the
-  [Redis HA source installation](redis_source.md) guide.
+  installations from source, read the
+  [Available configuration setups](#available-configuration-setups) section
+  below.
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
@@ -40,7 +41,7 @@ Omnibus GitLab packages.
   - [Step 3. Configuring the Redis Sentinel instances](#step-3-configuring-the-redis-sentinel-instances)
   - [Step 4. Configuring the GitLab application](#step-4-configuring-the-gitlab-application)
 - [Switching from an existing single-machine installation to Redis HA](#switching-from-an-existing-single-machine-installation-to-redis-ha)
-- [Example of a minimal configuration with 1 master, 2 slaves and 3 sentinels](#example-of-a-minimal-configuration-with-1-master-2-slaves-and-3-sentinels)
+- [Example of a minimal configuration with 1 master, 2 slaves and 3 Sentinels](#example-of-a-minimal-configuration-with-1-master-2-slaves-and-3-sentinels)
   - [Configuration for Redis master](#configuration-for-redis-master)
   - [Configuration for Redis slaves](#configuration-for-redis-slaves)
   - [Configuration for Sentinels](#configuration-for-sentinels)
@@ -79,17 +80,17 @@ components below.
 
 ### High Availability with Sentinel
 
->
+>**Notes:**
 - Starting with GitLab `8.11`, you can configure a list of Redis Sentinel
   servers that will monitor a group of Redis servers to provide failover support.
 - Starting with GitLab `8.14`, the Omnibus GitLab Enterprise Edition package
-  comes with Redis Sentinel daemon support.
+  comes with Redis Sentinel daemon built-in.
 
 High Availability with Redis requires a few things:
 
 - Multiple Redis instances
-  - Run Redis in a **Master** x **Slave** topology
-  - Multiple Sentinel instances
+- Run Redis in a **Master** x **Slave** topology
+- Multiple Sentinel instances
 - Application support and visibility to all Sentinel and Redis instances
 
 Redis Sentinel can handle the most important tasks in an HA environment and that's
@@ -132,27 +133,6 @@ the Omnibus GitLab package in `5` **independent** machines, both with
 - Redis Slave + Sentinel
 - Redis Slave + Sentinel
 
-### Available configuration setups
-
-Based on your infrastructure setup and how you have installed GitLab, there are
-multiple ways to configure Redis HA. Omnibus GitLab packages have Redis and/or
-Redis Sentinel bundled with them so you only need to focus on configuration.
-Pick the one that suits your needs.
-
-- [Installations from source][source]: You need to install Redis and Sentinel
-  yourself. Use the [Redis HA installation from source](redis_source.md) guide.
-- [Omnibus package Community Edition (CE) package][ce]: Redis is bundled, so you
-  can use the package with only the Redis service enabled (works for both master
-  and slave setups). To install and configure Sentinel, you can use the
-  [Redis HA installation from source](redis_source.md) guide.
-- [Omnibus package Enterprise Edition (EE) package][ee]: Both Redis and Sentinel
-  are bundled, so you can use the EE package to setup the whole Redis HA
-  infrastructure (master, slave and Sentinel).
-
-Note that even if you have installed GitLab using the Omnibus GitLab packages
-(both CE and EE), you can still use an
-[external Redis server](#using-a-non-omnibus-external-redis-server).
-
 ### Redis setup overview
 
 You must have at least `3` Redis servers: `1` Master, `2` Slaves, and they
@@ -168,7 +148,7 @@ simultaneously down.
 Please note that there are different requirements for Sentinel nodes.
 If you host them in the same Redis machines, you may need to take
 that restrictions into consideration when calculating the amount of
-nodes to be provisioned. See [Sentinel setup](#sentinel-setup)
+nodes to be provisioned. See [Sentinel setup overview](#sentinel-setup-overview)
 documentation for more information.
 
 All Redis nodes should be configured the same way and with similar server specs, as
@@ -245,6 +225,31 @@ the official documentation:
   the slaves will be reconfigured by the Sentinels anyway, but not with
   the exact parallel-syncs progression as specified.
 
+### Available configuration setups
+
+Based on your infrastructure setup and how you have installed GitLab, there are
+multiple ways to configure Redis HA. Omnibus GitLab packages have Redis and/or
+Redis Sentinel bundled with them so you only need to focus on configuration.
+Pick the one that suits your needs.
+
+- [Installations from source][source]: You need to install Redis and Sentinel
+  yourself. Use the [Redis HA installation from source](redis_source.md)
+  documentation.
+- [Omnibus GitLab **Community Edition** (CE) package][ce]: Redis is bundled, so you
+  can use the package with only the Redis service enabled as described in steps
+  1 and 2 of this document (works for both master and slave setups). To install
+  and configure Sentinel, jump directly to the Sentinel section in the
+  [Redis HA installation from source](redis_source.md#step-3-configuring-the-redis-sentinel-instances) documentation.
+- [Omnibus GitLab **Enterprise Edition** (EE) package][ee]: Both Redis and Sentinel
+  are bundled in the package, so you can use the EE package to setup the whole
+  Redis HA infrastructure (master, slave and Sentinel) which is described in
+  this document.
+- If you have installed GitLab using the Omnibus GitLab packages (CE or EE),
+  but you want to use your own external Redis server, follow steps 1-3 in the
+  [Redis HA installation from source](redis_source.md) documentation, then go
+  straight to step 4 in this guide to
+  [set up the GitLab application](#step-4-configuring-the-gitlab-application).
+
 ## Configuring Redis HA
 
 This is the section where we install and setup the new Redis instances.
@@ -284,7 +289,7 @@ The prerequisites for a HA Redis setup are the following:
     ```
 
 1. [Download/install](https://about.gitlab.com/installation) the Omnibus GitLab
-   package using **steps 1 and 2** from the GitLab downloads page.
+   package you want using **steps 1 and 2** from the GitLab downloads page.
      - Make sure you select the correct Omnibus package, with the same version
        and type (Community, Enterprise editions) of your current install.
      - Do not complete any other steps on the download page.
@@ -313,7 +318,7 @@ The prerequisites for a HA Redis setup are the following:
 1. To prevent database migrations from running on upgrade, run:
 
     ```
-    touch /etc/gitlab/skip-auto-migrations
+    sudo touch /etc/gitlab/skip-auto-migrations
     ```
 
     Only the primary GitLab application server should handle migrations.
@@ -329,7 +334,7 @@ The prerequisites for a HA Redis setup are the following:
     ```
 
 1. [Download/install](https://about.gitlab.com/installation) the Omnibus GitLab
-   package using **steps 1 and 2** from the GitLab downloads page.
+   package you want using **steps 1 and 2** from the GitLab downloads page.
      - Make sure you select the correct Omnibus package, with the same version
        and type (Community, Enterprise editions) of your current install.
      - Do not complete any other steps on the download page.
@@ -367,7 +372,7 @@ The prerequisites for a HA Redis setup are the following:
 1. To prevent database migrations from running on upgrade, run:
 
     ```
-    touch /etc/gitlab/skip-auto-migrations
+    sudo touch /etc/gitlab/skip-auto-migrations
     ```
 
     Only the primary GitLab application server should handle migrations.
@@ -495,7 +500,7 @@ multiple machines with the Sentinel daemon.
 1. To prevent database migrations from running on upgrade, run:
 
     ```
-    touch /etc/gitlab/skip-auto-migrations
+    sudo touch /etc/gitlab/skip-auto-migrations
     ```
 
     Only the primary GitLab application server should handle migrations.
@@ -560,7 +565,7 @@ redis['enable'] = false
 
 If you fail to replicate first, you may loose data (unprocessed background jobs).
 
-## Example of a minimal configuration with 1 master, 2 slaves and 3 sentinels
+## Example of a minimal configuration with 1 master, 2 slaves and 3 Sentinels
 
 In this example we consider that all servers have an internal network
 interface with IPs in the `10.0.0.x` range, and that they can connect
-- 
cgit v1.2.1


From 178d5ae9719b0edf6a4873502422e3302d264528 Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axilleas@axilleas.me>
Date: Wed, 16 Nov 2016 10:21:44 +0100
Subject: Rearrange Redis HA source installations sections

---
 .../high_availability/redis_source.md              | 57 +++++++++++++---------
 1 file changed, 33 insertions(+), 24 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/high_availability/redis_source.md b/doc/administration/high_availability/redis_source.md
index 20630b070c0..a420d44f451 100644
--- a/doc/administration/high_availability/redis_source.md
+++ b/doc/administration/high_availability/redis_source.md
@@ -1,26 +1,34 @@
-# Configuring Redis for GitLab HA (Source Install)
+# Configuring non-Omnibus Redis for GitLab HA
 
-We highly recommend that you use Omnibus GitLab packages, as we can optimize
-required packages specifically for GitLab, and we will take care of upgrading
+This is the documentation for configuring a Highly Available Redis setup when
+you have installed Redis all by yourself and not using the bundled one that
+comes with the Omnibus packages.
+
+We cannot stress enough the importance of reading the
+[Overview section](redis.md#overview) of the Omnibus Redis HA as it provides
+some invaluable information to the configuration of Redis. Please proceed to
+read it before going forward with this guide.
+
+We also highly recommend that you use the Omnibus GitLab packages, as we
+optimize them specifically for GitLab, and we will take care of upgrading Redis
 to the latest supported version.
 
-If you are building packages for a specific distro, or trying to build some
-internal automation, you can check this documentation to learn about the
-minimal setup, required changes, etc.
+If you're not sure whether this guide is for you, please refer to
+[Available configuration setups](redis.md#available-configuration-setups) in
+the Omnibus Redis HA documentation.
 
-If you want to see the documentation for Omnibus GitLab Install, please
-[read it here](redis.md).
+---
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 **Table of Contents**
 
-- [Configure your own Redis server](#configure-your-own-redis-server)
-  - [Configuring Master Redis instance](#configuring-master-redis-instance)
-  - [Configuring Slave Redis instances](#configuring-slave-redis-instances)
-  - [Configuring Redis Sentinel instances](#configuring-redis-sentinel-instances)
-- [GitLab setup](#gitlab-setup)
-- [Example configurations](#example-configurations)
+- [Configuring your own Redis server](#configuring-your-own-redis-server)
+  - [Step 1. Configuring the master Redis instance](#step-1-configuring-the-master-redis-instance)
+  - [Step 2. Configuring the slave Redis instances](#step-2-configuring-the-slave-redis-instances)
+  - [Step 3. Configuring the Redis Sentinel instances](#step-3-configuring-the-redis-sentinel-instances)
+  - [Step 4. Configuring the GitLab application](#step-4-configuring-the-gitlab-application)
+- [Example of minimal configuration with 1 master, 2 slaves and 3 Sentinels](#example-of-minimal-configuration-with-1-master-2-slaves-and-3-sentinels)
   - [Configuring Redis Master](#configuring-redis-master)
   - [Configuring Redis Slaves](#configuring-redis-slaves)
   - [Configuring Redis Sentinel](#configuring-redis-sentinel)
@@ -28,7 +36,7 @@ If you want to see the documentation for Omnibus GitLab Install, please
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
-## Configure your own Redis server
+## Configuring your own Redis server
 
 Redis server must be configured to use TCP connection instead of socket,
 and since Redis `3.2`, you must define a password to receive external
@@ -41,8 +49,7 @@ To configure Redis to use TCP connection you need to define both
 `bind` and `port`. You can bind to all interfaces (`0.0.0.0`) or specify the
 IP of the desired interface (for ex. one from an internal network).
 
-
-### Configuring Master Redis instance
+### Step 1. Configuring the master Redis instance
 
 You need to make the following changes in `redis.conf`:
 
@@ -61,7 +68,7 @@ You need to make the following changes in `redis.conf`:
 
 See [example configuration](#configuring-redis-master) below.
 
-### Configuring Slave Redis instances
+### Step 2. Configuring the slave Redis instances
 
 1. Follow same instructions for Redis Master
 
@@ -71,7 +78,7 @@ See [example configuration](#configuring-redis-master) below.
 
 See [example configuration](#configuring-redis-slaves) below.
 
-### Configuring Redis Sentinel instances
+### Step 3. Configuring the Redis Sentinel instances
 
 Sentinel is a special type of Redis server. It inherits most of the basic
 configuration options you can define in `redis.conf`, with specific ones
@@ -122,7 +129,7 @@ And the sentinel specific ones:
 
 See [example configuration](#configuring-redis-sentinel) below.
 
-## GitLab setup
+### Step 4. Configuring the GitLab application
 
 You can enable or disable Sentinel support at any time in new or existing
 installations. From the GitLab application perspective, all it requires is
@@ -141,7 +148,7 @@ which ideally should not have Redis or Sentinels in the same machine for a HA se
 
 1. Restart GitLab for the changes to take effect.
 
-## Example configurations
+## Example of minimal configuration with 1 master, 2 slaves and 3 Sentinels
 
 In this example we consider that all servers have an internal network
 interface with IPs in the `10.0.0.x` range, and that they can connect
@@ -247,12 +254,13 @@ sentinel failover_timeout 30000
 
 ## Troubleshooting
 
-We have a more detailed [Troubleshooting](redis.md#troubleshooting) explained in the documentation for Omnibus
-Install. Here we will list only the things that are specific to a **Source** install.
+We have a more detailed [Troubleshooting](redis.md#troubleshooting) explained
+in the documentation for Omnibus GitLab installations. Here we will list only
+the things that are specific to a source installation.
 
 If you get an error in GitLab like: `Redis::CannotConnectError: No sentinels available.`,
 there may be something wrong with your configuration files or it can be related
-to [this issue][gh-531].
+to [this upstream issue][gh-531].
 
 It's a bit non-intuitive the way you have to config `resque.yml` and
 `sentinel.conf`, otherwise `redis-rb` will not work properly.
@@ -287,3 +295,4 @@ production:
 When in doubt, please read [Redis Sentinel documentation](http://redis.io/topics/sentinel)
 
 [gh-531]: https://github.com/redis/redis-rb/issues/531
+[downloads]: https://about.gitlab.com/downloads
-- 
cgit v1.2.1


From dc54239683fbe77b13216deb6a0728563a0a89d0 Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axilleas@axilleas.me>
Date: Wed, 16 Nov 2016 11:42:12 +0100
Subject: Merge examples of Redis master/slave + Sentinels

---
 doc/administration/high_availability/redis.md | 144 +++++++-------------------
 1 file changed, 37 insertions(+), 107 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md
index 7ea49a2c22a..02ca4999cd4 100644
--- a/doc/administration/high_availability/redis.md
+++ b/doc/administration/high_availability/redis.md
@@ -29,22 +29,23 @@ Omnibus GitLab packages.
 **Table of Contents**
 
 - [Overview](#overview)
-  - [Prerequisites](#prerequisites)
   - [High Availability with Sentinel](#high-availability-with-sentinel)
   - [Recommended setup](#recommended-setup)
-  - [Available configuration setups](#available-configuration-setups)
   - [Redis setup overview](#redis-setup-overview)
   - [Sentinel setup overview](#sentinel-setup-overview)
+  - [Available configuration setups](#available-configuration-setups)
 - [Configuring Redis HA](#configuring-redis-ha)
-  - [Step 1. Configuring the Master Redis instance](#step-1-configuring-the-master-redis-instance)
-  - [Step 2. Configuring the Slave Redis instances](#step-2-configuring-the-slave-redis-instances)
+  - [Prerequisites](#prerequisites)
+  - [Step 1. Configuring the master Redis instance](#step-1-configuring-the-master-redis-instance)
+  - [Step 2. Configuring the slave Redis instances](#step-2-configuring-the-slave-redis-instances)
   - [Step 3. Configuring the Redis Sentinel instances](#step-3-configuring-the-redis-sentinel-instances)
   - [Step 4. Configuring the GitLab application](#step-4-configuring-the-gitlab-application)
 - [Switching from an existing single-machine installation to Redis HA](#switching-from-an-existing-single-machine-installation-to-redis-ha)
 - [Example of a minimal configuration with 1 master, 2 slaves and 3 Sentinels](#example-of-a-minimal-configuration-with-1-master-2-slaves-and-3-sentinels)
-  - [Configuration for Redis master](#configuration-for-redis-master)
-  - [Configuration for Redis slaves](#configuration-for-redis-slaves)
-  - [Configuration for Sentinels](#configuration-for-sentinels)
+  - [Example configuration for Redis master and Sentinel 1](#example-configuration-for-redis-master-and-sentinel-1)
+  - [Example configuration for Redis slave 1 and Sentinel 2](#example-configuration-for-redis-slave-1-and-sentinel-2)
+  - [Example configuration for Redis slave 2 and Sentinel 3](#example-configuration-for-redis-slave-2-and-sentinel-3)
+  - [Example configuration for the GitLab application](#example-configuration-for-the-gitlab-application)
 - [Advanced configuration](#advanced-configuration)
   - [Control running services](#control-running-services)
 - [Troubleshooting](#troubleshooting)
@@ -277,7 +278,7 @@ The prerequisites for a HA Redis setup are the following:
    change the default ones).
 1. The server that hosts the GitLab application must be able to access the
    Redis nodes.
-1. Protect the nodes from access from external networks (Internet), using
+1. Protect the nodes from access from external networks ([Internet][it]), using
    firewall.
 
 ### Step 1. Configuring the master Redis instance
@@ -527,13 +528,13 @@ which ideally should not have Redis or Sentinels on it for a HA setup.
 1. Edit `/etc/gitlab/gitlab.rb` and add/change the following lines:
 
     ```
-    # Must be the same in every sentinel node
+    ## Must be the same in every sentinel node
     redis['master_name'] = 'gitlab-redis'
 
-    # The same password for Redis authentication you set up for the master node.
+    ## The same password for Redis authentication you set up for the master node.
     redis['password'] = 'redis-password-goes-here'
 
-    # A list of sentinels with `host` and `port`
+    ## A list of sentinels with `host` and `port`
     gitlab_rails['redis_sentinels'] = [
       {'host' => '10.0.0.1', 'port' => 26379},
       {'host' => '10.0.0.2', 'port' => 26379},
@@ -567,6 +568,11 @@ If you fail to replicate first, you may loose data (unprocessed background jobs)
 
 ## Example of a minimal configuration with 1 master, 2 slaves and 3 Sentinels
 
+>**Note:**
+Redis Sentinel is bundled with Omnibus GitLab Enterprise Edition only. For
+different setups, read the
+[available configuration setups](#available-configuration-setups) section.
+
 In this example we consider that all servers have an internal network
 interface with IPs in the `10.0.0.x` range, and that they can connect
 to each other using these IPs.
@@ -595,142 +601,70 @@ The same thing will happen with `sentinel.conf` that will be overridden after th
 initial execution, after any new sentinel node starts watching the **Master**,
 or a failover promotes a different **Master** node.
 
-### Example configuration for Redis master
-
-**Example configation for Redis Master:**
+### Example configuration for Redis master and Sentinel 1
 
 In `/etc/gitlab/gitlab.rb`:
 
 ```ruby
 redis_master_role['enable'] = true
-
+redis_sentinel_role['enable'] = true
 redis['bind'] = '10.0.0.1'
 redis['port'] = 6379
 redis['password'] = 'redis-password-goes-here'
-```
-
-[Reconfigure Omnibus GitLab][reconfigure] for the changes to take effect.
-
-### Example configuration for Redis slaves
-
-**Example configuration for Slave 1:**
-
-In `/etc/gitlab/gitlab.rb`:
-
-```ruby
-redis_slave_role['enable'] = true
-
-redis['bind'] = '10.0.0.2'
-redis['port'] = 6379
-redis['password'] = 'redis-password-goes-here'
-redis['master_password'] = 'redis-password-goes-here'
-
-redis['master_ip'] = '10.0.0.1' # IP of master Redis server
-#redis['master_port'] = 6379 # Port of master Redis server, uncomment to change to non default
-```
-
-[Reconfigure Omnibus GitLab][reconfigure] for the changes to take effect.
-
-**Example configuration for Slave 2:**
-
-In `/etc/gitlab/gitlab.rb`:
-
-```ruby
-redis_slave_role['enable'] = true
-
-redis['bind'] = '10.0.0.3'
-redis['port'] = 6379
-redis['password'] = 'redis-password-goes-here'
-redis['master_password'] = 'redis-password-goes-here'
-
-redis['master_ip'] = '10.0.0.1' # IP of master Redis server
-#redis['master_port'] = 6379 # Port of master Redis server, uncomment to change to non default
-```
-
-[Reconfigure Omnibus GitLab][reconfigure] for the changes to take effect.
-
-### Example configuration for Sentinels
-
->**Note:**
-Redis Sentinel is bundled with Omnibus GitLab Enterprise Edition only. For the
-Omnibus Community Edition and installations from source, follow the
-[Redis HA source install](redis_source.md) guide.
-
-Please note that some of the variables are already configured previously
-as they are required for Redis replication.
-
-**Example configuration for Sentinel 1:**
-
-In `/etc/gitlab/gitlab.rb`:
-
-```ruby
-redis_sentinel_role['enable'] = true
-
 redis['master_name'] = 'gitlab-redis' # must be the same in every sentinel node
 redis['master_password'] = 'redis-password-goes-here' # the same value defined in redis['password'] in the master instance
 redis['master_ip'] = '10.0.0.1' # ip of the initial master redis instance
 #redis['master_port'] = 6379 # port of the initial master redis instance, uncomment to change to non default
-
-## Configure Sentinel
 sentinel['bind'] = '10.0.0.1'
 # sentinel['port'] = 26379 # uncomment to change default port
 sentinel['quorum'] = 2
-
-## Consider unresponsive server down after x amount of ms.
 # sentinel['down_after_milliseconds'] = 10000
-
 # sentinel['failover_timeout'] = 60000
 ```
 
 [Reconfigure Omnibus GitLab][reconfigure] for the changes to take effect.
 
-**Example configuration for Sentinel 2:**
+### Example configuration for Redis slave 1 and Sentinel 2
 
 In `/etc/gitlab/gitlab.rb`:
 
 ```ruby
+redis_slave_role['enable'] = true
 redis_sentinel_role['enable'] = true
-
+redis['bind'] = '10.0.0.2'
+redis['port'] = 6379
+redis['password'] = 'redis-password-goes-here'
+redis['master_password'] = 'redis-password-goes-here'
+redis['master_ip'] = '10.0.0.1' # IP of master Redis server
+#redis['master_port'] = 6379 # Port of master Redis server, uncomment to change to non default
 redis['master_name'] = 'gitlab-redis' # must be the same in every sentinel node
-redis['master_password'] = 'redis-password-goes-here' # the same value defined in redis['password'] in the master instance
-redis['master_ip'] = '10.0.0.1' # ip of the initial master redis instance
-#redis['master_port'] = 6379 # port of the initial master redis instance, uncomment to change to non default
-
-## Configure Sentinel
 sentinel['bind'] = '10.0.0.2'
 # sentinel['port'] = 26379 # uncomment to change default port
-
 sentinel['quorum'] = 2
-
-## Consider unresponsive server down after x amount of ms.
 # sentinel['down_after_milliseconds'] = 10000
-
 # sentinel['failover_timeout'] = 60000
 ```
 
 [Reconfigure Omnibus GitLab][reconfigure] for the changes to take effect.
 
-**Example configuration for Sentinel 3:**
+### Example configuration for Redis slave 2 and Sentinel 3
 
 In `/etc/gitlab/gitlab.rb`:
 
 ```ruby
+redis_slave_role['enable'] = true
 redis_sentinel_role['enable'] = true
-
+redis['bind'] = '10.0.0.3'
+redis['port'] = 6379
+redis['password'] = 'redis-password-goes-here'
+redis['master_password'] = 'redis-password-goes-here'
+redis['master_ip'] = '10.0.0.1' # IP of master Redis server
+#redis['master_port'] = 6379 # Port of master Redis server, uncomment to change to non default
 redis['master_name'] = 'gitlab-redis' # must be the same in every sentinel node
-redis['master_password'] = 'redis-password-goes-here' # the same value defined in redis['password'] in the master instance
-redis['master_ip'] = '10.0.0.1' # ip of the initial master redis instance
-#redis['master_port'] = 6379 # port of the initial master redis instance, uncomment to change to non default
-
-## Configure Sentinel
 sentinel['bind'] = '10.0.0.3'
 # sentinel['port'] = 26379 # uncomment to change default port
-
 sentinel['quorum'] = 2
-
-## Consider unresponsive server down after x amount of ms.
 # sentinel['down_after_milliseconds'] = 10000
-
 # sentinel['failover_timeout'] = 60000
 ```
 
@@ -740,14 +674,9 @@ sentinel['quorum'] = 2
 
 In `/etc/gitlab/gitlab.rb`:
 
-```
-# Must be the same in every sentinel node
+```ruby
 redis['master_name'] = 'gitlab-redis'
-
-# The same password for Redis authentication you set up for the master node.
 redis['password'] = 'redis-password-goes-here'
-
-# A list of sentinels with `host` and `port`
 gitlab_rails['redis_sentinels'] = [
   {'host' => '10.0.0.1', 'port' => 26379},
   {'host' => '10.0.0.2', 'port' => 26379},
@@ -970,3 +899,4 @@ Read more on high-availability configuration:
 [source]: ../../install/installation.md
 [ce]: https://about.gitlab.com/downloads
 [ee]: https://about.gitlab.com/downloads-ee
+[it]: https://gitlab.com/gitlab-org/gitlab-ce/uploads/c4cc8cd353604bd80315f9384035ff9e/The_Internet_IT_Crowd.png
-- 
cgit v1.2.1


From b6447f3027b7439e33bb8864992f5b4e60ca5cc5 Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axilleas@axilleas.me>
Date: Wed, 16 Nov 2016 11:51:28 +0100
Subject: Add steps to Redis HA source installation

---
 .../high_availability/redis_source.md              | 196 +++++++++++++--------
 1 file changed, 123 insertions(+), 73 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/high_availability/redis_source.md b/doc/administration/high_availability/redis_source.md
index a420d44f451..1660e26c784 100644
--- a/doc/administration/high_availability/redis_source.md
+++ b/doc/administration/high_availability/redis_source.md
@@ -38,45 +38,79 @@ the Omnibus Redis HA documentation.
 
 ## Configuring your own Redis server
 
-Redis server must be configured to use TCP connection instead of socket,
-and since Redis `3.2`, you must define a password to receive external
-connections (`requirepass`).
+This is the section where we install and setup the new Redis instances.
 
-You will also need to define equal password for slave password definition
-(`masterauth`), in the same instance, if you are using Redis with Sentinel.
+### Prerequisites
 
-To configure Redis to use TCP connection you need to define both
-`bind` and `port`. You can bind to all interfaces (`0.0.0.0`) or specify the
-IP of the desired interface (for ex. one from an internal network).
+- All Redis servers in this guide must be configured to use a TCP connection
+  instead of a socket. To configure Redis to use TCP connections you need to
+  define both `bind` and `port` in the Redis config file. You can bind to all
+  interfaces (`0.0.0.0`) or specify the IP of the desired interface
+  (e.g., one from an internal network).
+- Since Redis 3.2, you must define a password to receive external connections
+  (`requirepass`).
+- If you are using Redis with Sentinel, you will also need to define the same
+  password for the slave password definition (`masterauth`) in the same instance.
+
+In addition, read the prerequisites as described in the
+[Omnibus Redis HA document](redis.md#prerequisites) since they provide some
+valuable information for the general setup.
 
 ### Step 1. Configuring the master Redis instance
 
-You need to make the following changes in `redis.conf`:
+Assuming that the Redis master instance IP is `10.0.0.1`:
 
-1. Define a `bind` address pointing to a local IP that your other machines
-   can reach you. If you really need to bind to an external accessible IP, make
-   sure you add extra firewall rules to prevent unauthorized access:
+1. [Install Redis](../../install/installation.md#6-redis)
+1. Edit `/etc/redis/redis.conf`:
 
-1. Define a `port` to force redis to listen on TCP so other machines can
-   connect to it (default port is `6379`).
+    ```conf
+    ## Define a `bind` address pointing to a local IP that your other machines
+    ## can reach you. If you really need to bind to an external accessible IP, make
+    ## sure you add extra firewall rules to prevent unauthorized access:
+    bind 10.0.0.1
 
-1. Set up password authentication (use the same password in all nodes).
-   The password should be defined equal for both `requirepass` and `masterauth`
-   when setting up Redis to use with Sentinel.
+    ## Define a `port` to force redis to listen on TCP so other machines can
+    ## connect to it (default port is `6379`).
+    port 6379
 
-1. Restart the Redis services for the changes to take effect.
+    ## Set up password authentication (use the same password in all nodes).
+    ## The password should be defined equal for both `requirepass` and `masterauth`
+    ## when setting up Redis to use with Sentinel.
+    requirepass redis-password-goes-here
+    masterauth redis-password-goes-here
+    ```
 
-See [example configuration](#configuring-redis-master) below.
+1. Restart the Redis service for the changes to take effect.
 
 ### Step 2. Configuring the slave Redis instances
 
-1. Follow same instructions for Redis Master
+Assuming that the Redis slave instance IP is `10.0.0.2`:
+
+1. [Install Redis](../../install/installation.md#6-redis)
+1. Edit `/etc/redis/redis.conf`:
+
+    ```conf
+    ## Define a `bind` address pointing to a local IP that your other machines
+    ## can reach you. If you really need to bind to an external accessible IP, make
+    ## sure you add extra firewall rules to prevent unauthorized access:
+    bind 10.0.0.2
+
+    ## Define a `port` to force redis to listen on TCP so other machines can
+    ## connect to it (default port is `6379`).
+    port 6379
 
-1. Define `slaveof` pointing to the Redis master instance with **IP** and **port**.
+    ## Set up password authentication (use the same password in all nodes).
+    ## The password should be defined equal for both `requirepass` and `masterauth`
+    ## when setting up Redis to use with Sentinel.
+    requirepass redis-password-goes-here
+    masterauth redis-password-goes-here
 
-1. Restart the Redis services for the changes to take effect.
+    ## Define `slaveof` pointing to the Redis master instance with IP and port.
+    slaveof 10.0.0.1 6379
+    ```
 
-See [example configuration](#configuring-redis-slaves) below.
+1. Restart the Redis service for the changes to take effect.
+1. Go through the steps again for all the other slave nodes.
 
 ### Step 3. Configuring the Redis Sentinel instances
 
@@ -84,50 +118,64 @@ Sentinel is a special type of Redis server. It inherits most of the basic
 configuration options you can define in `redis.conf`, with specific ones
 starting with `sentinel` prefix.
 
-You will need to define the initial configs to enable connectivity:
-
-1. Define a `bind` address pointing to a local IP that your other machines
-   can reach you. If you really need to bind to an external accessible IP, make
-   sure you add extra firewall rules to prevent unauthorized access:
-
-1. Define a `port` to force sentinel to listen on TCP so other machines can
-   connect to it (default port is `26379`).
-
-And the sentinel specific ones:
-
-1. Define with `sentinel auth-pass` the same shared password you have
-   defined for both Redis **Master** and **Slaves** instances.
-
-1. Define with `sentinel monitor` the **IP** and **port** of the Redis
-   **Master** node, and the **quorum** required to start a failover.
-   If you need more information to understand about quorum, please
-   read the detailed explanation in the [HA documentation for Omnibus Installs](redis.md).
-
-1. Define with `sentinel down-after-milliseconds` the amount in `ms` of time
-   that an unresponsive server will be considered down.
-
-1. Define a value for `sentinel failover_timeout` in `ms`. This has multiple
-   meanings:
-
-   * The time needed to re-start a failover after a previous failover was
-     already tried against the same master by a given Sentinel, is two
-     times the failover timeout.
-
-   * The time needed for a slave replicating to a wrong master according
-     to a Sentinel current configuration, to be forced to replicate
-     with the right master, is exactly the failover timeout (counting since
-     the moment a Sentinel detected the misconfiguration).
-
-   * The time needed to cancel a failover that is already in progress but
-     did not produced any configuration change (SLAVEOF NO ONE yet not
-     acknowledged by the promoted slave).
-
-   * The maximum time a failover in progress waits for all the slaves to be
-     reconfigured as slaves of the new master. However even after this time
-     the slaves will be reconfigured by the Sentinels anyway, but not with
-     the exact parallel-syncs progression as specified.
-
-See [example configuration](#configuring-redis-sentinel) below.
+Assuming that the Redis Sentinel is installed on the same instance as Redis
+master with IP `10.0.0.1` (some settings might overlap with the master):
+
+1. [Install Redis](../../install/installation.md#6-redis)
+1. Edit `/etc/redis/redis.conf`:
+
+    ```conf
+    ## Define a `bind` address pointing to a local IP that your other machines
+    ## can reach you. If you really need to bind to an external accessible IP, make
+    ## sure you add extra firewall rules to prevent unauthorized access:
+    bind 10.0.0.1
+
+    ## Define a `port` to force Sentinel to listen on TCP so other machines can
+    ## connect to it (default port is `6379`).
+    port 26379
+
+    ## Set up password authentication (use the same password in all nodes).
+    ## The password should be defined equal for both `requirepass` and `masterauth`
+    ## when setting up Redis to use with Sentinel.
+    requirepass redis-password-goes-here
+    masterauth redis-password-goes-here
+
+    ## Define with `sentinel auth-pass` the same shared password you have
+    ## defined for both Redis master and slaves instances.
+    sentinel auth-pass gitlab-redis redis-password-goes-here
+
+    ## Define with `sentinel monitor` the IP and port of the Redis
+    ## master node, and the quorum required to start a failover.
+    sentinel monitor gitlab-redis 10.0.0.1 6379 2
+
+    ## Define with `sentinel down-after-milliseconds` the time in `ms`
+    ## that an unresponsive server will be considered down.
+    sentinel down-after-milliseconds gitlab-redis 10000
+
+    ## Define a value for `sentinel failover_timeout` in `ms`. This has multiple
+    ## meanings:
+    ##
+    ## * The time needed to re-start a failover after a previous failover was
+    ##   already tried against the same master by a given Sentinel, is two
+    ##   times the failover timeout.
+    ##
+    ## * The time needed for a slave replicating to a wrong master according
+    ##   to a Sentinel current configuration, to be forced to replicate
+    ##   with the right master, is exactly the failover timeout (counting since
+    ##   the moment a Sentinel detected the misconfiguration).
+    ##
+    ## * The time needed to cancel a failover that is already in progress but
+    ##   did not produced any configuration change (SLAVEOF NO ONE yet not
+    ##   acknowledged by the promoted slave).
+    ##
+    ## * The maximum time a failover in progress waits for all the slaves to be
+    ##   reconfigured as slaves of the new master. However even after this time
+    ##   the slaves will be reconfigured by the Sentinels anyway, but not with
+    ##   the exact parallel-syncs progression as specified.
+    sentinel failover_timeout 30000
+    ```
+1. Restart the Redis service for the changes to take effect.
+1. Go through the steps again for all the other Sentinel nodes.
 
 ### Step 4. Configuring the GitLab application
 
@@ -136,17 +184,17 @@ installations. From the GitLab application perspective, all it requires is
 the correct credentials for the Sentinel nodes.
 
 While it doesn't require a list of all Sentinel nodes, in case of a failure,
-it needs to access at one of listed ones.
+it needs to access at least one of listed ones.
 
->**Note:**
 The following steps should be performed in the [GitLab application server](gitlab.md)
-which ideally should not have Redis or Sentinels in the same machine for a HA setup.
+which ideally should not have Redis or Sentinels in the same machine for a HA
+setup:
 
 1. Edit `/home/git/gitlab/config/resque.yml` following the example in
    `/home/git/gitlab/config/resque.yml.example`, and uncomment the sentinels
    lines, pointing to the correct server credentials.
 
-1. Restart GitLab for the changes to take effect.
+1. [Restart GitLab][restart] for the changes to take effect.
 
 ## Example of minimal configuration with 1 master, 2 slaves and 3 Sentinels
 
@@ -156,7 +204,7 @@ to each other using these IPs.
 
 In a real world usage, you would also setup firewall rules to prevent
 unauthorized access from other machines, and block traffic from the
-outside (Internet).
+outside ([Internet][it]).
 
 We will use the same `3` nodes with **Redis** + **Sentinel** topology
 discussed in the [Configuring Redis for GitLab HA](redis.md) documentation.
@@ -165,7 +213,7 @@ Here is a list and description of each **machine** and the assigned **IP**:
 
 * `10.0.0.1`: Redis Master + Sentinel 1
 * `10.0.0.2`: Redis Slave 1 + Sentinel 2
-* `10.0.0.2`: Redis Slave 2 + Sentinel 3
+* `10.0.0.3`: Redis Slave 2 + Sentinel 3
 
 Please note that after the initial configuration, if a failover is initiated
 by the Sentinel nodes, the Redis nodes will be reconfigured and the **Master**
@@ -296,3 +344,5 @@ When in doubt, please read [Redis Sentinel documentation](http://redis.io/topics
 
 [gh-531]: https://github.com/redis/redis-rb/issues/531
 [downloads]: https://about.gitlab.com/downloads
+[restart]: ../restart_gitlab.md#installations-from-source
+[it]: https://gitlab.com/gitlab-org/gitlab-ce/uploads/c4cc8cd353604bd80315f9384035ff9e/The_Internet_IT_Crowd.png
-- 
cgit v1.2.1


From 850405b42ef408785c6133ab7ba9c7f7303f18b6 Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axilleas@axilleas.me>
Date: Wed, 16 Nov 2016 12:04:33 +0100
Subject: Merge examples of Redis master/slave + Sentinels for source docs

[ci skip]
---
 .../high_availability/redis_source.md              | 173 +++++++++++++--------
 1 file changed, 106 insertions(+), 67 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/high_availability/redis_source.md b/doc/administration/high_availability/redis_source.md
index 1660e26c784..e7a8f47355d 100644
--- a/doc/administration/high_availability/redis_source.md
+++ b/doc/administration/high_availability/redis_source.md
@@ -24,14 +24,16 @@ the Omnibus Redis HA documentation.
 **Table of Contents**
 
 - [Configuring your own Redis server](#configuring-your-own-redis-server)
+  - [Prerequisites](#prerequisites)
   - [Step 1. Configuring the master Redis instance](#step-1-configuring-the-master-redis-instance)
   - [Step 2. Configuring the slave Redis instances](#step-2-configuring-the-slave-redis-instances)
   - [Step 3. Configuring the Redis Sentinel instances](#step-3-configuring-the-redis-sentinel-instances)
   - [Step 4. Configuring the GitLab application](#step-4-configuring-the-gitlab-application)
 - [Example of minimal configuration with 1 master, 2 slaves and 3 Sentinels](#example-of-minimal-configuration-with-1-master-2-slaves-and-3-sentinels)
-  - [Configuring Redis Master](#configuring-redis-master)
-  - [Configuring Redis Slaves](#configuring-redis-slaves)
-  - [Configuring Redis Sentinel](#configuring-redis-sentinel)
+  - [Example configuration for Redis master and Sentinel 1](#example-configuration-for-redis-master-and-sentinel-1)
+  - [Example configuration for Redis slave 1 and Sentinel 2](#example-configuration-for-redis-slave-1-and-sentinel-2)
+  - [Example configuration for Redis slave 2 and Sentinel 3](#example-configuration-for-redis-slave-2-and-sentinel-3)
+  - [Example configuration of the GitLab application](#example-configuration-of-the-gitlab-application)
 - [Troubleshooting](#troubleshooting)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -121,8 +123,8 @@ starting with `sentinel` prefix.
 Assuming that the Redis Sentinel is installed on the same instance as Redis
 master with IP `10.0.0.1` (some settings might overlap with the master):
 
-1. [Install Redis](../../install/installation.md#6-redis)
-1. Edit `/etc/redis/redis.conf`:
+1. [Install Redis Sentinel](http://redis.io/topics/sentinel)
+1. Edit `/etc/redis/sentinel.conf`:
 
     ```conf
     ## Define a `bind` address pointing to a local IP that your other machines
@@ -191,8 +193,24 @@ which ideally should not have Redis or Sentinels in the same machine for a HA
 setup:
 
 1. Edit `/home/git/gitlab/config/resque.yml` following the example in
-   `/home/git/gitlab/config/resque.yml.example`, and uncomment the sentinels
-   lines, pointing to the correct server credentials.
+   [resque.yml.example][resque], and uncomment the Sentinel lines, pointing to
+   the correct server credentials:
+
+    ```yaml
+    # resque.yaml
+    production:
+      url: redis://:redi-password-goes-here@gitlab-redis/
+      sentinels:
+        -
+          host: 10.0.0.1
+          port: 26379 # point to sentinel, not to redis port
+        -
+          host: 10.0.0.2
+          port: 26379 # point to sentinel, not to redis port
+        -
+          host: 10.0.0.3
+          port: 26379 # point to sentinel, not to redis port
+    ```
 
 1. [Restart GitLab][restart] for the changes to take effect.
 
@@ -206,14 +224,16 @@ In a real world usage, you would also setup firewall rules to prevent
 unauthorized access from other machines, and block traffic from the
 outside ([Internet][it]).
 
-We will use the same `3` nodes with **Redis** + **Sentinel** topology
-discussed in the [Configuring Redis for GitLab HA](redis.md) documentation.
+For this example, **Sentinel 1** will be configured in the same machine as the
+**Redis Master**, **Sentinel 2** and **Sentinel 3** in the same machines as the
+**Slave 1** and **Slave 2** respectively.
 
 Here is a list and description of each **machine** and the assigned **IP**:
 
 * `10.0.0.1`: Redis Master + Sentinel 1
 * `10.0.0.2`: Redis Slave 1 + Sentinel 2
 * `10.0.0.3`: Redis Slave 2 + Sentinel 3
+* `10.0.0.4`: GitLab application
 
 Please note that after the initial configuration, if a failover is initiated
 by the Sentinel nodes, the Redis nodes will be reconfigured and the **Master**
@@ -224,81 +244,100 @@ The same thing will happen with `sentinel.conf` that will be overridden after th
 initial execution, after any new sentinel node starts watching the **Master**,
 or a failover promotes a different **Master** node.
 
-### Configuring Redis Master
+### Example configuration for Redis master and Sentinel 1
 
-**Example configation for Redis Master - `redis.conf`:**
+1. In `/etc/redis/redis.conf`:
 
-```conf
-bind 10.0.0.1
-port 6379
-requirepass redis-password-goes-here
-masterauth redis-password-goes-here
-```
+    ```conf
+    bind 10.0.0.1
+    port 6379
+    requirepass redis-password-goes-here
+    masterauth redis-password-goes-here
+    ```
+
+1. In `/etc/redis/sentinel.conf`:
 
-### Configuring Redis Slaves
+    ```conf
+    bind 10.0.0.1
+    port 26379
+    sentinel auth-pass gitlab-redis redis-password-goes-here
+    sentinel monitor gitlab-redis 10.0.0.1 6379 2
+    sentinel down-after-milliseconds gitlab-redis 10000
+    sentinel failover_timeout 30000
+    ```
 
-**Example configation for Slave 1 - `redis.conf`:**
+1. Restart the Redis service for the changes to take effect.
 
-```conf
-bind 10.0.0.2
-port 6379
-requirepass redis-password-goes-here
-masterauth redis-password-goes-here
+### Example configuration for Redis slave 1 and Sentinel 2
 
-# IP and port of the master Redis server
-slaveof 10.0.0.1 6379
-```
+1. In `/etc/redis/redis.conf`:
 
-**Example configation for Slave 2 - `redis.conf`:**
+    ```conf
+    bind 10.0.0.2
+    port 6379
+    requirepass redis-password-goes-here
+    masterauth redis-password-goes-here
+    slaveof 10.0.0.1 6379
+    ```
 
-```conf
-bind 10.0.0.3
-port 6379
-requirepass redis-password-goes-here
-masterauth redis-password-goes-here
+1. In `/etc/redis/sentinel.conf`:
 
-# IP and port of the master Redis server
-slaveof 10.0.0.1 6379
-```
+    ```conf
+    bind 10.0.0.2
+    port 26379
+    sentinel auth-pass gitlab-redis redis-password-goes-here
+    sentinel monitor gitlab-redis 10.0.0.1 6379 2
+    sentinel down-after-milliseconds gitlab-redis 10000
+    sentinel failover_timeout 30000
+    ```
 
-### Configuring Redis Sentinel
+1. Restart the Redis service for the changes to take effect.
 
-For this example, **Sentinel 1** will be configured in the same machine as the
-**Redis Master**, **Sentinel 2** and **Sentinel 3** in the same machines as the
-**Slave 1** and **Slave 2** respectively.
+### Example configuration for Redis slave 2 and Sentinel 3
 
-**Example configation for Sentinel 1 - `sentinel.conf`:**
+1. In `/etc/redis/redis.conf`:
 
-```conf
-bind 10.0.0.1
-port 26379
-sentinel auth-pass gitlab-redis redis-password-goes-here
-sentinel monitor gitlab-redis 10.0.0.1 6379 2
-sentinel down-after-milliseconds gitlab-redis 10000
-sentinel failover_timeout 30000
-```
+    ```conf
+    bind 10.0.0.3
+    port 6379
+    requirepass redis-password-goes-here
+    masterauth redis-password-goes-here
+    slaveof 10.0.0.1 6379
+    ```
 
-**Example configation for Sentinel 2 - `sentinel.conf`:**
+1. In `/etc/redis/sentinel.conf`:
 
-```conf
-bind 10.0.0.2
-port 26379
-sentinel auth-pass gitlab-redis redis-password-goes-here
-sentinel monitor gitlab-redis 10.0.0.1 6379 2
-sentinel down-after-milliseconds gitlab-redis 10000
-sentinel failover_timeout 30000
-```
+    ```conf
+    bind 10.0.0.3
+    port 26379
+    sentinel auth-pass gitlab-redis redis-password-goes-here
+    sentinel monitor gitlab-redis 10.0.0.1 6379 2
+    sentinel down-after-milliseconds gitlab-redis 10000
+    sentinel failover_timeout 30000
+    ```
 
-**Example configation for Sentinel 3 - `sentinel.conf`:**
+1. Restart the Redis service for the changes to take effect.
 
-```conf
-bind 10.0.0.3
-port 26379
-sentinel auth-pass gitlab-redis redis-password-goes-here
-sentinel monitor gitlab-redis 10.0.0.1 6379 2
-sentinel down-after-milliseconds gitlab-redis 10000
-sentinel failover_timeout 30000
-```
+### Example configuration of the GitLab application
+
+1. Edit `/home/git/gitlab/config/resque.yml`:
+
+    ```yaml
+    production:
+      url: redis://:redi-password-goes-here@gitlab-redis/
+      sentinels:
+        -
+          host: 10.0.0.1
+          port: 26379 # point to sentinel, not to redis port
+        -
+          host: 10.0.0.2
+          port: 26379 # point to sentinel, not to redis port
+        -
+          host: 10.0.0.3
+          port: 26379 # point to sentinel, not to redis port
+    ```
+
+1. [Restart GitLab][restart] for the changes to take effect.
 
 ## Troubleshooting
 
-- 
cgit v1.2.1


From 04f2dd65fb355eb3bf20e0d3deef9123132aacad Mon Sep 17 00:00:00 2001
From: Marin Jankovski <maxlazio@gmail.com>
Date: Fri, 11 Nov 2016 15:49:51 +0100
Subject: Add idle_timeout to reply by email doc.

---
 doc/administration/reply_by_email.md | 10 ++++++++++
 1 file changed, 10 insertions(+)

(limited to 'doc/administration')

diff --git a/doc/administration/reply_by_email.md b/doc/administration/reply_by_email.md
index 5a9a1582877..b42892eef68 100644
--- a/doc/administration/reply_by_email.md
+++ b/doc/administration/reply_by_email.md
@@ -105,6 +105,8 @@ To set up a basic Postfix mail server with IMAP access on Ubuntu, follow
 
     # The mailbox where incoming mail will end up. Usually "inbox".
     gitlab_rails['incoming_email_mailbox_name'] = "inbox"
+    # The IDLE command timeout.
+    gitlab_rails['incoming_email_idle_timeout'] = 60
     ```
 
     ```ruby
@@ -133,6 +135,8 @@ To set up a basic Postfix mail server with IMAP access on Ubuntu, follow
 
     # The mailbox where incoming mail will end up. Usually "inbox".
     gitlab_rails['incoming_email_mailbox_name'] = "inbox"
+    # The IDLE command timeout.
+    gitlab_rails['incoming_email_idle_timeout'] = 60
     ```
 
 1. Reconfigure GitLab and restart mailroom for the changes to take effect:
@@ -192,6 +196,8 @@ To set up a basic Postfix mail server with IMAP access on Ubuntu, follow
 
       # The mailbox where incoming mail will end up. Usually "inbox".
       mailbox: "inbox"
+      # The IDLE command timeout.
+      email_idle_timeout: 60
     ```
 
     ```yaml
@@ -221,6 +227,8 @@ To set up a basic Postfix mail server with IMAP access on Ubuntu, follow
 
       # The mailbox where incoming mail will end up. Usually "inbox".
       mailbox: "inbox"
+      # The IDLE command timeout.
+      email_idle_timeout: 60
     ```
 
 1. Enable `mail_room` in the init script at `/etc/default/gitlab`:
@@ -277,6 +285,8 @@ To set up a basic Postfix mail server with IMAP access on Ubuntu, follow
 
       # The mailbox where incoming mail will end up. Usually "inbox".
       mailbox: "inbox"
+      # The IDLE command timeout.
+      email_idle_timeout: 60
     ```
 
     As mentioned, the part after `+` is ignored, and this will end up in the mailbox for `gitlab-incoming@gmail.com`.
-- 
cgit v1.2.1


From baf09d2a7a78f9260f3dff601ed7a10d18d3bec4 Mon Sep 17 00:00:00 2001
From: Gabriel Mazetto <gabriel@gitlab.com>
Date: Thu, 22 Sep 2016 06:05:28 -0300
Subject: Improved redis sentinel documentation for CE

---
 doc/administration/high_availability/redis.md | 62 +++++++++++----------------
 1 file changed, 26 insertions(+), 36 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md
index 8656b42f274..a1426575abd 100644
--- a/doc/administration/high_availability/redis.md
+++ b/doc/administration/high_availability/redis.md
@@ -143,6 +143,7 @@ the master, and `masterauth` in slaves.
     redis['port'] = 6379
 
     ## Slave redis instance
+    redis['master'] = false
     redis['master_ip'] = '10.10.10.10' # IP of master Redis server
     redis['master_port'] = 6379 # Port of master Redis server
     redis['master_password'] = "<huge password string here>"
@@ -157,31 +158,19 @@ servers.
 
 ### Sentinel setup
 
-We don't provide yet an automated way to setup and run the Sentinel daemon
-from Omnibus installation method. You must follow the instructions below and
-run it by yourself.
+We provide an automated way to setup and run the Sentinel daemon
+with GitLab EE.
 
-The support for Sentinel in Ruby has some [caveats](https://github.com/redis/redis-rb/issues/531).
-While you can give any name for the `master-group-name` part of the
-configuration, as in this example:
-
-```conf
-sentinel monitor <master-group-name> <ip> <port> <quorum>
-```
-
-,for it to work in Ruby, you have to use the "hostname" of the master Redis
-server, otherwise you will get an error message like:
-`Redis::CannotConnectError: No sentinels available.`. Read
-[Sentinel troubleshooting](#sentinel-troubleshooting) for more information.
+See the instructions below how to setup it by yourself.
 
 Here is an example configuration file (`sentinel.conf`) for a Sentinel node:
 
 ```conf
 port 26379
-sentinel monitor master-redis.example.com 10.10.10.10 6379 1
-sentinel down-after-milliseconds master-redis.example.com 10000
-sentinel config-epoch master-redis.example.com 0
-sentinel leader-epoch master-redis.example.com 0
+sentinel monitor gitlab-redis 10.0.0.1 6379 1
+sentinel down-after-milliseconds gitlab-redis 10000
+sentinel config-epoch gitlab-redis 0
+sentinel leader-epoch gitlab-redis 0
 ```
 
 ---
@@ -213,10 +202,11 @@ The following steps should be performed in the [GitLab application server](gitla
 1. Edit `/etc/gitlab/gitlab.rb` and add/change the following lines:
 
     ```ruby
-    gitlab-rails['redis_host'] = "master-redis.example.com"
-    gitlab-rails['redis_port'] = 6379
-    gitlab-rails['redis_password'] = '<huge password string here>'
-    gitlab-rails['redis_sentinels'] = [
+    redis['master_name'] = "gitlab-redis"
+    redis['master_ip'] = "10.0.0.1"
+    redis['master_port'] = 6379
+    redis['master_password'] = '<huge password string here>'
+    gitlab_rails['redis_sentinels'] = [
       {'host' => '10.10.10.1', 'port' => 26379},
       {'host' => '10.10.10.2', 'port' => 26379},
       {'host' => '10.10.10.3', 'port' => 26379}
@@ -229,33 +219,33 @@ The following steps should be performed in the [GitLab application server](gitla
 
 If you get an error like: `Redis::CannotConnectError: No sentinels available.`,
 there may be something wrong with your configuration files or it can be related
-to [this issue][gh-531] ([pull request][gh-534] that should make things better).
+to [this issue][gh-531].
 
-It's a bit rigid the way you have to config `resque.yml` and `sentinel.conf`,
-otherwise `redis-rb` will not work properly.
+It's a bit non-intuitive the way you have to config `resque.yml` and
+`sentinel.conf`, otherwise `redis-rb` will not work properly.
 
-The hostname ('my-primary-redis') of the primary Redis server (`sentinel.conf`)
-**must** match the one configured in GitLab (`resque.yml` for source installations
-or `gitlab-rails['redis_*']` in Omnibus) and it must be valid ex:
+The `master-group-name` ('gitlab-redis') defined in (`sentinel.conf`)
+**must** be used as the hostname in GitLab (`resque.yml` for source installations
+or `gitlab-rails['redis_*']` in Omnibus):
 
 ```conf
 # sentinel.conf:
-sentinel monitor my-primary-redis 10.10.10.10 6379 1
-sentinel down-after-milliseconds my-primary-redis 10000
-sentinel config-epoch my-primary-redis 0
-sentinel leader-epoch my-primary-redis 0
+sentinel monitor gitlab-redis 10.10.10.10 6379 1
+sentinel down-after-milliseconds gitlab-redis 10000
+sentinel config-epoch gitlab-redis 0
+sentinel leader-epoch gitlab-redis 0
 ```
 
 ```yaml
 # resque.yaml
 production:
-  url: redis://my-primary-redis:6378
+  url: redis://:myredispassword@gitlab-redis/
   sentinels:
     -
-      host: slave1
+      host: slave1.example.com # or use ip
       port: 26380 # point to sentinel, not to redis port
     -
-      host: slave2
+      host: slave2.exampl.com # or use ip
       port: 26381 # point to sentinel, not to redis port
 ```
 
-- 
cgit v1.2.1


From eb73cd08086c445210532c746ce305938bc1b53c Mon Sep 17 00:00:00 2001
From: Gabriel Mazetto <gabriel@gitlab.com>
Date: Fri, 7 Oct 2016 01:16:32 +0200
Subject: Small fixes on Sentinel documentation for CE

---
 doc/administration/high_availability/redis.md | 2 --
 1 file changed, 2 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md
index a1426575abd..97842f50b81 100644
--- a/doc/administration/high_availability/redis.md
+++ b/doc/administration/high_availability/redis.md
@@ -203,8 +203,6 @@ The following steps should be performed in the [GitLab application server](gitla
 
     ```ruby
     redis['master_name'] = "gitlab-redis"
-    redis['master_ip'] = "10.0.0.1"
-    redis['master_port'] = 6379
     redis['master_password'] = '<huge password string here>'
     gitlab_rails['redis_sentinels'] = [
       {'host' => '10.10.10.1', 'port' => 26379},
-- 
cgit v1.2.1


From e26d8e0272d822a5086ce073a67039cf0107c9c8 Mon Sep 17 00:00:00 2001
From: Gabriel Mazetto <gabriel@gitlab.com>
Date: Fri, 7 Oct 2016 01:47:22 +0200
Subject: Updated password examples and improved omnibus troubleshooting

---
 doc/administration/high_availability/redis.md | 23 +++++++++++++++++++----
 1 file changed, 19 insertions(+), 4 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md
index 97842f50b81..acdfc2773a9 100644
--- a/doc/administration/high_availability/redis.md
+++ b/doc/administration/high_availability/redis.md
@@ -45,7 +45,7 @@ Redis.
     redis['bind'] = '0.0.0.0'
 
     # If you wish to use Redis authentication (recommended)
-    redis['password'] = 'Redis Password'
+    redis['password'] = 'redis-password-goes-here'
     ```
 
 1. Run `sudo touch /etc/gitlab/skip-auto-migrations` to prevent database migrations
@@ -132,7 +132,7 @@ the master, and `masterauth` in slaves.
     redis['port'] = 6379
 
     ## Master redis instance
-    redis['password'] = '<huge password string here>'
+    redis['password'] = 'redis-password-goes-here'
     ```
 
 1. Edit `/etc/gitlab/gitlab.rb` of a slave Redis machine (should be one or more machines):
@@ -146,7 +146,7 @@ the master, and `masterauth` in slaves.
     redis['master'] = false
     redis['master_ip'] = '10.10.10.10' # IP of master Redis server
     redis['master_port'] = 6379 # Port of master Redis server
-    redis['master_password'] = "<huge password string here>"
+    redis['master_password'] = "redis-password-goes-here"
     ```
 
 1. Reconfigure the GitLab for the changes to take effect: `sudo gitlab-ctl reconfigure`
@@ -203,7 +203,7 @@ The following steps should be performed in the [GitLab application server](gitla
 
     ```ruby
     redis['master_name'] = "gitlab-redis"
-    redis['master_password'] = '<huge password string here>'
+    redis['master_password'] = 'redis-password-goes-here'
     gitlab_rails['redis_sentinels'] = [
       {'host' => '10.10.10.1', 'port' => 26379},
       {'host' => '10.10.10.2', 'port' => 26379},
@@ -215,6 +215,21 @@ The following steps should be performed in the [GitLab application server](gitla
 
 ### Sentinel troubleshooting
 
+#### Omnibus install
+
+If you get an error like: `Redis::CannotConnectError: No sentinels available.`,
+there may be something wrong with your configuration files or it can be related
+to [this issue][gh-531].
+
+You must make sure you are defining the same value in `redis['master_name']`
+and `redis['master_pasword']` as you defined for your sentinel node.
+
+The way the redis connector `redis-rb` works with sentinel is a bit
+non-intuitive. We try to hide the complexity in omnibus, but it still requires
+a few extra configs.
+
+#### Source install
+
 If you get an error like: `Redis::CannotConnectError: No sentinels available.`,
 there may be something wrong with your configuration files or it can be related
 to [this issue][gh-531].
-- 
cgit v1.2.1


From 95f6cf339a8c0f5d63178a92eaef2d02bcfb297f Mon Sep 17 00:00:00 2001
From: Gabriel Mazetto <gabriel@gitlab.com>
Date: Sat, 15 Oct 2016 05:40:15 +0200
Subject: Improved documentation on HA sentinel part and Redis replication
 troubleshooting.

---
 doc/administration/high_availability/redis.md | 316 +++++++++++++++++++++-----
 1 file changed, 256 insertions(+), 60 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md
index acdfc2773a9..e416514bedf 100644
--- a/doc/administration/high_availability/redis.md
+++ b/doc/administration/high_availability/redis.md
@@ -8,6 +8,27 @@ that comes bundled with GitLab Omnibus packages.
   information. We recommend using a combination of a Redis password and tight
   firewall rules to secure your Redis service.
 
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**
+
+- [Configure your own Redis server](#configure-your-own-redis-server)
+- [Configure Redis using Omnibus](#configure-redis-using-omnibus)
+- [Experimental Redis Sentinel support](#experimental-redis-sentinel-support)
+  - [Redis setup](#redis-setup)
+    - [Source install](#source-install)
+    - [Omnibus Install](#omnibus-install)
+    - [Troubleshooting Replication](#troubleshooting-replication)
+  - [Sentinel](#sentinel)
+    - [Sentinel setup (Community Edition)](#sentinel-setup-community-edition)
+    - [Sentinel setup (EE Only)](#sentinel-setup-ee-only)
+  - [GitLab setup](#gitlab-setup)
+  - [Sentinel troubleshooting](#sentinel-troubleshooting)
+    - [Omnibus install](#omnibus-install)
+    - [Source install](#source-install-1)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 ## Configure your own Redis server
 
 If you're hosting GitLab on a cloud provider, you can optionally use a
@@ -37,6 +58,7 @@ Redis.
     unicorn['enable'] = false
     sidekiq['enable'] = false
     postgresql['enable'] = false
+    gitlab_rails['enable'] = false
     gitlab_workhorse['enable'] = false
     mailroom['enable'] = false
 
@@ -59,120 +81,294 @@ Redis.
 
 ## Experimental Redis Sentinel support
 
-> [Introduced][ce-1877] in GitLab 8.11.
+> [Introduced][ce-1877] in GitLab 8.11, improved in 8.13.
 
 Since GitLab 8.11, you can configure a list of Redis Sentinel servers that
 will monitor a group of Redis servers to provide you with a standard failover
 support.
 
-There is currently one exception to the Sentinel support: `mail_room`, the
-component that processes incoming emails. It doesn't support Sentinel yet, but
-we hope to integrate a future release that does support it.
-
 To get a better understanding on how to correctly setup Sentinel, please read
 the [Redis Sentinel documentation](http://redis.io/topics/sentinel) first, as
 failing to configure it correctly can lead to data loss.
 
+Redis Sentinel can handle the most important tasks in a HA environment to help
+keep servers online with minimal to no downtime:
+
+- Monitors master and slave instances to see if they are available
+- Promote a slave to master when the master fails.
+- Demote a master to slave when failed master comes back online (to prevent
+  data-partitioning).
+- Can be queried by clients to always connect to the correct master server.
+
+There is currently one exception to the Sentinel support: `mail_room`, the
+component that processes incoming emails. It doesn't support Sentinel yet, but
+we hope to integrate a future release that does support it soon.
+
 The configuration consists of three parts:
 
-- Redis setup
-- Sentinel setup
-- GitLab setup
+- Setup Redis Master and Slave nodes
+- Setup Sentinel nodes
+- Setup GitLab
+
+> **IMPORTANT**: You need at least 3 independent machines: physical, or VMs
+running into distinct physical machines. If you fail to provision the
+machines in that specific way, any issue with the shared environment can
+bring your entire setup down.
 
 Read carefully how to configure those components below.
 
 ### Redis setup
 
-You must have at least 2 Redis servers: 1 Master, 1 or more Slaves.
+You must have at least `3` Redis servers: `1` Master, `2` Slaves, and they need to
+be each in a independent machine (see explanation above).
+
 They should be configured the same way and with similar server specs, as
-in a failover situation, any Slave can be elected as the new Master by
+in a failover situation, any `Slave` can be elected as the new `Master` by
 the Sentinel servers.
 
-In a minimal setup, the only required change for the slaves in `redis.conf`
-is the addition of a `slaveof` line pointing to the initial master.
-You can increase the security by defining a `requirepass` configuration in
-the master, and `masterauth` in slaves.
+With Sentinel, you must define a password to protect the access as both
+Sentinel instances and other redis instances should be able to talk to
+each other over the network.
 
----
+You'll need to define both `requirepass` and `masterauth` in all
+nodes because they can be re-configured at any time by the Sentinels
+during a failover, and change it's status as `Master` or `Slave`.
 
-**Configuring your own Redis server**
+Initial `Slave` nodes will have in `redis.conf` an additional `slaveof` line
+pointing to the initial `Master`.
 
-1. Add to the slaves' `redis.conf`:
+#### Source install
 
-    ```conf
-    # IP and port of the master Redis server
-    slaveof 10.10.10.10 6379
-    ```
+**Master Redis instance**
 
-1. Optionally, set up password authentication for increased security.
-   Add the following to master's `redis.conf`:
+You need to make the following changes in `redis.conf`:
 
-    ```conf
-    # Optional password authentication for increased security
-    requirepass "<password>"
-    ```
+1. Define a `bind` address pointing to a local IP that your other machines
+   can reach you. If you really need to bind to an external acessible IP, make
+   sure you add extra firewall rules to prevent unauthorized access:
 
-1. Then add this line to all the slave servers' `redis.conf`:
+   ```conf
+   # By default, if no "bind" configuration directive is specified, Redis listens
+   # for connections from all the network interfaces available on the server.
+   # It is possible to listen to just one or multiple selected interfaces using
+   # the "bind" configuration directive, followed by one or more IP addresses.
+   #
+   # Examples:
+   #
+   # bind 192.168.1.100 10.0.0.1
+   # bind 127.0.0.1 ::1
+   bind 0.0.0.0 # This will bind to all interfaces
+   ```
+
+1. Define a `port` to force redis to listin on TCP so other machines can
+   connect to it:
+
+   ```conf
+   # Accept connections on the specified port, default is 6379 (IANA #815344).
+   # If port 0 is specified Redis will not listen on a TCP socket.
+   port 6379
+   ```
+
+1. Set up password authentication (use the same password in all nodes)
 
     ```conf
-    masterauth "<password>"
+    requirepass "redis-password-goes-here"
+    masterauth "redis-password-goes-here"
     ```
 
 1. Restart the Redis services for the changes to take effect.
 
----
+**Slave Redis instance**
 
-**Using Redis via Omnibus**
+1. Follow same instructions from master with the extra change in `redis.conf`:
 
-1. Edit `/etc/gitlab/gitlab.rb` of a master Redis machine (usualy a single machine):
+   ```conf
+   # IP and port of the master Redis server
+   slaveof 10.10.10.10 6379
+   ```
 
-    ```ruby
-    ## Redis TCP support (will disable UNIX socket transport)
-    redis['bind'] = '0.0.0.0' # or specify an IP to bind to a single one
-    redis['port'] = 6379
+1. Restart the Redis services for the changes to take effect.
 
-    ## Master redis instance
-    redis['password'] = 'redis-password-goes-here'
-    ```
+#### Omnibus Install
 
-1. Edit `/etc/gitlab/gitlab.rb` of a slave Redis machine (should be one or more machines):
+You need to install the omnibus package in 3 different and independent machines.
+We will elect one as the initial `Master` and the other 2 as `Slaves`.
 
-    ```ruby
-    ## Redis TCP support (will disable UNIX socket transport)
-    redis['bind'] = '0.0.0.0' # or specify an IP to bind to a single one
-    redis['port'] = 6379
+If you are migrating from a single machine install, you may want to setup the
+machines as Slaves, pointing to the original machine as `Master`, to migrate
+the data first, and than switch to this setup.
 
-    ## Slave redis instance
-    redis['master'] = false
-    redis['master_ip'] = '10.10.10.10' # IP of master Redis server
-    redis['master_port'] = 6379 # Port of master Redis server
-    redis['master_password'] = "redis-password-goes-here"
-    ```
+To disable redis in the single install, edit `/etc/gitlab/gitlab.rb`:
+
+```ruby
+redis['enable'] = false
+```
+
+**Master Redis instances**
+
+You need to make the following changes in `/etc/gitlab/gitlab.rb`:
+
+1. Define a `redis['bind']` address pointing to a local IP that your other machines
+   can reach you. If you really need to bind to an external acessible IP, make
+   sure you add extra firewall rules to prevent unauthorized access.
+1. Define a `redis['port']` to force redis to listin on TCP so other machines can
+   connect to it.
+1. Set up password authentication with `redis['master_password']` (use the same
+   password in all nodes).
 
-1. Reconfigure the GitLab for the changes to take effect: `sudo gitlab-ctl reconfigure`
+```ruby
+## Redis TCP support (will disable UNIX socket transport)
+redis['bind'] = '0.0.0.0' # or specify an IP to bind to a single one
+redis['port'] = 6379
+redis['requirepass'] = 'redis-password-goes-here'
+redis['master_password'] = 'redis-password-goes-here'
+```
+
+Reconfigure GitLab Omnibus for the changes to take effect: `sudo gitlab-ctl reconfigure`
+
+**Slave Redis instances**
+
+You need to make the same changes listed for the `Master` instance,
+with an additional `Slave` section as in the example below:
+
+```ruby
+## Redis TCP support (will disable UNIX socket transport)
+redis['bind'] = '0.0.0.0' # or specify an IP to bind to a single one
+redis['port'] = 6379
+redis['requirepass'] = 'redis-password-goes-here'
+redis['master_password'] = 'redis-password-goes-here'
+
+## Slave redis instance
+redis['master'] = false
+redis['master_ip'] = '10.10.10.10' # IP of master Redis server
+redis['master_port'] = 6379 # Port of master Redis server
+```
+
+Reconfigure GitLab Omnibus for the changes to take effect: `sudo gitlab-ctl reconfigure`
+
+#### Troubleshooting Replication
+
+You can check if everything is correct by connecting to each server using
+`redis-cli` application, and sending the `INFO` command.
+
+If authentication was correctly defined, it should fail with:
+`NOAUTH Authentication required` error. Try to authenticate with the
+previous defined password with `AUTH redis-password-goes-here` and
+try the `INFO` command again.
+
+Look for the `# Replication` section where you should see some important
+information like the `role` of the server.
+
+When connected to a `master` redis, you will see the number of connected
+`slaves`, and a list of each with connection details.
+
+When it's a `slave`, you will see details of the master connection and if
+its `up` or `down`.
 
 ---
 
 Now that the Redis servers are all set up, let's configure the Sentinel
 servers.
 
-### Sentinel setup
+If you are not sure if your Redis servers are working and replicating
+correctly, please read the [Troubleshooting  Replication](#troubleshooting-replication)
+and fix it before proceeding with Sentinel setup.
+
+### Sentinel
+
+You must have at least `3` Redis Sentinel servers, and they need to
+be each in a independent machine. You can install them in the same
+machines you installed the other `3` Redis servers.
+
+This number is required for the consensus algorithm to be effective
+in the case of a failure. You should always have and `odd` number
+of Sentinel nodes provisioned.
 
-We provide an automated way to setup and run the Sentinel daemon
-with GitLab EE.
+Here is a simple explanation on how Sentinel handles a failover:
 
-See the instructions below how to setup it by yourself.
+When a number of Sentinels (`quorum` value) agree the fact the `master` is
+not reachable, the **majority** of the sentinels must elect a temporary
+Sentinel `leader`, that will be responsible to start the failover proceedings.
 
-Here is an example configuration file (`sentinel.conf`) for a Sentinel node:
+As an example, for a cluster of `3` Sentinels, at least `2` must agree on a
+`leader`. If you have total of `5` at least `3` must agree on the leader.
+
+The `quorum` is only used to detect failure, not to elect the `leader`.
+
+Official [Sentinel documentation](http://redis.io/topics/sentinel#example-sentinel-deployments)
+also lists different network topologies and warns againts situations like
+network partition and how it can affect the state of the HA solution. Make
+sure you read it carefully and understand the implications in your current
+setup.
+
+To make Sentinel setup easier, ee provide an [automated way to setup and run](#sentinel-setup-ee-only)
+the Sentinel daemon with GitLab EE.
+
+#### Sentinel setup (Community Edition)
+
+For GitLab CE, you need to install, configure, execute and monitor Sentinel
+by yourself.
+
+Here is an example configuration file (`sentinel.conf`) for a minimal Sentinel
+node:
 
 ```conf
-port 26379
-sentinel monitor gitlab-redis 10.0.0.1 6379 1
+bind 0.0.0.0 # bind to all interfaces or change to a specific IP
+port 26379 # default sentinel port
+sentinel auth-pass gitlab-redis redis-password-goes-here
+sentinel monitor gitlab-redis 10.0.0.1 6379 2
 sentinel down-after-milliseconds gitlab-redis 10000
 sentinel config-epoch gitlab-redis 0
 sentinel leader-epoch gitlab-redis 0
 ```
 
+#### Sentinel setup (EE Only)
+
+To setup sentinel, you must edit `/etc/gitlab/gitlab.rb` file.
+This is a minimal configuration required to run the daemon:
+
+```ruby
+redis['master_name'] = 'gitlab-redis' # must be the same in every sentinel node
+redis['master_ip'] = '10.0.0.1' # ip of the initial master redis instance
+redis['master_port'] = 6379 # port of the initial master redis instance
+redis['master_password'] = 'your-secure-password-here' # the same value defined in redis['password'] in the master instance
+
+sentinel['enable'] = true
+# sentinel['port'] = 26379
+
+## Quorum must reflect the amount of voting sentinels it take to start a failover.
+sentinel['quorum'] = 2
+
+## Consider unresponsive server down after x amount of ms.
+# sentinel['down_after_milliseconds'] = 10000
+
+# sentinel['failover_timeout'] = 60000
+```
+
+When you install Sentinel in a separate machine, you need to control which
+other services will be running in it. Take a look at the following variables
+and enable or disable whenever it fits your strategy:
+
+```ruby
+# Enabled Redis and Sentinel services
+redis['enable'] = true
+sentinel['enable'] = true
+
+# Disabled all other services
+redis['enable'] = false
+bootstrap['enable'] = false
+nginx['enable'] = false
+unicorn['enable'] = false
+sidekiq['enable'] = false
+postgresql['enable'] = false
+gitlab_workhorse['enable'] = false
+gitlab_rails['enable'] = false
+mailroom['enable'] = false
+```
+
+Remember that enabling a new service may also require additional configuration
+params (like `redis` for example).
+
 ---
 
 The final part is to inform the main GitLab application server of the Redis
@@ -243,7 +439,7 @@ or `gitlab-rails['redis_*']` in Omnibus):
 
 ```conf
 # sentinel.conf:
-sentinel monitor gitlab-redis 10.10.10.10 6379 1
+sentinel monitor gitlab-redis 10.10.10.10 6379 2
 sentinel down-after-milliseconds gitlab-redis 10000
 sentinel config-epoch gitlab-redis 0
 sentinel leader-epoch gitlab-redis 0
@@ -276,7 +472,7 @@ To make sure your configuration is correct:
     sudo gitlab-rails console
 
     # For source installations
-    sudo -u git rails console RAILS_ENV=production
+    sudo -u git rails console production
     ```
 
 1. Run in the console:
-- 
cgit v1.2.1


From 0f951737af830163260a9535990a18fba130b443 Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axilleas@axilleas.me>
Date: Wed, 16 Nov 2016 13:56:31 +0100
Subject: Remove experimental heading and move note at the top

[ci skip]
---
 doc/administration/high_availability/redis.md | 15 ++++++---------
 1 file changed, 6 insertions(+), 9 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md
index a87c1dde55d..f9bc4f59345 100644
--- a/doc/administration/high_availability/redis.md
+++ b/doc/administration/high_availability/redis.md
@@ -1,5 +1,11 @@
 # Configuring Redis for GitLab HA
 
+>
+Experimental Redis Sentinel support was [Introduced][ce-1877] in GitLab 8.11.
+Starting with 8.14, Redis Sentinel is no longer experimental.
+If you've used it with versions `< 8.14` before, please check the updated
+documentation here.
+
 High Availability with [Redis] is possible using a **Master** x **Slave**
 topology with a [Redis Sentinel][sentinel] service to watch and automatically
 start the failover procedure.
@@ -52,7 +58,6 @@ Omnibus GitLab packages.
   - [Troubleshooting Redis replication](#troubleshooting-redis-replication)
   - [Troubleshooting Sentinel](#troubleshooting-sentinel)
 - [Changelog](#changelog)
-  - [Experimental Redis Sentinel support](#experimental-redis-sentinel-support)
 - [Further reading](#further-reading)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -871,14 +876,6 @@ Changes to Redis HA over time.
 
 - Experimental Redis Sentinel support was added
 
-### Experimental Redis Sentinel support
-
->
-Experimental Redis Sentinel support was [Introduced][ce-1877] in GitLab 8.11.
-Starting with 8.14, Redis Sentinel is no longer experimental.
-If you used with versions `< 8.14` before, please check the updated
-documentation here.
-
 ## Further reading
 
 Read more on High Availability:
-- 
cgit v1.2.1


From d5dc44f0588690fb79ddc2aa3ee150012d5e4873 Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axilleas@axilleas.me>
Date: Wed, 16 Nov 2016 13:59:52 +0100
Subject: Minor edits in Redis HA source install

[ci skip]
---
 doc/administration/high_availability/redis_source.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/high_availability/redis_source.md b/doc/administration/high_availability/redis_source.md
index e7a8f47355d..8558ba82d63 100644
--- a/doc/administration/high_availability/redis_source.md
+++ b/doc/administration/high_availability/redis_source.md
@@ -345,12 +345,12 @@ We have a more detailed [Troubleshooting](redis.md#troubleshooting) explained
 in the documentation for Omnibus GitLab installations. Here we will list only
 the things that are specific to a source installation.
 
-If you get an error in GitLab like: `Redis::CannotConnectError: No sentinels available.`,
+If you get an error in GitLab like `Redis::CannotConnectError: No sentinels available.`,
 there may be something wrong with your configuration files or it can be related
 to [this upstream issue][gh-531].
 
-It's a bit non-intuitive the way you have to config `resque.yml` and
-`sentinel.conf`, otherwise `redis-rb` will not work properly.
+You must make sure that `resque.yml` and `sentinel.conf` are configured correctly,
+otherwise `redis-rb` will not work properly.
 
 The `master-group-name` ('gitlab-redis') defined in (`sentinel.conf`)
 **must** be used as the hostname in GitLab (`resque.yml`):
@@ -379,7 +379,7 @@ production:
       port: 26379 # point to sentinel, not to redis port
 ```
 
-When in doubt, please read [Redis Sentinel documentation](http://redis.io/topics/sentinel)
+When in doubt, please read [Redis Sentinel documentation](http://redis.io/topics/sentinel).
 
 [gh-531]: https://github.com/redis/redis-rb/issues/531
 [downloads]: https://about.gitlab.com/downloads
-- 
cgit v1.2.1


From 465c61ee6889e03016712cbda7fd48e0e973cb76 Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axilleas@axilleas.me>
Date: Wed, 16 Nov 2016 14:17:58 +0100
Subject: Remove login as root step from Redis HA docs

[ci skip]
---
 doc/administration/high_availability/redis.md | 31 ++++++++-------------------
 1 file changed, 9 insertions(+), 22 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md
index f9bc4f59345..1fa3560e932 100644
--- a/doc/administration/high_availability/redis.md
+++ b/doc/administration/high_availability/redis.md
@@ -107,10 +107,12 @@ to help keep servers online with minimal to no downtime. Redis Sentinel:
 - Promotes a **Slave** to **Master** when the **Master** fails
 - Demotes a **Master** to **Slave** when the failed **Master** comes back online
   (to prevent data-partitioning)
-- Can be queried by clients to always connect to the current **Master** server
+- Can be queried by the application to always connect to the current **Master**
+  server
 
-When a **Master** fails to respond, it's the client's responsibility to handle
-timeout and reconnect (querying a **Sentinel** for a new **Master**).
+When a **Master** fails to respond, it's the application's responsibility
+(in our case GitLab) to handle timeout and reconnect (querying a **Sentinel**
+for a new **Master**).
 
 To get a better understanding on how to correctly setup Sentinel, please read
 the [Redis Sentinel documentation](http://redis.io/topics/sentinel) first, as
@@ -289,12 +291,7 @@ The prerequisites for a HA Redis setup are the following:
 
 ### Step 1. Configuring the master Redis instance
 
-1. SSH into the **master** Redis server and login as root:
-
-    ```
-    sudo -i
-    ```
-
+1. SSH into the **master** Redis server.
 1. [Download/install](https://about.gitlab.com/installation) the Omnibus GitLab
    package you want using **steps 1 and 2** from the GitLab downloads page.
      - Make sure you select the correct Omnibus package, with the same version
@@ -334,12 +331,7 @@ The prerequisites for a HA Redis setup are the following:
 
 ### Step 2. Configuring the slave Redis instances
 
-1. SSH into the **slave** Redis server and login as root:
-
-    ```
-    sudo -i
-    ```
-
+1. SSH into the **slave** Redis server.
 1. [Download/install](https://about.gitlab.com/installation) the Omnibus GitLab
    package you want using **steps 1 and 2** from the GitLab downloads page.
      - Make sure you select the correct Omnibus package, with the same version
@@ -417,12 +409,7 @@ multiple machines with the Sentinel daemon.
 
 ---
 
-1. SSH into the server that will host Redis Sentinel and login as root:
-
-    ```
-    sudo -i
-    ```
-
+1. SSH into the server that will host Redis Sentinel.
 1. **You can omit this step if the Sentinels will be hosted in the same node as
    the other Redis instances.**
 
@@ -437,7 +424,6 @@ multiple machines with the Sentinel daemon.
    Sentinels in the same node as the other Redis instances, some values might
    be duplicate below):
 
-
     ```ruby
     redis_sentinel_role['enable'] = true
 
@@ -530,6 +516,7 @@ it needs to access at least one of the listed.
 The following steps should be performed in the [GitLab application server](gitlab.md)
 which ideally should not have Redis or Sentinels on it for a HA setup.
 
+1. SSH into the server where the GitLab application is installed.
 1. Edit `/etc/gitlab/gitlab.rb` and add/change the following lines:
 
     ```
-- 
cgit v1.2.1


From c61a9b0f1a12972dd3c2ae4e968c11c72ced6756 Mon Sep 17 00:00:00 2001
From: Marin Jankovski <maxlazio@gmail.com>
Date: Wed, 16 Nov 2016 16:24:46 +0100
Subject: Correct the idle_timeout in the docs for installation from source.

---
 doc/administration/reply_by_email.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/reply_by_email.md b/doc/administration/reply_by_email.md
index b42892eef68..14cd7a03826 100644
--- a/doc/administration/reply_by_email.md
+++ b/doc/administration/reply_by_email.md
@@ -197,7 +197,7 @@ To set up a basic Postfix mail server with IMAP access on Ubuntu, follow
       # The mailbox where incoming mail will end up. Usually "inbox".
       mailbox: "inbox"
       # The IDLE command timeout.
-      email_idle_timeout: 60
+      idle_timeout: 60
     ```
 
     ```yaml
@@ -228,7 +228,7 @@ To set up a basic Postfix mail server with IMAP access on Ubuntu, follow
       # The mailbox where incoming mail will end up. Usually "inbox".
       mailbox: "inbox"
       # The IDLE command timeout.
-      email_idle_timeout: 60
+      idle_timeout: 60
     ```
 
 1. Enable `mail_room` in the init script at `/etc/default/gitlab`:
@@ -286,7 +286,7 @@ To set up a basic Postfix mail server with IMAP access on Ubuntu, follow
       # The mailbox where incoming mail will end up. Usually "inbox".
       mailbox: "inbox"
       # The IDLE command timeout.
-      email_idle_timeout: 60
+      idle_timeout: 60
     ```
 
     As mentioned, the part after `+` is ignored, and this will end up in the mailbox for `gitlab-incoming@gmail.com`.
-- 
cgit v1.2.1


From 5fa7169618e2be9956482e2feedaff651f080761 Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axilleas@axilleas.me>
Date: Thu, 17 Nov 2016 13:03:29 +0100
Subject: Remove ToC since it's now supported in the docs portal itself

[ci skip]
---
 doc/administration/high_availability/redis.md      | 32 ----------------------
 .../high_availability/redis_source.md              | 21 --------------
 2 files changed, 53 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md
index 1fa3560e932..f532a106bc6 100644
--- a/doc/administration/high_availability/redis.md
+++ b/doc/administration/high_availability/redis.md
@@ -30,38 +30,6 @@ Omnibus GitLab packages.
   [Available configuration setups](#available-configuration-setups) section
   below.
 
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-**Table of Contents**
-
-- [Overview](#overview)
-  - [High Availability with Sentinel](#high-availability-with-sentinel)
-  - [Recommended setup](#recommended-setup)
-  - [Redis setup overview](#redis-setup-overview)
-  - [Sentinel setup overview](#sentinel-setup-overview)
-  - [Available configuration setups](#available-configuration-setups)
-- [Configuring Redis HA](#configuring-redis-ha)
-  - [Prerequisites](#prerequisites)
-  - [Step 1. Configuring the master Redis instance](#step-1-configuring-the-master-redis-instance)
-  - [Step 2. Configuring the slave Redis instances](#step-2-configuring-the-slave-redis-instances)
-  - [Step 3. Configuring the Redis Sentinel instances](#step-3-configuring-the-redis-sentinel-instances)
-  - [Step 4. Configuring the GitLab application](#step-4-configuring-the-gitlab-application)
-- [Switching from an existing single-machine installation to Redis HA](#switching-from-an-existing-single-machine-installation-to-redis-ha)
-- [Example of a minimal configuration with 1 master, 2 slaves and 3 Sentinels](#example-of-a-minimal-configuration-with-1-master-2-slaves-and-3-sentinels)
-  - [Example configuration for Redis master and Sentinel 1](#example-configuration-for-redis-master-and-sentinel-1)
-  - [Example configuration for Redis slave 1 and Sentinel 2](#example-configuration-for-redis-slave-1-and-sentinel-2)
-  - [Example configuration for Redis slave 2 and Sentinel 3](#example-configuration-for-redis-slave-2-and-sentinel-3)
-  - [Example configuration for the GitLab application](#example-configuration-for-the-gitlab-application)
-- [Advanced configuration](#advanced-configuration)
-  - [Control running services](#control-running-services)
-- [Troubleshooting](#troubleshooting)
-  - [Troubleshooting Redis replication](#troubleshooting-redis-replication)
-  - [Troubleshooting Sentinel](#troubleshooting-sentinel)
-- [Changelog](#changelog)
-- [Further reading](#further-reading)
-
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
-
 ## Overview
 
 Before diving into the details of setting up Redis and Redis Sentinel for HA,
diff --git a/doc/administration/high_availability/redis_source.md b/doc/administration/high_availability/redis_source.md
index 8558ba82d63..3629772b8af 100644
--- a/doc/administration/high_availability/redis_source.md
+++ b/doc/administration/high_availability/redis_source.md
@@ -17,27 +17,6 @@ If you're not sure whether this guide is for you, please refer to
 [Available configuration setups](redis.md#available-configuration-setups) in
 the Omnibus Redis HA documentation.
 
----
-
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-**Table of Contents**
-
-- [Configuring your own Redis server](#configuring-your-own-redis-server)
-  - [Prerequisites](#prerequisites)
-  - [Step 1. Configuring the master Redis instance](#step-1-configuring-the-master-redis-instance)
-  - [Step 2. Configuring the slave Redis instances](#step-2-configuring-the-slave-redis-instances)
-  - [Step 3. Configuring the Redis Sentinel instances](#step-3-configuring-the-redis-sentinel-instances)
-  - [Step 4. Configuring the GitLab application](#step-4-configuring-the-gitlab-application)
-- [Example of minimal configuration with 1 master, 2 slaves and 3 Sentinels](#example-of-minimal-configuration-with-1-master-2-slaves-and-3-sentinels)
-  - [Example configuration for Redis master and Sentinel 1](#example-configuration-for-redis-master-and-sentinel-1)
-  - [Example configuration for Redis slave 1 and Sentinel 2](#example-configuration-for-redis-slave-1-and-sentinel-2)
-  - [Example configuration for Redis slave 2 and Sentinel 3](#example-configuration-for-redis-slave-2-and-sentinel-3)
-  - [Example configuration of the GitLab application](#example-configuration-of-the-gitlab-application)
-- [Troubleshooting](#troubleshooting)
-
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
-
 ## Configuring your own Redis server
 
 This is the section where we install and setup the new Redis instances.
-- 
cgit v1.2.1


From af1dabe805fa7ad6fcdccfdb792b07e00c3c42d2 Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axilleas@axilleas.me>
Date: Tue, 22 Nov 2016 19:53:43 +0100
Subject: Reduce size of images from 25MB to 13MB using pngquant

Took it from https://gitlab.com/gitlab-com/www-gitlab-com/merge_requests/3232

[ci skip]
---
 doc/administration/img/custom_hooks_error_msg.png  | Bin 159486 -> 44922 bytes
 .../high_availability/active-active-diagram.png    | Bin 29607 -> 14649 bytes
 .../high_availability/active-passive-diagram.png   | Bin 24246 -> 11699 bytes
 doc/administration/img/housekeeping_settings.png   | Bin 27420 -> 12025 bytes
 .../img/raketasks/check_repos_output.png           | Bin 35333 -> 19153 bytes
 .../img/repository_storages_admin_ui.png           | Bin 54043 -> 17760 bytes
 .../performance/img/grafana_dashboard_dropdown.png | Bin 14368 -> 7761 bytes
 .../performance/img/grafana_dashboard_import.png   | Bin 18267 -> 11836 bytes
 .../img/grafana_data_source_configuration.png      | Bin 26060 -> 14700 bytes
 .../performance/img/grafana_data_source_empty.png  | Bin 21821 -> 11963 bytes
 .../performance/img/grafana_save_icon.png          | Bin 9107 -> 4619 bytes
 .../img/metrics_gitlab_configuration_settings.png  | Bin 61357 -> 26169 bytes
 .../performance/img/request_profile_result.png     | Bin 9720 -> 3236 bytes
 .../performance/img/request_profiling_token.png    | Bin 30076 -> 10229 bytes
 .../operations/img/sidekiq_job_throttling.png      | Bin 114784 -> 32229 bytes
 15 files changed, 0 insertions(+), 0 deletions(-)

(limited to 'doc/administration')

diff --git a/doc/administration/img/custom_hooks_error_msg.png b/doc/administration/img/custom_hooks_error_msg.png
index 92e87e15fb3..1b3277bef16 100644
Binary files a/doc/administration/img/custom_hooks_error_msg.png and b/doc/administration/img/custom_hooks_error_msg.png differ
diff --git a/doc/administration/img/high_availability/active-active-diagram.png b/doc/administration/img/high_availability/active-active-diagram.png
index 81259e0ae93..4f5984b88fe 100644
Binary files a/doc/administration/img/high_availability/active-active-diagram.png and b/doc/administration/img/high_availability/active-active-diagram.png differ
diff --git a/doc/administration/img/high_availability/active-passive-diagram.png b/doc/administration/img/high_availability/active-passive-diagram.png
index f69ff1d0357..3b42ce5911c 100644
Binary files a/doc/administration/img/high_availability/active-passive-diagram.png and b/doc/administration/img/high_availability/active-passive-diagram.png differ
diff --git a/doc/administration/img/housekeeping_settings.png b/doc/administration/img/housekeeping_settings.png
index 6ebc6205635..acc4506993a 100644
Binary files a/doc/administration/img/housekeeping_settings.png and b/doc/administration/img/housekeeping_settings.png differ
diff --git a/doc/administration/img/raketasks/check_repos_output.png b/doc/administration/img/raketasks/check_repos_output.png
index 1f632566b00..7fda2ba0c0f 100644
Binary files a/doc/administration/img/raketasks/check_repos_output.png and b/doc/administration/img/raketasks/check_repos_output.png differ
diff --git a/doc/administration/img/repository_storages_admin_ui.png b/doc/administration/img/repository_storages_admin_ui.png
index 6481baca1ad..3e76c5b282c 100644
Binary files a/doc/administration/img/repository_storages_admin_ui.png and b/doc/administration/img/repository_storages_admin_ui.png differ
diff --git a/doc/administration/monitoring/performance/img/grafana_dashboard_dropdown.png b/doc/administration/monitoring/performance/img/grafana_dashboard_dropdown.png
index 7e34fad71ce..51eef90068d 100644
Binary files a/doc/administration/monitoring/performance/img/grafana_dashboard_dropdown.png and b/doc/administration/monitoring/performance/img/grafana_dashboard_dropdown.png differ
diff --git a/doc/administration/monitoring/performance/img/grafana_dashboard_import.png b/doc/administration/monitoring/performance/img/grafana_dashboard_import.png
index f97624365c7..7761ea00522 100644
Binary files a/doc/administration/monitoring/performance/img/grafana_dashboard_import.png and b/doc/administration/monitoring/performance/img/grafana_dashboard_import.png differ
diff --git a/doc/administration/monitoring/performance/img/grafana_data_source_configuration.png b/doc/administration/monitoring/performance/img/grafana_data_source_configuration.png
index 7d50e4c88c2..3e749eb8f9d 100644
Binary files a/doc/administration/monitoring/performance/img/grafana_data_source_configuration.png and b/doc/administration/monitoring/performance/img/grafana_data_source_configuration.png differ
diff --git a/doc/administration/monitoring/performance/img/grafana_data_source_empty.png b/doc/administration/monitoring/performance/img/grafana_data_source_empty.png
index aa39a53acae..33fcaaaef64 100644
Binary files a/doc/administration/monitoring/performance/img/grafana_data_source_empty.png and b/doc/administration/monitoring/performance/img/grafana_data_source_empty.png differ
diff --git a/doc/administration/monitoring/performance/img/grafana_save_icon.png b/doc/administration/monitoring/performance/img/grafana_save_icon.png
index c740e33cd1c..c18f2147e9d 100644
Binary files a/doc/administration/monitoring/performance/img/grafana_save_icon.png and b/doc/administration/monitoring/performance/img/grafana_save_icon.png differ
diff --git a/doc/administration/monitoring/performance/img/metrics_gitlab_configuration_settings.png b/doc/administration/monitoring/performance/img/metrics_gitlab_configuration_settings.png
index db396423e30..13bfd097b81 100644
Binary files a/doc/administration/monitoring/performance/img/metrics_gitlab_configuration_settings.png and b/doc/administration/monitoring/performance/img/metrics_gitlab_configuration_settings.png differ
diff --git a/doc/administration/monitoring/performance/img/request_profile_result.png b/doc/administration/monitoring/performance/img/request_profile_result.png
index 73e2fdcab67..8ebd74c2d3c 100644
Binary files a/doc/administration/monitoring/performance/img/request_profile_result.png and b/doc/administration/monitoring/performance/img/request_profile_result.png differ
diff --git a/doc/administration/monitoring/performance/img/request_profiling_token.png b/doc/administration/monitoring/performance/img/request_profiling_token.png
index 04d87567816..9160407e028 100644
Binary files a/doc/administration/monitoring/performance/img/request_profiling_token.png and b/doc/administration/monitoring/performance/img/request_profiling_token.png differ
diff --git a/doc/administration/operations/img/sidekiq_job_throttling.png b/doc/administration/operations/img/sidekiq_job_throttling.png
index 7f29a4d3c46..dcf40b4bf17 100644
Binary files a/doc/administration/operations/img/sidekiq_job_throttling.png and b/doc/administration/operations/img/sidekiq_job_throttling.png differ
-- 
cgit v1.2.1