First iteration on Pages refactoring

1 files changed, 176 insertions, 176 deletions

diff --git a/doc/pages/administration.md b/doc/pages/administration.md
index 0e1665fa832..9a94282a229 100644
--- a/doc/pages/administration.md
+++ b/doc/pages/administration.md
@@ -1,8 +1,9 @@
 # GitLab Pages Administration
 
-> **Note:**
-> This feature was first [introduced][ee-80] in GitLab EE 8.3.
-> Custom CNAMEs with TLS support were [introduced][ee-173] in GitLab EE 8.5.
+> **Notes:**
+> - [Introduced][ee-80] in GitLab EE 8.3.
+> - Custom CNAMEs with TLS support were [introduced][ee-173] in GitLab EE 8.5.
+> - GitLab Pages were ported to Community Edition in GitLab 8.16.
 
 ---
 
@@ -14,33 +15,20 @@ configuration.
 If you are looking for ways to upload your static content in GitLab Pages, you
 probably want to read the [user documentation](README.md).
 
-## The GitLab Pages daemon
-
-Starting from GitLab EE 8.5, GitLab Pages make use of the [GitLab Pages daemon],
-a simple HTTP server written in Go that can listen on an external IP address
-and provide support for custom domains and custom certificates. The GitLab
-Pages Daemon supports dynamic certificates through SNI and exposes pages using
-HTTP2 by default.
-
-Here is a brief list with what it is supported when using the pages daemon:
-
-- Multiple domains per-project
-- One TLS certificate per-domain
-  - Validation of certificate
-  - Validation of certificate chain
-  - Validation of private key against certificate
+## Overview
 
+GitLab Pages makes use of the [GitLab Pages daemon], a simple HTTP server
+written in Go that can listen on an external IP address and provide support for
+custom domains and custom certificates. It supports dynamic certificates through
+SNI and exposes pages using HTTP2 by default.
 You are encouraged to read its [README][pages-readme] to fully understand how
 it works.
 
-[gitlab pages daemon]: https://gitlab.com/gitlab-org/gitlab-pages
-[pages-readme]: https://gitlab.com/gitlab-org/gitlab-pages/blob/master/README.md
-
-### The GitLab Pages daemon and the case of custom domains
+---
 
 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, so you basically have three choices:
+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 a separate server. In that case, the
@@ -53,68 +41,18 @@ can set it up, so you basically have three choices:
    pages will not be able to be served with user provided certificates. For
    HTTP it's OK to use HTTP or TCP load balancing.
 
-In this document, we will proceed assuming the first option. Let's begin by
-installing the pages daemon.
-
-### Install the Pages daemon
-
-**Source installations**
-
-```
-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.1
-sudo -u git -H make
-```
-
-**Omnibus installations**
-
-The `gitlab-pages` daemon is included in the Omnibus package.
-
-
-## Configuration
-
-There are multiple ways to set up GitLab Pages according to what URL scheme you
-are willing to support.
-
-### Configuration prerequisites
+In this document, we will proceed assuming the first option.
 
-In the next section you will find all possible scenarios to choose from.
+## Prerequisites
 
-In either scenario, you will need:
+Before proceeding with the Pages configuration, you will need to:
 
