diff --git a/README.md b/README.md
index ac98eb1aedc338a11248dd9814f7f0bef04aea85_UkVBRE1FLm1k..4f132b62117b5755fb78c572d87284b02c1546b0_UkVBRE1FLm1k 100644
--- a/README.md
+++ b/README.md
@@ -29,10 +29,85 @@
 
 ## Configuration options
 
-GitLab and GitLab CI are configured by setting their relevant options in
-`/etc/gitlab/gitlab.rb`. For a complete list of available options, visit the
-[gitlab.rb.template][]. New installations starting from GitLab 7.6, will have
-all the options of the template listed in `/etc/gitlab/gitlab.rb` by default.
+See [doc/settings/configuration.md](doc/settings/configuration.md).
+
+##### Configuring the external URL for GitLab
+
+See [doc/settings/configuration.md](doc/settings/configuration.md#configuring-the-external-url-for-gitlab).
+
+##### Storing Git data in an alternative directory
+
+See [doc/settings/configuration.md](doc/settings/configuration.md#storing-git-data-in-an-alternative-directory).
+
+##### Changing the name of the Git user / group
+
+See [doc/settings/configuration.md](doc/settings/configuration.md#changing-the-name-of-the-git-user-group).
+
+##### Setting up LDAP sign-in
+
+See [doc/settings/ldap.md](doc/settings/ldap.md).
+
+##### Enable HTTPS
+
+See [doc/settings/nginx.md](doc/settings/nginx.md#enable-https).
+
+##### Redirect `HTTP` requests to `HTTPS`.
+
+See [doc/settings/nginx.md](doc/settings/nginx.md#redirect-http-requests-to-https).
+
+##### Change the default port and the ssl certificate locations.
+
+See [doc/settings/nginx.md](doc/settings/nginx.md#change-the-default-port-and-the-ssl-certificate-locations).
+
+##### Use non-packaged web-server
+
+For using an existing Nginx, Passenger, or Apache webserver see [doc/settings/nginx.md](doc/settings/nginx.md#using-a-non-bundled-web-server).
+
+##### Using a non-packaged PostgreSQL database management server
+
+To connect to an external PostgreSQL or MySQL DBMS see [doc/settings/database.md](doc/settings/database.md) (MySQL support in the Omnibus Packages is Enterprise Only).
+
+##### Using a non-packaged Redis instance
+
+See [doc/settings/redis.md](doc/settings/redis.md).
+
+##### Adding ENV Vars to the Gitlab Runtime Environment
+
+See
+[doc/settings/environment-variables.md](doc/settings/environment-variables.md).
+
+##### Changing gitlab.yml settings
+
+See [doc/settings/gitlab.yml.md](doc/settings/gitlab.yml.md).
+
+##### Specify numeric user and group identifiers
+
+See [doc/settings/configuration.md](doc/settings/configuration.md#specify-numeric-user-and-group-identifiers).
+
+##### Sending application email via SMTP
+
+See [doc/settings/smtp.md](doc/settings/smtp.md).
+
+##### Omniauth (Google, Twitter, GitHub login)
+
+Omniauth configuration is documented in
+[doc.gitlab.com](http://doc.gitlab.com/ce/integration/omniauth.html).
+
+##### Adjusting Unicorn settings
+
+See [doc/settings/unicorn.md](doc/settings/unicorn.md).
+
+##### Setting the NGINX listen address or addresses
+
+See [doc/settings/nginx.md](doc/settings/nginx.md).
+
+##### Inserting custom NGINX settings into the GitLab server block
+
+See [doc/settings/nginx.md](doc/settings/nginx.md).
+
+##### Inserting custom settings into the NGINX config
+
+See [doc/settings/nginx.md](doc/settings/nginx.md).
 
 ## Installation
 
@@ -60,6 +135,69 @@
 Your GitLab instance should reachable over HTTP at the IP or hostname of your server.
 You can login as an admin user with username `root` and password `5iveL!fe`.
 
+#### Starting and stopping
+
+After omnibus-gitlab is installed and configured, your server will have a Runit
+service directory (`runsvdir`) process running that gets started at boot via
+`/etc/inittab` or the `/etc/init/gitlab-runsvdir.conf` Upstart resource.  You
+should not have to deal with the `runsvdir` process directly; you can use the
+`gitlab-ctl` front-end instead.
+
+You can start, stop or restart GitLab and all of its components with the
+following commands.
+
+```shell
+# Start all GitLab components
+sudo gitlab-ctl start
+
+# Stop all GitLab components
+sudo gitlab-ctl stop
+
+# Restart all GitLab components
+sudo gitlab-ctl restart
+```
+
+Note that on a single-core server it may take up to a minute to restart Unicorn
+and Sidekiq. Your GitLab instance will give a 502 error until Unicorn is up
+again.
+
+It is also possible to start, stop or restart individual components.
+
+```shell
+sudo gitlab-ctl restart sidekiq
+```
+
+Unicorn supports zero-downtime reloads. These can be triggered as follows:
+
+```shell
+sudo gitlab-ctl hup unicorn
+```
+
+Note that you cannot use a Unicorn reload to update the Ruby runtime.
+
+### Updating
+
+Instructions for updating your Omnibus installation and upgrading from a manual installation are in the [update doc](doc/update.md).
+
+### Uninstalling omnibus-gitlab
+
+To uninstall omnibus-gitlab, preserving your data (repositories, database, configuration), run the following commands.
+
+```
+# Stop gitlab and remove its supervision process
+sudo gitlab-ctl uninstall
+
+# Debian/Ubuntu
+sudo dpkg -r gitlab
+
+# Redhat/Centos
+sudo rpm -e gitlab
+```
+
+To remove all omnibus-gitlab data use `sudo gitlab-ctl cleanse`.
+
+To remove all users and groups created by omnibus-gitlab, before removing the gitlab package (with dpkg or yum) run `sudo gitlab-ctl remove_users`. *Note* All gitlab processes need to be stopped before runnign the command.
+
 ### Common installation problems
 
 This section has been moved to the separate document [doc/common_installation_problems.md](doc/common_installation_problems.md).
@@ -123,68 +261,6 @@
 
 See [doc/common_installation_problems.md](doc/common_installation_problems.mdr#short-read-or-oom-loading-db-error).
 
-### Uninstalling omnibus-gitlab
-
-To uninstall omnibus-gitlab, preserving your data (repositories, database, configuration), run the following commands.
-
-```
-# Stop gitlab and remove its supervision process
-sudo gitlab-ctl uninstall
-
-# Debian/Ubuntu
-sudo dpkg -r gitlab
-
-# Redhat/Centos
-sudo rpm -e gitlab
-```
-
-To remove all omnibus-gitlab data use `sudo gitlab-ctl cleanse`.
-
-To remove all users and groups created by omnibus-gitlab, before removing the gitlab package (with dpkg or yum) run `sudo gitlab-ctl remove_users`. *Note* All gitlab processes need to be stopped before runnign the command.
-
-## Updating
-
-Instructions for updating your Omnibus installation and upgrading from a manual installation are in the [update doc](doc/update.md).
-
-## Starting and stopping
-
-After omnibus-gitlab is installed and configured, your server will have a Runit
-service directory (`runsvdir`) process running that gets started at boot via
-`/etc/inittab` or the `/etc/init/gitlab-runsvdir.conf` Upstart resource.  You
-should not have to deal with the `runsvdir` process directly; you can use the
-`gitlab-ctl` front-end instead.
-
-You can start, stop or restart GitLab and all of its components with the
-following commands.
-
-```shell
-# Start all GitLab components
-sudo gitlab-ctl start
-
-# Stop all GitLab components
-sudo gitlab-ctl stop
-
-# Restart all GitLab components
-sudo gitlab-ctl restart
-```
-
-Note that on a single-core server it may take up to a minute to restart Unicorn
-and Sidekiq. Your GitLab instance will give a 502 error until Unicorn is up
-again.
-
-It is also possible to start, stop or restart individual components.
-
-```shell
-sudo gitlab-ctl restart sidekiq
-```
-
-Unicorn supports zero-downtime reloads. These can be triggered as follows:
-
-```shell
-sudo gitlab-ctl hup unicorn
-```
-
-Note that you cannot use a Unicorn reload to update the Ruby runtime.
 
 ## Configuration
 
@@ -214,5 +290,4 @@
 
 NOTE: Your machines SSH host keys are stored in a separate location at `/etc/ssh/`. Be sure to also [backup and restore those keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079) to avoid man-in-the-middle attack warnings if you have to perform a full machine restore.
 
-### Configuring the external URL for GitLab
 
@@ -218,150 +293,4 @@
 
-In order for GitLab to display correct repository clone links to your users
-it needs to know the URL under which it is reached by your users, e.g.
-`http://gitlab.example.com`. Add or edit the following line in
-`/etc/gitlab/gitlab.rb`:
-
-```ruby
-external_url "http://gitlab.example.com"
-```
-
-Run `sudo gitlab-ctl reconfigure` for the change to take effect.
-
-
-### Storing Git data in an alternative directory
-
-By default, omnibus-gitlab stores Git repository data under
-`/var/opt/gitlab/git-data`: repositories are stored in
-`/var/opt/gitlab/git-data/repositories`, and satellites in
-`/var/opt/gitlab/git-data/gitlab-satellites`.  You can change the location of
-the `git-data` parent directory by adding the following line to
-`/etc/gitlab/gitlab.rb`.
-
-```ruby
-git_data_dir "/mnt/nas/git-data"
-```
-
-Note that the target directory and any of its subpaths must not be a symlink.
-
-Run `sudo gitlab-ctl reconfigure` for the change to take effect.
-
-If you already have existing Git repositories in `/var/opt/gitlab/git-data` you
-can move them to the new location as follows:
-
-```shell
-# Prevent users from writing to the repositories while you move them.
-sudo gitlab-ctl stop
-
-# Only move 'repositories'; 'gitlab-satellites' will be recreated
-# automatically. Note there is _no_ slash behind 'repositories', but there _is_ a
-# slash behind 'git-data'.
-sudo rsync -av /var/opt/gitlab/git-data/repositories /mnt/nas/git-data/
-
-# Fix permissions if necessary
-sudo gitlab-ctl reconfigure
-
-# Double-check directory layout in /mnt/nas/git-data. Expected output:
-# gitlab-satellites  repositories
-sudo ls /mnt/nas/git-data/
-
-# Done! Start GitLab and verify that you can browse through the repositories in
-# the web interface.
-sudo gitlab-ctl start
-```
-
-### Changing the name of the Git user / group
-
-By default, omnibus-gitlab uses the user name `git` for Git gitlab-shell login,
-ownership of the Git data itself, and SSH URL generation on the web interface.
-Similarly, `git` group is used for group ownership of the Git data.  You can
-change the user and group by adding the following lines to
-`/etc/gitlab/gitlab.rb`.
-
-```ruby
-user['username'] = "gitlab"
-user['group'] = "gitlab"
-```
-
-Run `sudo gitlab-ctl reconfigure` for the change to take effect.
-
-### Setting up LDAP sign-in
-
-See [doc/settings/ldap.md](doc/settings/ldap.md).
-
-### Enable HTTPS
-
-See [doc/settings/nginx.md](doc/settings/nginx.md#enable-https).
-
-#### Redirect `HTTP` requests to `HTTPS`.
-
-See [doc/settings/nginx.md](doc/settings/nginx.md#redirect-http-requests-to-https).
-
-#### Change the default port and the ssl certificate locations.
-
-See [doc/settings/nginx.md](doc/settings/nginx.md#change-the-default-port-and-the-ssl-certificate-locations).
-
-### Use non-packaged web-server
-
-For using an existing Nginx, Passenger, or Apache webserver see [doc/settings/nginx.md](doc/settings/nginx.md#using-a-non-bundled-web-server).
-
-## Using a non-packaged PostgreSQL database management server
-
-To connect to an external PostgreSQL or MySQL DBMS see [doc/settings/database.md](doc/settings/database.md) (MySQL support in the Omnibus Packages is Enterprise Only).
-
-## Using a non-packaged Redis instance
-
-See [doc/settings/redis.md](doc/settings/redis.md).
-
-### Adding ENV Vars to the Gitlab Runtime Environment
-
-See
-[doc/settings/environment-variables.md](doc/settings/environment-variables.md).
-
-### Changing gitlab.yml settings
-
-See [doc/settings/gitlab.yml.md](doc/settings/gitlab.yml.md).
-
-### Specify numeric user and group identifiers
-
-Omnibus-gitlab creates users for GitLab, PostgreSQL, Redis and NGINX. You can
-specify the numeric identifiers for these users in `/etc/gitlab/gitlab.rb` as
-follows.
-
-```ruby
-user['uid'] = 1234
-user['gid'] = 1234
-postgresql['uid'] = 1235
-postgresql['gid'] = 1235
-redis['uid'] = 1236
-redis['gid'] = 1236
-web_server['uid'] = 1237
-web_server['gid'] = 1237
-```
-
-### Sending application email via SMTP
-
-See [doc/settings/smtp.md](doc/settings/smtp.md).
-
-### Omniauth (Google, Twitter, GitHub login)
-
-Omniauth configuration is documented in
-[doc.gitlab.com](http://doc.gitlab.com/ce/integration/omniauth.html).
-
-### Adjusting Unicorn settings
-
-See [doc/settings/unicorn.md](doc/settings/unicorn.md).
-
-### Setting the NGINX listen address or addresses
-
-See [doc/settings/nginx.md](doc/settings/nginx.md).
-
-### Inserting custom NGINX settings into the GitLab server block
-
-See [doc/settings/nginx.md](doc/settings/nginx.md).
-
-### Inserting custom settings into the NGINX config
-
-See [doc/settings/nginx.md](doc/settings/nginx.md).
 
 ## Backups
 
diff --git a/doc/README.md b/doc/README.md
index ac98eb1aedc338a11248dd9814f7f0bef04aea85_ZG9jL1JFQURNRS5tZA==..4f132b62117b5755fb78c572d87284b02c1546b0_ZG9jL1JFQURNRS5tZA== 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -19,7 +19,7 @@
 
 ## Configuring
 
-- [Configuration options](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-config-template/gitlab.rb.template)
+- [Configuration options](settings/configuration.md)
 - [SMTP](settings/smtp.md)
 - [NGINX](settings/nginx.md)
 - [LDAP](settings/ldap.md)
diff --git a/doc/settings/README.md b/doc/settings/README.md
index ac98eb1aedc338a11248dd9814f7f0bef04aea85_ZG9jL3NldHRpbmdzL1JFQURNRS5tZA==..4f132b62117b5755fb78c572d87284b02c1546b0_ZG9jL3NldHRpbmdzL1JFQURNRS5tZA== 100644
--- a/doc/settings/README.md
+++ b/doc/settings/README.md
@@ -1,5 +1,6 @@
 # Configuring omnibus settings
 
+- [Configuration options](configuration.md)
 - [SMTP](smtp.md)
 - [NGINX](nginx.md)
 - [LDAP](ldap.md)
diff --git a/doc/settings/configuration.md b/doc/settings/configuration.md
new file mode 100644
index 0000000000000000000000000000000000000000..4f132b62117b5755fb78c572d87284b02c1546b0_ZG9jL3NldHRpbmdzL2NvbmZpZ3VyYXRpb24ubWQ=
--- /dev/null
+++ b/doc/settings/configuration.md
@@ -0,0 +1,155 @@
+# Configuration options
+
+GitLab and GitLab CI are configured by setting their relevant options in
+`/etc/gitlab/gitlab.rb`. For a complete list of available options, visit the
+[gitlab.rb.template][]. New installations starting from GitLab 7.6, will have
+all the options of the template listed in `/etc/gitlab/gitlab.rb` by default.
+
+
+### Configuring the external URL for GitLab
+
+In order for GitLab to display correct repository clone links to your users
+it needs to know the URL under which it is reached by your users, e.g.
+`http://gitlab.example.com`. Add or edit the following line in
+`/etc/gitlab/gitlab.rb`:
+
+```ruby
+external_url "http://gitlab.example.com"
+```
+
+Run `sudo gitlab-ctl reconfigure` for the change to take effect.
+
+### Storing Git data in an alternative directory
+
+By default, omnibus-gitlab stores Git repository data under
+`/var/opt/gitlab/git-data`: repositories are stored in
+`/var/opt/gitlab/git-data/repositories`, and satellites in
+`/var/opt/gitlab/git-data/gitlab-satellites`.  You can change the location of
+the `git-data` parent directory by adding the following line to
+`/etc/gitlab/gitlab.rb`.
+
+```ruby
+git_data_dir "/mnt/nas/git-data"
+```
+
+Note that the target directory and any of its subpaths must not be a symlink.
+
+Run `sudo gitlab-ctl reconfigure` for the change to take effect.
+
+If you already have existing Git repositories in `/var/opt/gitlab/git-data` you
+can move them to the new location as follows:
+
+```shell
+# Prevent users from writing to the repositories while you move them.
+sudo gitlab-ctl stop
+
+# Only move 'repositories'; 'gitlab-satellites' will be recreated
+# automatically. Note there is _no_ slash behind 'repositories', but there _is_ a
+# slash behind 'git-data'.
+sudo rsync -av /var/opt/gitlab/git-data/repositories /mnt/nas/git-data/
+
+# Fix permissions if necessary
+sudo gitlab-ctl reconfigure
+
+# Double-check directory layout in /mnt/nas/git-data. Expected output:
+# gitlab-satellites  repositories
+sudo ls /mnt/nas/git-data/
+
+# Done! Start GitLab and verify that you can browse through the repositories in
+# the web interface.
+sudo gitlab-ctl start
+```
+
+### Changing the name of the Git user / group
+
+By default, omnibus-gitlab uses the user name `git` for Git gitlab-shell login,
+ownership of the Git data itself, and SSH URL generation on the web interface.
+Similarly, `git` group is used for group ownership of the Git data.  You can
+change the user and group by adding the following lines to
+`/etc/gitlab/gitlab.rb`.
+
+```ruby
+user['username'] = "gitlab"
+user['group'] = "gitlab"
+```
+
+Run `sudo gitlab-ctl reconfigure` for the change to take effect.
+
+### Setting up LDAP sign-in
+
+See [doc/settings/ldap.md](doc/settings/ldap.md).
+
+### Enable HTTPS
+
+See [doc/settings/nginx.md](doc/settings/nginx.md#enable-https).
+
+#### Redirect `HTTP` requests to `HTTPS`.
+
+See [doc/settings/nginx.md](doc/settings/nginx.md#redirect-http-requests-to-https).
+
+#### Change the default port and the ssl certificate locations.
+
+See [doc/settings/nginx.md](doc/settings/nginx.md#change-the-default-port-and-the-ssl-certificate-locations).
+
+### Use non-packaged web-server
+
+For using an existing Nginx, Passenger, or Apache webserver see [doc/settings/nginx.md](doc/settings/nginx.md#using-a-non-bundled-web-server).
+
+## Using a non-packaged PostgreSQL database management server
+
+To connect to an external PostgreSQL or MySQL DBMS see [doc/settings/database.md](doc/settings/database.md) (MySQL support in the Omnibus Packages is Enterprise Only).
+
+## Using a non-packaged Redis instance
+
+See [doc/settings/redis.md](doc/settings/redis.md).
+
+### Adding ENV Vars to the Gitlab Runtime Environment
+
+See
+[doc/settings/environment-variables.md](doc/settings/environment-variables.md).
+
+### Changing gitlab.yml settings
+
+See [doc/settings/gitlab.yml.md](doc/settings/gitlab.yml.md).
+
+### Specify numeric user and group identifiers
+
+Omnibus-gitlab creates users for GitLab, PostgreSQL, Redis and NGINX. You can
+specify the numeric identifiers for these users in `/etc/gitlab/gitlab.rb` as
+follows.
+
+```ruby
+user['uid'] = 1234
+user['gid'] = 1234
+postgresql['uid'] = 1235
+postgresql['gid'] = 1235
+redis['uid'] = 1236
+redis['gid'] = 1236
+web_server['uid'] = 1237
+web_server['gid'] = 1237
+```
+
+### Sending application email via SMTP
+
+See [doc/settings/smtp.md](doc/settings/smtp.md).
+
+### Omniauth (Google, Twitter, GitHub login)
+
+Omniauth configuration is documented in
+[doc.gitlab.com](http://doc.gitlab.com/ce/integration/omniauth.html).
+
+### Adjusting Unicorn settings
+
+See [doc/settings/unicorn.md](doc/settings/unicorn.md).
+
+### Setting the NGINX listen address or addresses
+
+See [doc/settings/nginx.md](doc/settings/nginx.md).
+
+### Inserting custom NGINX settings into the GitLab server block
+
+See [doc/settings/nginx.md](doc/settings/nginx.md).
+
+### Inserting custom settings into the NGINX config
+
+See [doc/settings/nginx.md](doc/settings/nginx.md).