Merge branch 'docs-codyw-update-incoming-email' into 'master'

Docs - Reorganize incoming email doc

See merge request gitlab-org/gitlab-ce!25409

doc/administration/incoming_email.md

@@ -95,133 +95,97 @@ for a real-world example of this exploit.
 
 ### 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:
+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 (see [examples](#config-examples) below).
 
-    Configuration for Postfix mail server, assumes mailbox
-    incoming@gitlab.example.com
-
-    ```ruby
-    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
+1. Reconfigure GitLab for the changes to take effect:
 
-    # 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
+    ```sh
+    sudo gitlab-ctl reconfigure
+    sudo gitlab-ctl restart
     ```
 
-    Configuration for Gmail / Google Apps, assumes mailbox
-    gitlab-incoming@gmail.com
+1. Verify that everything is configured correctly:
 
-    ```ruby
-    gitlab_rails['incoming_email_enabled'] = true
+    ```sh
+    sudo gitlab-rake gitlab:incoming_email:check
+    ```
 
-    # 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"
+Reply by email should now be working.
 
-    # 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]"
+### Installations from source
 
-    # 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
+1. Go to the GitLab installation directory:
 
-    # 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
+    ```sh
+    cd /home/git/gitlab
     ```
 
-    Configuration for Microsoft Exchange mail server w/ IMAP enabled, assumes the
-    catch-all mailbox incoming@exchange.example.com
-
-    ```ruby
-    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 `@`).
-    # Exchange does not support sub-addressing, so a catch-all mailbox must be used.
-    gitlab_rails['incoming_email_address'] = "incoming-%{key}@exchange.example.com"
+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 (see [examples](#config-examples) below).
 
-    # Email account username
-    # Typically this is the userPrincipalName (UPN)
-    gitlab_rails['incoming_email_email'] = "incoming@ad-domain.example.com"
-    # Email account password
-    gitlab_rails['incoming_email_password'] = "[REDACTED]"
+1. Enable `mail_room` in the init script at `/etc/default/gitlab`:
 
-    # IMAP server host
-    gitlab_rails['incoming_email_host'] = "exchange.example.com"
-    # IMAP server port
-    gitlab_rails['incoming_email_port'] = 993
-    # Whether the IMAP server uses SSL
-    gitlab_rails['incoming_email_ssl'] = true
+    ```sh
+    sudo mkdir -p /etc/default
+    echo 'mail_room_enabled=true' | sudo tee -a /etc/default/gitlab
     ```
 
-1. Reconfigure GitLab for the changes to take effect:
+1. Restart GitLab:
 
     ```sh
-    sudo gitlab-ctl reconfigure
-    sudo gitlab-ctl restart
+    sudo service gitlab restart
     ```
 
 1. Verify that everything is configured correctly:
 
     ```sh
-    sudo gitlab-rake gitlab:incoming_email:check
+    sudo -u git -H bundle exec rake gitlab:incoming_email:check RAILS_ENV=production
     ```
 
-1. Reply by email should now be working.
+Reply by email should now be working.
 
-### Installations from source
+### Config examples
 
-1. Go to the GitLab installation directory:
+#### Postfix
 
-    ```sh
-    cd /home/git/gitlab
-    ```
+Example configuration for Postfix mail server. Assumes mailbox incoming@gitlab.example.com.
 
-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:
+Example for Omnibus installs:
 
-    ```sh
-    sudo editor config/gitlab.yml
-    ```
+```ruby
+gitlab_rails['incoming_email_enabled'] = true
 
-    Configuration for Postfix mail server, assumes mailbox
-    incoming@gitlab.example.com
+# 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"
 
-    ```yaml
-    incoming_email:
+# 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"
+# The IDLE command timeout.
+gitlab_rails['incoming_email_idle_timeout'] = 60
+```
+
+Example for source installs:
+
+```yaml
+incoming_email:
     enabled: true
 
     # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
@@ -248,13 +212,47 @@ for a real-world example of this exploit.
     mailbox: "inbox"
     # The IDLE command timeout.
     idle_timeout: 60
-    ```
+```
+
+#### Gmail
+
+Example configuration for Gmail/G Suite. Assumes mailbox gitlab-incoming@gmail.com.
 
-    Configuration for Gmail / Google Apps, assumes mailbox
-    gitlab-incoming@gmail.com
+Example for Omnibus installs:
 
-    ```yaml
-    incoming_email:
+```ruby
+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"
+# The IDLE command timeout.
+gitlab_rails['incoming_email_idle_timeout'] = 60
+```
+
+Example for source installs:
+
+```yaml
+incoming_email:
     enabled: true
 
     # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
@@ -281,13 +279,41 @@ for a real-world example of this exploit.
     mailbox: "inbox"
     # The IDLE command timeout.
     idle_timeout: 60
-    ```
+```
 
-    Configuration for Microsoft Exchange mail server w/ IMAP enabled, assumes the
-    catch-all mailbox incoming@exchange.example.com
+#### MS Exchange
 
-    ```yaml
-    incoming_email:
+Example configuration for Microsoft Exchange mail server with IMAP enabled. Assumes the
+catch-all mailbox incoming@exchange.example.com.
+
+Example for Omnibus installs:
+
+```ruby
+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 `@`).
+# Exchange does not support sub-addressing, so a catch-all mailbox must be used.
+gitlab_rails['incoming_email_address'] = "incoming-%{key}@exchange.example.com"
+
+# Email account username
+# Typically this is the userPrincipalName (UPN)
+gitlab_rails['incoming_email_email'] = "incoming@ad-domain.example.com"
+# Email account password
+gitlab_rails['incoming_email_password'] = "[REDACTED]"
+
+# IMAP server host
+gitlab_rails['incoming_email_host'] = "exchange.example.com"
+# IMAP server port
+gitlab_rails['incoming_email_port'] = 993
+# Whether the IMAP server uses SSL
+gitlab_rails['incoming_email_ssl'] = true
+```
+
+Example for source installs:
+
+```yaml
+incoming_email:
     enabled: true
 
     # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
@@ -314,25 +340,4 @@ for a real-world example of this exploit.
     mailbox: "inbox"
     # The IDLE command timeout.
     idle_timeout: 60
-    ```
-
-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.
+```