-1. To use the [GitLab Pages daemon](#the-gitlab-pages-daemon)
-1. A separate domain
-1. A separate Nginx configuration file which needs to be explicitly added in
-   the server under which GitLab EE runs (Omnibus does that automatically)
-1. (Optional) A wildcard certificate for that domain if you decide to serve
-   pages under HTTPS
-1. (Optional but recommended) [Shared runners](../ci/runners/README.md) so that
-   your users don't have to bring their own
-
-### Configuration scenarios
-
-Before proceeding with setting up GitLab Pages, you have to decide which route
-you want to take.
-
-The possible scenarios are depicted in the table below.
-
-| URL scheme | Option | Wildcard certificate | Custom domain with HTTP support | Custom domain with HTTPS support | Secondary IP |
-| --- |:---:|:---:|:---:|:---:|:---:|:---:|:---:|
-| `http://page.example.io`  | 1 | no  |  no | no | no |
-| `https://page.example.io` | 1 | yes |  no | no | no |
-| `http://page.example.io` and `http://page.com`   | 2 | no  |  yes    | no  | yes |
-| `https://page.example.io` and `https://page.com` | 2 | yes |  redirects to HTTPS | yes | yes |
-
-As you see from the table above, each URL scheme comes with an option:
-
-1. Pages enabled, daemon is enabled and NGINX will proxy all requests to the
-   daemon. Pages daemon doesn't listen to the outside world.
-1. 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. Have a separate domain under which the GitLab Pages will be served
+1. (Optional) Have a wildcard certificate for that domain if you decide to serve
+   Pages under HTTPS
+1. Configure a wildcard DNS record
+1. (Optional but recommended) Enable [Shared runners](../ci/runners/README.md)
+   so that your users don't have to bring their own
 
 ### DNS configuration
 
@@ -129,21 +67,39 @@ host that GitLab runs. For example, an entry would look like this:
 where `example.io` is the domain under which GitLab Pages will be served
 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
 see the [security section](#security).
 
 [wiki-wildcard-dns]: https://en.wikipedia.org/wiki/Wildcard_DNS_record
 
-## Setting up GitLab Pages
+## Configuration
 
-Below are the four scenarios that are described in
-[#configuration-scenarios](#configuration-scenarios).
+Depending on your needs, you can install GitLab Pages in four different ways.
 
-### Custom domains with HTTPS support
+### Option 1. Custom domains with HTTPS support
+
+| 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 |
+
+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.
 
 **Source installations:**
 
-1. [Install the pages daemon](#install-the-pages-daemon)
+1. Install the Pages daemon:
+
+    ```
+    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.1
+    sudo -u git -H make
+    ```
+
 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
@@ -176,7 +132,19 @@ Below are the four scenarios that are described in
     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.1:80 -listen-https 1.1.1.1:443 -root-cert /path/to/example.io.crt -root-key /path/to/example.io.key
     ```
 
-1. Make sure to [configure NGINX](#nginx-configuration) properly.
+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. 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]
 
 ---
@@ -197,17 +165,32 @@ Below are the four scenarios that are described in
 
     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.
-    Read more at the
-    [NGINX configuration for custom domains](#nginx-configuration-for-custom-domains)
-    section.
 
 1. [Reconfigure GitLab][reconfigure]
 
-### Custom domains without HTTPS support
+### Option 2. Custom domains without HTTPS support
+
+| 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 |
+
+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.
 
 **Source installations:**
 
-1. [Install the pages daemon](#install-the-pages-daemon)
+1. Install the Pages daemon:
+
+    ```
+    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.1
+    sudo -u git -H make
+    ```
+
 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` to the secondary IP on which the pages daemon will listen
@@ -236,7 +219,19 @@ Below are the four scenarios that are described in
     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.1:80"
     ```
 
-1. Make sure to [configure NGINX](#nginx-configuration) properly.
+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. 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]
 
 ---
@@ -254,58 +249,29 @@ Below are the four scenarios that are described in
 
     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.
-    Read more at the
-    [NGINX configuration for custom domains](#nginx-configuration-for-custom-domains)
-    section.
 
 1. [Reconfigure GitLab][reconfigure]
 
-### Wildcard HTTP domain without custom domains
+### Option 3. Wildcard HTTPS domain without custom domains
 
-**Source installations:**
-
-1. [Install the pages daemon](#install-the-pages-daemon)
-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. Make sure to [configure NGINX](#nginx-configuration) properly.
-1. [Restart GitLab][restart]
+| URL scheme | Wildcard certificate | Custom domain with HTTP support | Custom domain with HTTPS support | Secondary IP |
+| --- |:---:|:---:|:---:|:---:|:---:|:---:|:---:|
+| `https://page.example.io` | yes |  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.
 
-**Omnibus installations:**
+**Source installations:**
 
-1. Set the external URL for GitLab Pages in `/etc/gitlab/gitlab.rb`:
+1. Install the Pages daemon:
 
-    ```ruby
-    pages_external_url 'http://example.io'
     ```
-
-1. [Reconfigure GitLab][reconfigure]
-
-### Wildcard HTTPS domain without custom domains
-
-**Source installations:**
-
-1. [Install the pages daemon](#install-the-pages-daemon)
+    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.1
+    sudo -u git -H make
+    ```
 1. In `gitlab.yml`, set the port to `443` and https to `true`:
 
      ```bash
@@ -320,7 +286,14 @@ Below are the four scenarios that are described in
        https: true
      ```
 
-1. Make sure to [configure NGINX](#nginx-configuration) properly.
+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.
 
 ---
 
@@ -342,49 +315,76 @@ Below are the four scenarios that are described in
 
 1. [Reconfigure GitLab][reconfigure]
 
-## NGINX configuration
+### Option 4. Wildcard HTTP domain without custom domains
 
-Depending on your setup, you will need to make some changes to NGINX.
-Specifically you must change the domain name and the IP address where NGINX
-listens to. Read the following sections for more details.
+| URL scheme | Wildcard certificate | Custom domain with HTTP support | Custom domain with HTTPS support | Secondary IP |
+| --- |:---:|:---:|:---:|:---:|:---:|:---:|:---:|
+| `http://page.example.io`  | no  |  no | no | no |
 
-### NGINX configuration files
+Pages enabled, daemon is enabled and NGINX will proxy all requests to the
+daemon. Pages daemon doesn't listen to the outside world.
 
-Copy the `gitlab-pages-ssl` Nginx configuration file:
+**Source installations:**
 
-```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
-```
+1. Install the Pages daemon:
 
-Replace `gitlab-pages-ssl` with `gitlab-pages` if you are not using SSL.
+    ```
+    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.1
+    sudo -u git -H make
+    ```
 
-### NGINX configuration for custom domains
+1. Go to the GitLab installation directory:
 
-> If you are not using custom domains ignore this section.
+     ```bash
+     cd /home/git/gitlab
+     ```
 
-[In the case of custom domains](#the-gitlab-pages-daemon-and-the-case-of-custom-domains),
-if you have the secondary IP address configured on the same server as GitLab,
-you need to change **all** NGINX configs to listen on the first IP address.
+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:
 
-**Source installations:**
+     ```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. 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. 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]
+
+---
 
 **Omnibus installations:**
 
-1. Edit `/etc/gitlab/gilab.rb`:
+1. Set the external URL for GitLab Pages in `/etc/gitlab/gitlab.rb`:
 
-    ```
-    nginx['listen_addresses'] = ['1.1.1.1']
+    ```ruby
+    pages_external_url 'http://example.io'
     ```
 
 1. [Reconfigure GitLab][reconfigure]
 
-### NGINX caveats
+## NGINX caveats
+
+>**Note:**
+The following information applies only for installations from source.
 
 Be extra careful when setting up the domain name in the NGINX config. You must
 not remove the backslashes.
@@ -462,35 +462,35 @@ latest previous version.
 
 ---
 
+**GitLab 8.16 ([documentation][8-16-docs])**
+
+- GitLab Pages were ported to Community Edition in GitLab 8.16.
+- Documentation was refactored to be more modular and easy to follow.
+
 **GitLab 8.5 ([documentation][8-5-docs])**
 
 - In GitLab 8.5 we introduced the [gitlab-pages][] daemon which is now the
   recommended way to set up GitLab Pages.
 - The [NGINX configs][] have changed to reflect this change. So make sure to
   update them.
-- Custom CNAME and TLS certificates support
-- Documentation was moved to one place
-
-[8-5-docs]: https://gitlab.com/gitlab-org/gitlab-ee/blob/8-5-stable-ee/doc/pages/administration.md
-[gitlab-pages]: https://gitlab.com/gitlab-org/gitlab-pages/tree/v0.2.1
-[NGINX configs]: https://gitlab.com/gitlab-org/gitlab-ee/tree/8-5-stable-ee/lib/support/nginx
+- Custom CNAME and TLS certificates support.
+- Documentation was moved to one place.
 
 ---
 
-**GitLab 8.4**
-
-No new changes.
-
----
-
-**GitLab 8.3 ([source docs][8-3-docs], [Omnibus docs][8-3-omnidocs])**
+**GitLab 8.3 ([documentation][8-3-docs])**
 
 - GitLab Pages feature was introduced.
 
 [8-3-docs]: https://gitlab.com/gitlab-org/gitlab-ee/blob/8-3-stable-ee/doc/pages/administration.md
-[8-3-omnidocs]: https://gitlab.com/gitlab-org/omnibus-gitlab/blob/8-3-stable-ee/doc/settings/pages.md
+[8-5-docs]: https://gitlab.com/gitlab-org/gitlab-ee/blob/8-5-stable-ee/doc/pages/administration.md
+[8-16-docs]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-16-stable-ce/doc/pages/administration.md
 [backup]: ../raketasks/backup_restore.md
 [ee-80]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/80
 [ee-173]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/173
+[gitlab pages daemon]: https://gitlab.com/gitlab-org/gitlab-pages
+[NGINX configs]: https://gitlab.com/gitlab-org/gitlab-ee/tree/8-5-stable-ee/lib/support/nginx
+[pages-readme]: https://gitlab.com/gitlab-org/gitlab-pages/blob/master/README.md
 [reconfigure]: ../administration/restart_gitlab.md#omnibus-gitlab-reconfigure
 [restart]: ../administration/restart_gitlab.md#installations-from-source
+[gitlab-pages]: https://gitlab.com/gitlab-org/gitlab-pages/tree/v0.2.1