Revert "Merge branch 'docs/pages-admin' into 'master' "

This reverts commit c824e37f8cc507bb48578c363876de69869cf85a.

2 files changed, 156 insertions, 248 deletions

diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md
index 1fe68986876..c352caf1115 100644
--- a/doc/administration/pages/index.md
+++ b/doc/administration/pages/index.md
@@ -1,4 +1,4 @@
-# GitLab Pages administration
+# GitLab Pages Administration
 
 > **Notes:**
 - [Introduced][ee-80] in GitLab EE 8.3.
@@ -6,7 +6,6 @@
 - GitLab Pages [were ported][ce-14605] to Community Edition in GitLab 8.17.
 - This guide is for Omnibus GitLab installations. If you have installed
   GitLab from source, follow the [Pages source installation document](source.md).
-- To learn how to use GitLab Pages, read the [user documentation][pages-userguide].
 
 ---
 
@@ -15,6 +14,9 @@ sure to read the [changelog](#changelog) if you are upgrading to a new GitLab
 version as it may include new features and changes needed to be made in your
 configuration.
 
+If you are looking for ways to upload your static content in GitLab Pages, you
+probably want to read the [user documentation][pages-userguide].
+
 ## Overview
 
 GitLab Pages makes use of the [GitLab Pages daemon], a simple HTTP server
@@ -30,7 +32,7 @@ In the case of custom domains, the Pages daemon needs to listen on ports `80`
 and/or `443`. For that reason, there is some flexibility in the way which you
 can set it up:
 
-1. Run the pages daemon in the same server as GitLab, listening on a secondary IP.
+1. Run the pages daemon in the same server as GitLab, listening on a secondary IP
 1. Run the pages daemon in a separate server. In that case, the
    [Pages path](#change-storage-path) must also be present in the server that
    the pages daemon is installed, so you will have to share it via network.
@@ -62,11 +64,11 @@ you need to add a [wildcard DNS A record][wiki-wildcard-dns] pointing to the
 host that GitLab runs. For example, an entry would look like this:
 
 ```
-*.example.io. 1800 IN A 1.1.1.1
+*.example.io. 1800 IN A 1.2.3.4
 ```
 
 where `example.io` is the domain under which GitLab Pages will be served
-and `1.1.1.1` is the IP address of your GitLab instance.
+and `1.2.3.4` is the IP address of your GitLab instance.
 
 > **Note:**
 You should not use the GitLab domain to serve user pages. For more information
@@ -76,81 +78,46 @@ see the [security section](#security).
 
 ## Configuration
 
-Depending on your needs, you can set up GitLab Pages in 4 different ways.
-The following options are listed from the easiest setup to the most
-advanced one. The absolute minimum requirement is to set up the wildcard DNS
-since that is needed in all configurations.
-
-### Wildcard domains
-
->**Requirements:**
-- [Wildcard DNS setup](#dns-configuration)
->
->---
->
-URL scheme: `http://page.example.io`
-
-This is the minimum setup that you can use Pages with. It is the base for all
-other setups as described below. Nginx will proxy all requests to the daemon.
-The Pages daemon doesn't listen to the outside world.
-
-1. Set the external URL for GitLab Pages in `/etc/gitlab/gitlab.rb`:
-
-    ```ruby
-    pages_external_url 'http://example.io'
-    ```
-
-1. [Reconfigure GitLab][reconfigure]
+Depending on your needs, you can install GitLab Pages in four different ways.
 
-### Wildcard domains with TLS support
+### Option 1. Custom domains with HTTPS support
 
->**Requirements:**
-- [Wildcard DNS setup](#dns-configuration)
-- Wildcard TLS certificate
->
->---
->
-URL scheme: `https://page.example.io`
+| URL scheme | Wildcard certificate | Custom domain with HTTP support | Custom domain with HTTPS support | Secondary IP |
+| --- |:---:|:---:|:---:|:---:|:---:|:---:|:---:|
+| `https://page.example.io` and `https://page.com` | yes |  redirects to HTTPS | yes | yes |
 
-Nginx will proxy all requests to the daemon. Pages daemon doesn't listen to the
-outside world.
+Pages enabled, daemon is enabled AND pages has external IP support enabled.
+In that case, the pages daemon is running, NGINX still proxies requests to
+the daemon but the daemon is also able to receive requests from the outside
+world. Custom domains and TLS are supported.
 
-1. Place the certificate and key inside `/etc/gitlab/ssl`
-1. In `/etc/gitlab/gitlab.rb` specify the following configuration:
+1. Edit `/etc/gitlab/gitlab.rb`:
 
     ```ruby
-    pages_external_url 'https://example.io'
-
-    pages_nginx['redirect_http_to_https'] = true
-    pages_nginx['ssl_certificate'] = "/etc/gitlab/ssl/pages-nginx.crt"
-    pages_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/pages-nginx.key"
+    pages_external_url "https://example.io"
+    nginx['listen_addresses'] = ['1.1.1.1']
+    pages_nginx['enable'] = false
+    gitlab_pages['cert'] = "/etc/gitlab/ssl/example.io.crt"
+    gitlab_pages['cert_key'] = "/etc/gitlab/ssl/example.io.key"
+    gitlab_pages['external_http'] = '1.1.1.2:80'
+    gitlab_pages['external_https'] = '1.1.1.2:443'
     ```
 
-    where `pages-nginx.crt` and `pages-nginx.key` are the SSL cert and key,
-    respectively.
+    where `1.1.1.1` is the primary IP address that GitLab is listening to and
+    `1.1.1.2` the secondary IP where the GitLab Pages daemon listens to.
 
 1. [Reconfigure GitLab][reconfigure]
 
-## Advanced configuration
-
-In addition to the wildcard domains, you can also have the option to configure
-GitLab Pages to work with custom domains. Again, there are two options here:
-support custom domains with and without TLS certificates. The easiest setup is
-that without TLS certificates.
-
-### Custom domains
+### Option 2. Custom domains without HTTPS support
 
->**Requirements:**
-- [Wildcard DNS setup](#dns-configuration)
-- Secondary IP
->
----
->
-URL scheme: `http://page.example.io` and `http://domain.com`
+| URL scheme |  Wildcard certificate | Custom domain with HTTP support | Custom domain with HTTPS support | Secondary IP |
+| --- |:---:|:---:|:---:|:---:|:---:|:---:|:---:|
+| `http://page.example.io` and `http://page.com` | no  |  yes    | no  | yes |
 
-In that case, the pages daemon is running, Nginx still proxies requests to
+Pages enabled, daemon is enabled AND pages has external IP support enabled.
+In that case, the pages daemon is running, NGINX still proxies requests to
 the daemon but the daemon is also able to receive requests from the outside
-world. Custom domains are supported, but no TLS.
+world. Custom domains and TLS are supported.
 
 1. Edit `/etc/gitlab/gitlab.rb`:
 
@@ -166,35 +133,45 @@ world. Custom domains are supported, but no TLS.
 
 1. [Reconfigure GitLab][reconfigure]
 
-### Custom domains with TLS support
+### Option 3. Wildcard HTTPS domain without custom domains
 
->**Requirements:**
-- [Wildcard DNS setup](#dns-configuration)
-- Wildcard TLS certificate
-- Secondary IP
->
----
->
-URL scheme: `https://page.example.io` and `https://domain.com`
+| URL scheme | Wildcard certificate | Custom domain with HTTP support | Custom domain with HTTPS support | Secondary IP |
+| --- |:---:|:---:|:---:|:---:|:---:|:---:|:---:|
+| `https://page.example.io` | yes |  no | no | no |
 
-In that case, the pages daemon is running, Nginx still proxies requests to
-the daemon but the daemon is also able to receive requests from the outside
-world. Custom domains and TLS are supported.
+Pages enabled, daemon is enabled and NGINX will proxy all requests to the
+daemon. Pages daemon doesn't listen to the outside world.
 
-1. Edit `/etc/gitlab/gitlab.rb`:
+1. Place the certificate and key inside `/etc/gitlab/ssl`
+1. In `/etc/gitlab/gitlab.rb` specify the following configuration:
 
     ```ruby
-    pages_external_url "https://example.io"
-    nginx['listen_addresses'] = ['1.1.1.1']
-    pages_nginx['enable'] = false
-    gitlab_pages['cert'] = "/etc/gitlab/ssl/example.io.crt"
-    gitlab_pages['cert_key'] = "/etc/gitlab/ssl/example.io.key"
-    gitlab_pages['external_http'] = '1.1.1.2:80'
-    gitlab_pages['external_https'] = '1.1.1.2:443'
+    pages_external_url 'https://example.io'
+
+    pages_nginx['redirect_http_to_https'] = true
+    pages_nginx['ssl_certificate'] = "/etc/gitlab/ssl/pages-nginx.crt"
+    pages_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/pages-nginx.key"
     ```
 
-    where `1.1.1.1` is the primary IP address that GitLab is listening to and
-    `1.1.1.2` the secondary IP where the GitLab Pages daemon listens to.
+    where `pages-nginx.crt` and `pages-nginx.key` are the SSL cert and key,
+    respectively.
+
+1. [Reconfigure GitLab][reconfigure]
+
+### Option 4. Wildcard HTTP domain without custom domains
+
+| URL scheme | Wildcard certificate | Custom domain with HTTP support | Custom domain with HTTPS support | Secondary IP |
+| --- |:---:|:---:|:---:|:---:|:---:|:---:|:---:|
+| `http://page.example.io`  | no  |  no | no | no |
+
+Pages enabled, daemon is enabled and NGINX will proxy all requests to the
+daemon. Pages daemon doesn't listen to the outside world.
+
+1. Set the external URL for GitLab Pages in `/etc/gitlab/gitlab.rb`:
+
+    ```ruby
+    pages_external_url 'http://example.io'
+    ```
 
 1. [Reconfigure GitLab][reconfigure]
 
diff --git a/doc/administration/pages/source.md b/doc/administration/pages/source.md
index 83efe54c88d..d4468b99992 100644
--- a/doc/administration/pages/source.md
+++ b/doc/administration/pages/source.md
@@ -17,54 +17,22 @@ Pages to the latest supported version.
 
 ## Prerequisites
 
-Before proceeding with the Pages configuration, you will need to:
-
-1. Have a separate domain under which the GitLab Pages will be served. In this
-   document we assume that to be `example.io`.
-1. Configure a **wildcard DNS record**.
-1. (Optional) Have a **wildcard certificate** for that domain if you decide to
-   serve Pages under HTTPS.
-1. (Optional but recommended) Enable [Shared runners](../../ci/runners/README.md)
-   so that your users don't have to bring their own.
-
-### DNS configuration
-
-GitLab Pages expect to run on their own virtual host. In your DNS server/provider
-you need to add a [wildcard DNS A record][wiki-wildcard-dns] pointing to the
-host that GitLab runs. For example, an entry would look like this:
-
-```
-*.example.io. 1800 IN A 1.1.1.1
-```
-
-where `example.io` is the domain under which GitLab Pages will be served
-and `1.1.1.1` is the IP address of your GitLab instance.
-
-> **Note:**
-You should not use the GitLab domain to serve user pages. For more information
-see the [security section](#security).
-
-[wiki-wildcard-dns]: https://en.wikipedia.org/wiki/Wildcard_DNS_record
+[Read the Omnibus prerequisites section.](index.md#prerequisites)
 
 ## Configuration
 
-Depending on your needs, you can set up GitLab Pages in 4 different ways.
-The following options are listed from the easiest setup to the most
-advanced one. The absolute minimum requirement is to set up the wildcard DNS
-since that is needed in all configurations.
+Depending on your needs, you can install GitLab Pages in four different ways.
 
-### Wildcard domains
+### Option 1. Custom domains with HTTPS support
 
->**Requirements:**
-- [Wildcard DNS setup](#dns-configuration)
->
->---
->
-URL scheme: `http://page.example.io`
+| URL scheme | Wildcard certificate | Custom domain with HTTP support | Custom domain with HTTPS support | Secondary IP |
+| --- |:---:|:---:|:---:|:---:|:---:|:---:|:---:|
+| `https://page.example.io` and `https://page.com` | yes |  redirects to HTTPS | yes | yes |
 
-This is the minimum setup that you can use Pages with. It is the base for all
-other setups as described below. Nginx will proxy all requests to the daemon.
-The Pages daemon doesn't listen to the outside world.
+Pages enabled, daemon is enabled AND pages has external IP support enabled.
+In that case, the pages daemon is running, NGINX still proxies requests to
+the daemon but the daemon is also able to receive requests from the outside
+world. Custom domains and TLS are supported.
 
 1. Install the Pages daemon:
 
@@ -76,14 +44,10 @@ The Pages daemon doesn't listen to the outside world.
     sudo -u git -H make
     ```
 
-1. Go to the GitLab installation directory:
-
-     ```bash
-     cd /home/git/gitlab
-     ```
-
-1. Edit `gitlab.yml` and under the `pages` setting, set `enabled` to `true` and
-   the `host` to the FQDN under which GitLab Pages will be served:
+1. Edit `gitlab.yml` to look like the example below. You need to change the
+   `host` to the FQDN under which GitLab Pages will be served. Set
+   `external_http` and `external_https` to the secondary IP on which the pages
+   daemon will listen for connections:
 
      ```yaml
      ## GitLab Pages
@@ -93,59 +57,25 @@ The Pages daemon doesn't listen to the outside world.
        # path: shared/pages
 
        host: example.io
-       port: 80
-       https: false
-     ```
-
-1. Copy the `gitlab-pages-ssl` Nginx configuration file:
-
-    ```bash
-    sudo cp lib/support/nginx/gitlab-pages-ssl /etc/nginx/sites-available/gitlab-pages-ssl.conf
-    sudo ln -sf /etc/nginx/sites-{available,enabled}/gitlab-pages-ssl.conf
-    ```
-
-      Replace `gitlab-pages-ssl` with `gitlab-pages` if you are not using SSL.
-
-1. Restart NGINX
-1. [Restart GitLab][restart]
-
-### Wildcard domains with TLS support
-
->**Requirements:**
-- [Wildcard DNS setup](#dns-configuration)
-- Wildcard TLS certificate
->
->---
->
-URL scheme: `https://page.example.io`
+       port: 443
+       https: true
 
-Nginx will proxy all requests to the daemon. Pages daemon doesn't listen to the
-outside world.
+       external_http: 1.1.1.2:80
+       external_https: 1.1.1.2:443
+     ```
 
-1. Install the Pages daemon:
+1. Edit `/etc/default/gitlab` and set `gitlab_pages_enabled` to `true` in
+   order to enable the pages daemon. In `gitlab_pages_options` the
+   `-pages-domain`, `-listen-http` and `-listen-https` must match the `host`,
+   `external_http` and `external_https` settings that you set above respectively.
+   The `-root-cert` and `-root-key` settings are the wildcard TLS certificates
+   of the `example.io` domain:
 
     ```
-    cd /home/git
-    sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-pages.git
-    cd gitlab-pages
-    sudo -u git -H git checkout v0.2.4
-    sudo -u git -H make
+    gitlab_pages_enabled=true
+    gitlab_pages_options="-pages-domain example.io -pages-root $app_root/shared/pages -listen-proxy 127.0.0.1:8090 -listen-http 1.1.1.2:80 -listen-https 1.1.1.2:443 -root-cert /path/to/example.io.crt -root-key /path/to/example.io.key
     ```
 
-1. In `gitlab.yml`, set the port to `443` and https to `true`:
-
-     ```bash
-     ## GitLab Pages
-     pages:
-       enabled: true
-       # The location where pages are stored (default: shared/pages).
-       # path: shared/pages
-
-       host: example.io
-       port: 443
-       https: true
-     ```
-
 1. Copy the `gitlab-pages-ssl` Nginx configuration file:
 
     ```bash
@@ -155,30 +85,22 @@ outside world.
 
       Replace `gitlab-pages-ssl` with `gitlab-pages` if you are not using SSL.
 
+1. Edit all GitLab related configs in `/etc/nginx/site-available/` and replace
+   `0.0.0.0` with `1.1.1.1`, where `1.1.1.1` the primary IP where GitLab
+   listens to.
 1. Restart NGINX
 1. [Restart GitLab][restart]
 
+### Option 2. Custom domains without HTTPS support
 
-## Advanced configuration
+| URL scheme |  Wildcard certificate | Custom domain with HTTP support | Custom domain with HTTPS support | Secondary IP |
+| --- |:---:|:---:|:---:|:---:|:---:|:---:|:---:|
+| `http://page.example.io` and `http://page.com` | no  |  yes    | no  | yes |
 
-In addition to the wildcard domains, you can also have the option to configure
-GitLab Pages to work with custom domains. Again, there are two options here:
-support custom domains with and without TLS certificates. The easiest setup is
-that without TLS certificates.
-
-### Custom domains
-
->**Requirements:**
-- [Wildcard DNS setup](#dns-configuration)
-- Secondary IP
->
----
->
-URL scheme: `http://page.example.io` and `http://domain.com`
-
-In that case, the pages daemon is running, Nginx still proxies requests to
+Pages enabled, daemon is enabled AND pages has external IP support enabled.
+In that case, the pages daemon is running, NGINX still proxies requests to
 the daemon but the daemon is also able to receive requests from the outside
-world. Custom domains are supported, but no TLS.
+world. Custom domains and TLS are supported.
 
 1. Install the Pages daemon:
 
@@ -233,20 +155,14 @@ world. Custom domains are supported, but no TLS.
 1. Restart NGINX
 1. [Restart GitLab][restart]
 
-### Custom domains with TLS support
+### Option 3. Wildcard HTTPS domain without custom domains
 
->**Requirements:**
-- [Wildcard DNS setup](#dns-configuration)
-- Wildcard TLS certificate
-- Secondary IP
->
----
->
-URL scheme: `https://page.example.io` and `https://domain.com`
+| URL scheme | Wildcard certificate | Custom domain with HTTP support | Custom domain with HTTPS support | Secondary IP |
+| --- |:---:|:---:|:---:|:---:|:---:|:---:|:---:|
+| `https://page.example.io` | yes |  no | no | no |
 
-In that case, the pages daemon is running, Nginx still proxies requests to
-the daemon but the daemon is also able to receive requests from the outside
-world. Custom domains and TLS are supported.
+Pages enabled, daemon is enabled and NGINX will proxy all requests to the
+daemon. Pages daemon doesn't listen to the outside world.
 
 1. Install the Pages daemon:
 
@@ -257,13 +173,9 @@ world. Custom domains and TLS are supported.
     sudo -u git -H git checkout v0.2.4
     sudo -u git -H make
     ```
+1. In `gitlab.yml`, set the port to `443` and https to `true`:
 
-1. Edit `gitlab.yml` to look like the example below. You need to change the
-   `host` to the FQDN under which GitLab Pages will be served. Set
-   `external_http` and `external_https` to the secondary IP on which the pages
-   daemon will listen for connections:
-
-     ```yaml
+     ```bash
      ## GitLab Pages
      pages:
        enabled: true
@@ -273,23 +185,8 @@ world. Custom domains and TLS are supported.
        host: example.io
        port: 443
        https: true
-
-       external_http: 1.1.1.2:80
-       external_https: 1.1.1.2:443
      ```
 
-1. Edit `/etc/default/gitlab` and set `gitlab_pages_enabled` to `true` in
-   order to enable the pages daemon. In `gitlab_pages_options` the
-   `-pages-domain`, `-listen-http` and `-listen-https` must match the `host`,
-   `external_http` and `external_https` settings that you set above respectively.
-   The `-root-cert` and `-root-key` settings are the wildcard TLS certificates
-   of the `example.io` domain:
-
-    ```
-    gitlab_pages_enabled=true
-    gitlab_pages_options="-pages-domain example.io -pages-root $app_root/shared/pages -listen-proxy 127.0.0.1:8090 -listen-http 1.1.1.2:80 -listen-https 1.1.1.2:443 -root-cert /path/to/example.io.crt -root-key /path/to/example.io.key
-    ```
-
 1. Copy the `gitlab-pages-ssl` Nginx configuration file:
 
     ```bash
@@ -299,26 +196,60 @@ world. Custom domains and TLS are supported.
 
       Replace `gitlab-pages-ssl` with `gitlab-pages` if you are not using SSL.
 
-1. Edit all GitLab related configs in `/etc/nginx/site-available/` and replace
-   `0.0.0.0` with `1.1.1.1`, where `1.1.1.1` the primary IP where GitLab
-   listens to.
 1. Restart NGINX
 1. [Restart GitLab][restart]
 
-## Change storage path
+### Option 4. Wildcard HTTP domain without custom domains
 
-Follow the steps below to change the default path where GitLab Pages' contents
-are stored.
+| URL scheme | Wildcard certificate | Custom domain with HTTP support | Custom domain with HTTPS support | Secondary IP |
+| --- |:---:|:---:|:---:|:---:|:---:|:---:|:---:|
+| `http://page.example.io`  | no  |  no | no | no |
 
-1. Pages are stored by default in `/var/opt/gitlab/gitlab-rails/shared/pages`.
-   If you wish to store them in another location you must set it up in
-   `/etc/gitlab/gitlab.rb`:
+Pages enabled, daemon is enabled and NGINX will proxy all requests to the
+daemon. Pages daemon doesn't listen to the outside world.
+
+1. Install the Pages daemon:
 
-     ```ruby
-     gitlab_rails['pages_path'] = "/mnt/storage/pages"
+    ```
+    cd /home/git
+    sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-pages.git
+    cd gitlab-pages
+    sudo -u git -H git checkout v0.2.4
+    sudo -u git -H make
+    ```
+
+1. Go to the GitLab installation directory:
+
+     ```bash
+     cd /home/git/gitlab
+     ```
+
+1. Edit `gitlab.yml` and under the `pages` setting, set `enabled` to `true` and
+   the `host` to the FQDN under which GitLab Pages will be served:
+
+     ```yaml
+     ## GitLab Pages
+     pages:
+       enabled: true
+       # The location where pages are stored (default: shared/pages).
+       # path: shared/pages
+
+       host: example.io
+       port: 80
+       https: false
      ```
 
-1. [Reconfigure GitLab][reconfigure]
+1. Copy the `gitlab-pages-ssl` Nginx configuration file:
+
+    ```bash
+    sudo cp lib/support/nginx/gitlab-pages-ssl /etc/nginx/sites-available/gitlab-pages-ssl.conf
+    sudo ln -sf /etc/nginx/sites-{available,enabled}/gitlab-pages-ssl.conf
+    ```
+
+      Replace `gitlab-pages-ssl` with `gitlab-pages` if you are not using SSL.
+
+1. Restart NGINX
+1. [Restart GitLab][restart]
 
 ## NGINX caveats