Merge remote-tracking branch 'origin/master' into feature-oauth-refactoring

3 files changed, 45 insertions, 64 deletions

diff --git a/doc/install/database_mysql.md b/doc/install/database_mysql.md
index 270ad3b0b86..ae68fd007ab 100644
--- a/doc/install/database_mysql.md
+++ b/doc/install/database_mysql.md
@@ -1,4 +1,4 @@
-# Database Mysql
+# Database MySQL
 
 ## Note
 
@@ -12,16 +12,16 @@ We do not recommend using MySQL due to various issues. For example, case [(in)se
     # Ensure you have MySQL version 5.5.14 or later
     mysql --version
 
-    # Pick a database root password (can be anything), type it and press enter
-    # Retype the database root password and press enter
+    # Pick a MySQL root password (can be anything), type it and press enter
+    # Retype the MySQL root password and press enter
 
-    # Secure your installation.
+    # Secure your installation
     sudo mysql_secure_installation
 
     # Login to MySQL
     mysql -u root -p
 
-    # Type the database root password
+    # Type the MySQL root password
 
     # Create a user for GitLab
     # do not type the 'mysql>', this is part of the prompt
diff --git a/doc/install/installation.md b/doc/install/installation.md
index 423a5f0cb19..5ad8392fb63 100644
--- a/doc/install/installation.md
+++ b/doc/install/installation.md
@@ -76,7 +76,7 @@ Is the system packaged Git too old? Remove it and compile from source.
     # Install into /usr/local/bin
     sudo make prefix=/usr/local install
 
-    # When editing config/gitlab.yml (Step 5), change the git bin_path to /usr/local/bin/git
+    # When editing config/gitlab.yml (Step 5), change the git -> bin_path to /usr/local/bin/git
 
 **Note:** In order to receive mail notifications, make sure to install a mail server. By default, Debian is shipped with exim4 but this [has problems](https://github.com/gitlabhq/gitlabhq/issues/4866#issuecomment-32726573) while Ubuntu does not ship with one. The recommended mail server is postfix and you can install it with:
 
@@ -153,12 +153,7 @@ We recommend using a PostgreSQL database. For MySQL check [MySQL setup guide](da
     # Copy the example GitLab config
     sudo -u git -H cp config/gitlab.yml.example config/gitlab.yml
 
-    # Make sure to change "localhost" to the fully-qualified domain name of your
-    # host serving GitLab where necessary
-    #
-    # If you want to use https make sure that you set `https` to `true`. See #using-https for all necessary details.
-    #
-    # If you installed Git from source, change the git bin_path to /usr/local/bin/git
+    # Update GitLab config file, follow the directions at top of file
     sudo -u git -H editor config/gitlab.yml
 
     # Make sure GitLab can write to the log/ and tmp/ directories
@@ -196,6 +191,8 @@ We recommend using a PostgreSQL database. For MySQL check [MySQL setup guide](da
 
 **Important Note:** Make sure to edit both `gitlab.yml` and `unicorn.rb` to match your setup.
 
+**Note:** If you want to use HTTPS, see [Using HTTPS](#using-https) for the additional steps.
+
 ### Configure GitLab DB Settings
 
     # PostgreSQL only:
@@ -233,17 +230,12 @@ GitLab Shell is an SSH access and repository management software developed speci
     # Run the installation task for gitlab-shell (replace `REDIS_URL` if needed):
     sudo -u git -H bundle exec rake gitlab:shell:install[v1.9.7] REDIS_URL=redis://localhost:6379 RAILS_ENV=production
 
-    # By default, the gitlab-shell config is generated from your main gitlab config.
-    #
-    # Note: When using GitLab with HTTPS please change the following:
-    # - Provide paths to the certificates under `ca_file` and `ca_path` options.
-    # - The `gitlab_url` option must point to the https endpoint of GitLab.
-    # - In case you are using self signed certificate set `self_signed_cert` to `true`.
-    # See #using-https for all necessary details.
-    #
+    # By default, the gitlab-shell config is generated from your main GitLab config.
     # You can review (and modify) the gitlab-shell config as follows:
     sudo -u git -H editor /home/git/gitlab-shell/config.yml
 
+**Note:** If you want to use HTTPS, see [Using HTTPS](#using-https) for the additional steps.
+
 ### Initialize Database and Activate Advanced Features
 
     sudo -u git -H bundle exec rake gitlab:setup RAILS_ENV=production
@@ -252,6 +244,10 @@ GitLab Shell is an SSH access and repository management software developed speci
 
     # When done you see 'Administrator account created:'
 
+**Note:** You can set the Administrator password by supplying it in environmental variable `GITLAB_ROOT_PASSWORD`, eg.:
+
+    sudo -u git -H bundle exec rake gitlab:setup RAILS_ENV=production GITLAB_ROOT_PASSWORD=newpassword
+
 ### Install Init Script
 
 Download the init script (will be `/etc/init.d/gitlab`):
@@ -309,14 +305,14 @@ Make sure to edit the config file to match your setup:
     # domain name of your host serving GitLab.
     sudo editor /etc/nginx/sites-available/gitlab
 
-**Note:** If you want to use HTTPS, replace the `gitlab` Nginx config with `gitlab-ssl`. See [Using HTTPS](#using-https) for all necessary details.
+**Note:** If you want to use HTTPS, replace the `gitlab` Nginx config with `gitlab-ssl`. See [Using HTTPS](#using-https) for HTTPS configuration details.
 
 ### Test Configuration
 
 Validate your `gitlab` or `gitlab-ssl` Nginx config file with the following command:
 
     sudo nginx -t
-    
+
 You should receive `syntax is okay` and `test is successful` messages. If you receive errors check your `gitlab` or `gitlab-ssl` Nginx config file for typos, etc. as indiciated in the error message given.
 
 ### Restart
@@ -350,11 +346,30 @@ Visit YOUR_SERVER in your web browser for your first GitLab login. The setup has
 
 ### Using HTTPS
 
-To recapitulate what is needed to use GitLab with HTTPS:
+To use GitLab with HTTPS:
+
+1. In `gitlab.yml`:
+    1. Set the `port` option in section 1 to `443`.
+    1. Set the `https` option in section 1 to `true`.
+1. In the `config.yml` of gitlab-shell:
+    1. Set `gitlab_url` option to the HTTPS endpoint of GitLab (e.g. `https://git.example.com`).
+    1. Set the certificates using either the `ca_file` or `ca_path` option.
+1. Use the `gitlab-ssl` Nginx example config instead of the `gitlab` config.
+    1. Update `YOUR_SERVER_FQDN`.
+    1. Update `ssl_certificate` and `ssl_certificate_key`.
+    1. Review the configuration file and consider applying other security and performance enhancing features.
+
+Using a self-signed certificate is discouraged but if you must use it follow the normal directions then:
 
-1. In `gitlab.yml` set the `https` option to `true`
-1. In the `config.yml` of gitlab-shell set the relevant options (see the [install GitLab Shell section](#install-gitlab-shell) of this document).
-1. Use the `gitlab-ssl` nginx example config instead of the `gitlab` config.
+1. Generate a self-signed SSL certificate:
+
+    ```
+    mkdir -p /etc/nginx/ssl/
+    cd /etc/nginx/ssl/
+    sudo openssl req -newkey rsa:2048 -x509 -nodes -days 3560 -out gitlab.crt -keyout gitlab.key
+    sudo chmod o-r gitlab.key
+    ```
+1. In the `config.yml` of gitlab-shell set `self_signed_cert` to `true`.
 
 ### Additional Markup Styles
 
@@ -390,38 +405,4 @@ You can configure LDAP authentication in `config/gitlab.yml`. Please restart Git
 
 ### Using Custom Omniauth Providers
 
-GitLab uses [Omniauth](http://www.omniauth.org/) for authentication and already ships with a few providers preinstalled (e.g. LDAP, GitHub, Twitter). But sometimes that is not enough and you need to integrate with other authentication solutions. For these cases you can use the Omniauth provider.
-
-#### Steps
-
-These steps are fairly general and you will need to figure out the exact details from the Omniauth provider's documentation.
-
--   Stop GitLab:
-
-        sudo service gitlab stop
-
--   Add the gem to your [Gemfile](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/Gemfile):
-
-        gem "omniauth-your-auth-provider"
-
--   If you're using MySQL, install the new Omniauth provider gem by running the following command:
-
-        sudo -u git -H bundle install --without development test postgres --path vendor/bundle --no-deployment
-
--   If you're using PostgreSQL, install the new Omniauth provider gem by running the following command:
-
-        sudo -u git -H bundle install --without development test mysql --path vendor/bundle --no-deployment
-
-    > These are the same commands you used in the [Install Gems section](#install-gems) with `--path vendor/bundle --no-deployment` instead of `--deployment`.
-
--   Start GitLab:
-
-        sudo service gitlab start
-
-#### Examples
-
-If you have successfully set up a provider that is not shipped with GitLab itself, please let us know.
-
-You can help others by reporting successful configurations and probably share a few insights or provide warnings for common errors or pitfalls by sharing your experience [in the public Wiki](https://github.com/gitlabhq/gitlab-public-wiki/wiki/Custom-omniauth-provider-configurations).
-
-While we can't officially support every possible authentication mechanism out there, we'd like to at least help those with special needs.
+See the [omniauth integration document](doc/integration/omniauth.md)
diff --git a/doc/install/requirements.md b/doc/install/requirements.md
index 53f6ccc8c34..fd2e29d3c52 100644
--- a/doc/install/requirements.md
+++ b/doc/install/requirements.md
@@ -7,9 +7,9 @@
 - Ubuntu
 - Debian
 - CentOS
-- RedHat Enterprise Linux
-- Scientific Linux
-- Oracle Linux
+- RedHat Enterprise Linux (please use the CentOS packages and instructions)
+- Scientific Linux (please use the CentOS packages and instructions)
+- Oracle Linux (please use the CentOS packages and instructions)
 
 For the installations options please see [the installation page on the GitLab website](https://about.gitlab.com/installation/).