Skip to content

G
gitlab-ce
Commit 16bb6a74 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis
Browse files
Options

First iteration on Pages refactoring

parent 938624c9
Show whitespace changes
Inline Side-by-side
Showing with 176 additions and 176 deletions
doc/pages/administration.md
View file @ 16bb6a74
# GitLab Pages Administration # GitLab Pages Administration
> **Note:** > **Notes:**
> This feature was first [introduced][ee-80] in GitLab EE 8.3. > - [Introduced][ee-80] in GitLab EE 8.3.
> Custom CNAMEs with TLS support were [introduced][ee-173] in GitLab EE 8.5. > - 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. ...@@ -14,33 +15,20 @@ configuration.
If you are looking for ways to upload your static content in GitLab Pages, you If you are looking for ways to upload your static content in GitLab Pages, you
probably want to read the [user documentation](README.md). probably want to read the [user documentation](README.md).
## The GitLab Pages daemon ## Overview
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
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 You are encouraged to read its [README][pages-readme] to fully understand how
it works. 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` 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 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 the same server as GitLab, listening on a secondary IP
1. Run the pages daemon in a separate server. In that case, the 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: ...@@ -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 pages will not be able to be served with user provided certificates. For
HTTP it's OK to use HTTP or TCP load balancing. 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 In this document, we will proceed assuming the first option.
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 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. Have a separate domain under which the GitLab Pages will be served
1. A separate domain 1. (Optional) Have a wildcard certificate for that domain if you decide to serve
1. A separate Nginx configuration file which needs to be explicitly added in Pages under HTTPS
the server under which GitLab EE runs (Omnibus does that automatically) 1. Configure a wildcard DNS record
1. (Optional) A wildcard certificate for that domain if you decide to serve 1. (Optional but recommended) Enable [Shared runners](../ci/runners/README.md)
pages under HTTPS so that your users don't have to bring their own
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.
### DNS configuration ### DNS configuration
...@@ -129,21 +67,39 @@ host that GitLab runs. For example, an entry would look like this: ...@@ -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 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. 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 You should not use the GitLab domain to serve user pages. For more information
see the [security section](#security). see the [security section](#security).
[wiki-wildcard-dns]: https://en.wikipedia.org/wiki/Wildcard_DNS_record [wiki-wildcard-dns]: https://en.wikipedia.org/wiki/Wildcard_DNS_record
## Setting up GitLab Pages ## Configuration
Depending on your needs, you can install GitLab Pages in four different ways.
Below are the four scenarios that are described in ### Option 1. Custom domains with HTTPS support
[#configuration-scenarios](#configuration-scenarios).
### 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:** **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 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 `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 `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 ...@@ -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 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] 1. [Restart GitLab][restart]
--- ---
...@@ -197,17 +165,32 @@ Below are the four scenarios that are described in ...@@ -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 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.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] 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:** **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 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 `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 `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 ...@@ -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" 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] 1. [Restart GitLab][restart]
--- ---
...@@ -254,58 +249,29 @@ Below are the four scenarios that are described in ...@@ -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 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.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] 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) | URL scheme | Wildcard certificate | Custom domain with HTTP support | Custom domain with HTTPS support | Secondary IP |
1. Go to the GitLab installation directory: | --- |:---:|:---:|:---:|:---:|:---:|:---:|:---:|
| `https://page.example.io` | yes | no | no | no |
```bash Pages enabled, daemon is enabled and NGINX will proxy all requests to the
cd /home/git/gitlab daemon. Pages daemon doesn't listen to the outside world.
```
1. Edit `gitlab.yml` and under the `pages` setting, set `enabled` to `true` and **Source installations:**
the `host` to the FQDN under which GitLab Pages will be served:
```yaml 1. Install the Pages daemon:
## GitLab Pages
pages:
enabled: true
# The location where pages are stored (default: shared/pages).
# path: shared/pages
host: example.io
port: 80
https: false
``` ```
cd /home/git
1. Make sure to [configure NGINX](#nginx-configuration) properly. sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-pages.git
1. [Restart GitLab][restart] cd gitlab-pages
sudo -u git -H git checkout v0.2.1
--- sudo -u git -H make
**Omnibus installations:**
1. Set the external URL for GitLab Pages in `/etc/gitlab/gitlab.rb`:
```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)
1. In `gitlab.yml`, set the port to `443` and https to `true`: 1. In `gitlab.yml`, set the port to `443` and https to `true`:
```bash ```bash
...@@ -320,7 +286,14 @@ Below are the four scenarios that are described in ...@@ -320,7 +286,14 @@ Below are the four scenarios that are described in
https: true 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 ...@@ -342,49 +315,76 @@ Below are the four scenarios that are described in
1. [Reconfigure GitLab][reconfigure] 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. | URL scheme | Wildcard certificate | Custom domain with HTTP support | Custom domain with HTTPS support | Secondary IP |
Specifically you must change the domain name and the IP address where NGINX | --- |:---:|:---:|:---:|:---:|:---:|:---:|:---:|
listens to. Read the following sections for more details. | `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 1. Install the Pages daemon:
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. ```
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), 1. Edit `gitlab.yml` and under the `pages` setting, set `enabled` to `true` and
if you have the secondary IP address configured on the same server as GitLab, the `host` to the FQDN under which GitLab Pages will be served:
you need to change **all** NGINX configs to listen on the first IP address.
**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 NGINX
1. [Restart GitLab][restart]
---
**Omnibus installations:** **Omnibus installations:**
1. Edit `/etc/gitlab/gilab.rb`: 1. Set the external URL for GitLab Pages in `/etc/gitlab/gitlab.rb`:
``` ```ruby
nginx['listen_addresses'] = ['1.1.1.1'] pages_external_url 'http://example.io'
``` ```
1. [Reconfigure GitLab][reconfigure] 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 Be extra careful when setting up the domain name in the NGINX config. You must
not remove the backslashes. not remove the backslashes.
...@@ -462,35 +462,35 @@ latest previous version. ...@@ -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])** **GitLab 8.5 ([documentation][8-5-docs])**
- In GitLab 8.5 we introduced the [gitlab-pages][] daemon which is now the - In GitLab 8.5 we introduced the [gitlab-pages][] daemon which is now the
recommended way to set up GitLab Pages. recommended way to set up GitLab Pages.
- The [NGINX configs][] have changed to reflect this change. So make sure to - The [NGINX configs][] have changed to reflect this change. So make sure to
update them. update them.
- Custom CNAME and TLS certificates support - Custom CNAME and TLS certificates support.
- Documentation was moved to one place - 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
--- ---
**GitLab 8.4** **GitLab 8.3 ([documentation][8-3-docs])**
No new changes.
---
**GitLab 8.3 ([source docs][8-3-docs], [Omnibus docs][8-3-omnidocs])**
- GitLab Pages feature was introduced. - 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-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 [backup]: ../raketasks/backup_restore.md
[ee-80]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/80 [ee-80]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/80
[ee-173]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/173 [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 [reconfigure]: ../administration/restart_gitlab.md#omnibus-gitlab-reconfigure
[restart]: ../administration/restart_gitlab.md#installations-from-source [restart]: ../administration/restart_gitlab.md#installations-from-source
[gitlab-pages]: https://gitlab.com/gitlab-org/gitlab-pages/tree/v0.2.1
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7