# HG changeset patch
# User Balasankar "Balu" C <balasankar@gitlab.com>
# Date 1547462473 -19800
#      Mon Jan 14 16:11:13 2019 +0530
# Node ID f66aa228f9f90b00224ffcefe356d6e70e5be970
# Parent  08f59a44599d45336063a9f6fb6ddeee4a27a190
Add documentation on service specific NGINX settings

diff --git a/doc/settings/nginx.md b/doc/settings/nginx.md
--- a/doc/settings/nginx.md
+++ b/doc/settings/nginx.md
@@ -1,5 +1,30 @@
 # NGINX settings
 
+## Service-specific NGINX settings
+
+Users can configure NGINX settings differently for different services via
+gitlab.rb. Settings for the GitLab rails application can be configured using the
+`nginx['<some setting>']` keys. There are similar keys for other services like
+`pages_nginx`, `mattermost_nginx` and `registry_nginx`. All the configurations
+available for `nginx` are also available for these `<service_nginx>` settings and
+share the same default values as GitLab NGINX.
+
+If modifying via gitlab.rb, users have to configure nginx setting for each
+service separately. Settings given via `nginx['foo']` WILL NOT be replicated to
+service specific nginx configuration (as `registry_nginx['foo']` or
+`mattermost_nginx['foo']`, etc.). For example, to configure HTTP to HTTPS
+redirection for GitLab, Mattermost and Registry, the following settings should
+be added to `gitlab.rb`
+
+```ruby
+nginx['redirect_http_to_https'] = true
+registry_nginx['redirect_http_to_https'] = true
+mattermost_nginx['redirect_http_to_https'] = true
+```
+
+**`Note`**: Modifying NGINX configuration should be done with care as incorrect
+or incompatible configuration may yield to unavailability of service.
+
 ## Enable HTTPS
 
 By default, omnibus-gitlab does not use HTTPS. If you want to enable HTTPS for
diff --git a/files/gitlab-config-template/gitlab.rb.template b/files/gitlab-config-template/gitlab.rb.template
--- a/files/gitlab-config-template/gitlab.rb.template
+++ b/files/gitlab-config-template/gitlab.rb.template
@@ -1214,8 +1214,11 @@
 ## GitLab Pages NGINX
 ################################################################################
 
-# All the settings defined in the "GitLab Nginx" section are also available in this "GitLab Pages NGINX" section
-# You just have to change the key "nginx['some_settings']" with "pages_nginx['some_settings']"
+# All the settings defined in the "GitLab Nginx" section are also available in
+# this "GitLab Pages NGINX" section, using the key `pages_nginx`.  However,
+# those settings should be explicitly set. That is, settings given as
+# `nginx['some_setting']` WILL NOT be automatically replicated as
+# `pages_nginx['some_setting']` and should be set separately.
 
 # Below you can find settings that are exclusive to "GitLab Pages NGINX"
 # pages_nginx['enable'] = false
@@ -1272,8 +1275,11 @@
 ## Mattermost NGINX
 ################################################################################
 
-# All the settings defined in the "GitLab NGINX" section are also available in this "Mattermost NGINX" section
-# You just have to change the key "nginx['some_settings']" with "mattermost_nginx['some_settings']"
+# All the settings defined in the "GitLab Nginx" section are also available in
+# this "Mattermost NGINX" section, using the key `mattermost_nginx`.  However,
+# those settings should be explicitly set. That is, settings given as
+# `nginx['some_setting']` WILL NOT be automatically replicated as
+# `mattermost_nginx['some_setting']` and should be set separately.
 
 # Below you can find settings that are exclusive to "Mattermost NGINX"
 # mattermost_nginx['enable'] = false
@@ -1295,8 +1301,11 @@
 ## Registry NGINX
 ################################################################################
 
-# All the settings defined in the "GitLab NGINX" section are also available in this "Registry NGINX" section
-# You just have to change the key "nginx['some_settings']" with "registry_nginx['some_settings']"
+# All the settings defined in the "GitLab Nginx" section are also available in
+# this "Registry NGINX" section, using the key `registry_nginx`.  However, those
+# settings should be explicitly set. That is, settings given as
+# `nginx['some_setting']` WILL NOT be automatically replicated as
+# `registry_nginx['some_setting']` and should be set separately.
 
 # Below you can find settings that are exclusive to "Registry NGINX"
 # registry_nginx['enable'] = false