2015-12-17 16:03:38 +00:00
|
|
|
# GitLab Pages Administration
|
|
|
|
|
2016-02-21 10:17:36 +00:00
|
|
|
> **Note:**
|
2016-02-21 15:34:18 +00:00
|
|
|
> 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.
|
|
|
|
|
|
|
|
---
|
2016-02-21 10:17:36 +00:00
|
|
|
|
|
|
|
This document describes how to set up the _latest_ GitLab Pages feature. Make
|
|
|
|
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.
|
2015-12-17 16:03:38 +00:00
|
|
|
|
|
|
|
If you are looking for ways to upload your static content in GitLab Pages, you
|
|
|
|
probably want to read the [user documentation](README.md).
|
|
|
|
|
2016-02-21 10:17:36 +00:00
|
|
|
[ee-80]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/80
|
2016-02-21 15:35:01 +00:00
|
|
|
[ee-173]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/173
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
|
|
|
|
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
|
|
|
|
**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
|
|
|
|
|
2016-02-21 18:53:20 +00:00
|
|
|
- [The GitLab Pages daemon](#the-gitlab-pages-daemon)
|
|
|
|
- [Install the Pages daemon](#install-the-pages-daemon)
|
2016-02-21 15:35:01 +00:00
|
|
|
- [Configuration](#configuration)
|
2016-02-21 18:53:20 +00:00
|
|
|
- [Configuration scenarios](#configuration-scenarios)
|
2016-02-21 15:35:01 +00:00
|
|
|
- [DNS configuration](#dns-configuration)
|
2016-02-21 18:53:20 +00:00
|
|
|
- [Custom domains without TLS](#custom-domains-without-tls)
|
|
|
|
- [Custom domains with TLS](#custom-domains-with-tls)
|
|
|
|
- [Installations from source](#installations-from-source)
|
2016-02-21 15:35:01 +00:00
|
|
|
- [Running GitLab Pages with HTTPS](#running-gitlab-pages-with-https)
|
2016-02-21 18:53:20 +00:00
|
|
|
- [Omnibus package installations](#omnibus-package-installations)
|
2016-02-21 15:35:01 +00:00
|
|
|
- [Set maximum pages size](#set-maximum-pages-size)
|
|
|
|
- [Change storage path](#change-storage-path)
|
|
|
|
- [Backup](#backup)
|
|
|
|
- [Security](#security)
|
|
|
|
- [Changelog](#changelog)
|
|
|
|
|
|
|
|
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
2016-02-20 22:41:08 +00:00
|
|
|
|
2016-02-21 18:52:15 +00:00
|
|
|
## The GitLab Pages daemon
|
2016-02-20 22:41:08 +00:00
|
|
|
|
2016-02-21 18:52:15 +00:00
|
|
|
Starting from GitLab EE 8.5, Pages make use of a separate tool ([gitlab-pages]),
|
|
|
|
a simple HTTP server written in Go that serves GitLab Pages with CNAMEs and SNI
|
|
|
|
using HTTP/HTTP2. You are encouraged to read its [README][pages-readme] to fully
|
|
|
|
understand how it works.
|
|
|
|
|
|
|
|
What 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
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
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 the same IP
|
|
|
|
but on different ports. In that case, you will have to proxy the traffic with
|
|
|
|
a loadbalancer.
|
|
|
|
1. Run the pages daemon in a separate server. In that case, the Pages [`path`]
|
|
|
|
must also be present in the server that the pages daemon is installed, so
|
|
|
|
you will have to share it via network.
|
|
|
|
|
|
|
|
[`path`]: https://gitlab.com/gitlab-org/gitlab-ee/blob/8-5-stable-ee/config/gitlab.yml.example#L155
|
|
|
|
|
|
|
|
### Install the Pages daemon
|
|
|
|
|
|
|
|
**Install the Pages daemon on a source installation**
|
|
|
|
|
|
|
|
```
|
|
|
|
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 0.2.0
|
|
|
|
sudo -u git -H make
|
|
|
|
```
|
|
|
|
|
|
|
|
**Install the Pages daemon on Omnibus**
|
|
|
|
|
|
|
|
The `gitlab-pages` daemon is included in the Omnibus package.
|
2016-02-21 10:27:50 +00:00
|
|
|
|
|
|
|
[pages-readme]: https://gitlab.com/gitlab-org/gitlab-pages/blob/master/README.md
|
2016-02-20 22:41:08 +00:00
|
|
|
|
2015-12-17 16:03:38 +00:00
|
|
|
## Configuration
|
|
|
|
|
2016-02-21 18:52:53 +00:00
|
|
|
There are multiple ways to set up GitLab Pages according to what URL scheme you
|
|
|
|
are willing to support. Below you will find all possible scenarios to choose
|
|
|
|
from.
|
|
|
|
|
|
|
|
### Configuration scenarios
|
|
|
|
|
|
|
|
Before proceeding you have to decide what Pages scenario you want to use.
|
|
|
|
Remember that in either scenario, you need:
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
The possible scenarios are depicted in the table below.
|
|
|
|
|
|
|
|
| URL scheme | Option | Wildcard certificate | Pages daemon | Custom domain with HTTP support | Custom domain with HTTPS support | Secondary IP |
|
|
|
|
| --- |:---:|:---:|:---:|:---:|:---:|:---:|:---:|
|
|
|
|
| `http://page.gitlab.io` | 1 | no | no | no | no | no |
|
|
|
|
| `https://page.gitlab.io` | 1 | yes | no | no | no | no |
|
|
|
|
| `http://page.gitlab.io` and `http://page.com` | 2 | no | yes | yes | no | yes |
|
|
|
|
| `https://page.gitlab.io` and `https://page.com` | 2 | yes | yes | yes/no | 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.
|
2015-12-17 16:03:38 +00:00
|
|
|
|
|
|
|
### DNS configuration
|
|
|
|
|
2015-12-18 11:40:55 +00:00
|
|
|
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:
|
2015-12-17 16:03:38 +00:00
|
|
|
|
|
|
|
```
|
2015-12-18 11:40:55 +00:00
|
|
|
*.gitlab.io. 60 IN A 1.2.3.4
|
2015-12-17 16:03:38 +00:00
|
|
|
```
|
|
|
|
|
2015-12-18 11:40:55 +00:00
|
|
|
where `gitlab.io` is the domain under which GitLab Pages will be served
|
2015-12-17 16:03:38 +00:00
|
|
|
and `1.2.3.4` is the IP address of your GitLab instance.
|
|
|
|
|
2015-12-18 16:08:41 +00:00
|
|
|
You should not use the GitLab domain to serve user pages. For more information
|
|
|
|
see the [security section](#security).
|
2015-12-17 16:03:38 +00:00
|
|
|
|
|
|
|
### Omnibus package installations
|
|
|
|
|
|
|
|
See the relevant documentation at <http://doc.gitlab.com/omnibus/settings/pages.html>.
|
|
|
|
|
|
|
|
### Installations from source
|
|
|
|
|
|
|
|
1. Go to the GitLab installation directory:
|
|
|
|
|
2015-12-17 17:38:21 +00:00
|
|
|
```bash
|
|
|
|
cd /home/git/gitlab
|
|
|
|
```
|
|
|
|
|
2015-12-17 17:56:07 +00:00
|
|
|
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:
|
2015-12-17 17:38:21 +00:00
|
|
|
|
2015-12-18 00:20:29 +00:00
|
|
|
```yaml
|
2015-12-17 17:38:21 +00:00
|
|
|
## GitLab Pages
|
|
|
|
pages:
|
|
|
|
enabled: true
|
|
|
|
# The location where pages are stored (default: shared/pages).
|
|
|
|
# path: shared/pages
|
|
|
|
|
|
|
|
# The domain under which the pages are served:
|
|
|
|
# http://group.example.com/project
|
|
|
|
# or project path can be a group page: group.example.com
|
2015-12-18 11:40:55 +00:00
|
|
|
host: gitlab.io
|
2015-12-17 17:38:21 +00:00
|
|
|
port: 80 # Set to 443 if you serve the pages with HTTPS
|
|
|
|
https: false # Set to true if you serve the pages with HTTPS
|
2015-12-17 16:03:38 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
1. Make sure you have copied the new `gitlab-pages` Nginx configuration file:
|
|
|
|
|
2015-12-17 17:38:21 +00:00
|
|
|
```bash
|
|
|
|
sudo cp lib/support/nginx/gitlab-pages /etc/nginx/sites-available/gitlab-pages.conf
|
|
|
|
sudo ln -sf /etc/nginx/sites-{available,enabled}/gitlab-pages.conf
|
|
|
|
```
|
2015-12-17 16:03:38 +00:00
|
|
|
|
2015-12-17 17:38:21 +00:00
|
|
|
Don't forget to add your domain name in the Nginx config. For example if
|
2015-12-18 11:40:55 +00:00
|
|
|
your GitLab pages domain is `gitlab.io`, replace
|
2015-12-17 16:03:38 +00:00
|
|
|
|
2015-12-17 17:38:21 +00:00
|
|
|
```bash
|
2015-12-18 11:18:11 +00:00
|
|
|
server_name ~^(?<group>.*)\.YOUR_GITLAB_PAGES\.DOMAIN$;
|
2015-12-17 17:38:21 +00:00
|
|
|
```
|
2015-12-17 16:03:38 +00:00
|
|
|
|
2015-12-17 17:38:21 +00:00
|
|
|
with
|
2015-12-17 16:03:38 +00:00
|
|
|
|
2015-12-17 17:38:21 +00:00
|
|
|
```
|
2015-12-18 12:09:14 +00:00
|
|
|
server_name ~^(?<group>.*)\.gitlabpages\.com$;
|
2015-12-17 17:38:21 +00:00
|
|
|
```
|
2015-12-17 16:03:38 +00:00
|
|
|
|
2015-12-18 12:09:14 +00:00
|
|
|
You must be extra careful to not remove the backslashes. If you are using
|
|
|
|
a subdomain, make sure to escape all dots (`.`) with a backslash (\).
|
|
|
|
For example `pages.gitlab.io` would be:
|
|
|
|
|
|
|
|
```
|
|
|
|
server_name ~^(?<group>.*)\.pages\.gitlab\.io$;
|
|
|
|
```
|
2015-12-17 16:03:38 +00:00
|
|
|
|
|
|
|
1. Restart Nginx and GitLab:
|
|
|
|
|
2015-12-17 17:38:21 +00:00
|
|
|
```bash
|
|
|
|
sudo service nginx restart
|
|
|
|
sudo service gitlab restart
|
|
|
|
```
|
2015-12-17 16:03:38 +00:00
|
|
|
|
2015-12-17 23:57:32 +00:00
|
|
|
### Running GitLab Pages with HTTPS
|
2015-12-17 16:03:38 +00:00
|
|
|
|
|
|
|
If you want the pages to be served under HTTPS, a wildcard SSL certificate is
|
|
|
|
required.
|
|
|
|
|
|
|
|
1. In `gitlab.yml`, set the port to `443` and https to `true`:
|
|
|
|
|
2015-12-17 17:38:21 +00:00
|
|
|
```bash
|
|
|
|
## GitLab Pages
|
|
|
|
pages:
|
|
|
|
enabled: true
|
|
|
|
# The location where pages are stored (default: shared/pages).
|
|
|
|
# path: shared/pages
|
|
|
|
|
|
|
|
# The domain under which the pages are served:
|
|
|
|
# http://group.example.com/project
|
|
|
|
# or project path can be a group page: group.example.com
|
2015-12-18 11:40:55 +00:00
|
|
|
host: gitlab.io
|
2015-12-17 17:38:21 +00:00
|
|
|
port: 443 # Set to 443 if you serve the pages with HTTPS
|
|
|
|
https: true # Set to true if you serve the pages with HTTPS
|
2015-12-17 16:03:38 +00:00
|
|
|
```
|
2015-12-18 11:40:34 +00:00
|
|
|
|
2015-12-17 17:38:21 +00:00
|
|
|
1. Copy the `gitlab-pages-ssl` Nginx configuration file:
|
2015-12-17 16:03:38 +00:00
|
|
|
|
2015-12-17 17:38:21 +00:00
|
|
|
```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.conf
|
|
|
|
```
|
2015-12-17 16:03:38 +00:00
|
|
|
|
2015-12-17 17:38:21 +00:00
|
|
|
Make sure to edit the config to add your domain as well as correctly point
|
2015-12-18 11:40:55 +00:00
|
|
|
to the right location of the SSL certificate files. Restart Nginx for the
|
|
|
|
changes to take effect.
|
2015-12-17 16:03:38 +00:00
|
|
|
|
|
|
|
## Set maximum pages size
|
|
|
|
|
2015-12-18 11:40:55 +00:00
|
|
|
The maximum size of the unpacked archive per project can be configured in the
|
|
|
|
Admin area under the Application settings in the **Maximum size of pages (MB)**.
|
2015-12-17 16:03:38 +00:00
|
|
|
The default is 100MB.
|
|
|
|
|
2015-12-18 00:20:29 +00:00
|
|
|
## Change storage path
|
|
|
|
|
|
|
|
Pages are stored by default in `/home/git/gitlab/shared/pages`.
|
|
|
|
If you wish to store them in another location you must set it up in
|
|
|
|
`gitlab.yml` under the `pages` section:
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
pages:
|
|
|
|
enabled: true
|
|
|
|
# The location where pages are stored (default: shared/pages).
|
|
|
|
path: /mnt/storage/pages
|
|
|
|
```
|
|
|
|
|
|
|
|
Restart GitLab for the changes to take effect:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
sudo service gitlab restart
|
|
|
|
```
|
|
|
|
|
2015-12-17 17:38:21 +00:00
|
|
|
## Backup
|
2015-12-17 16:03:38 +00:00
|
|
|
|
2015-12-17 17:38:21 +00:00
|
|
|
Pages are part of the regular backup so there is nothing to configure.
|
2015-12-17 16:03:38 +00:00
|
|
|
|
2015-12-17 17:38:21 +00:00
|
|
|
## Security
|
2015-12-17 16:03:38 +00:00
|
|
|
|
2015-12-17 17:38:21 +00:00
|
|
|
You should strongly consider running GitLab pages under a different hostname
|
|
|
|
than GitLab to prevent XSS attacks.
|
2015-12-17 16:03:38 +00:00
|
|
|
|
2016-02-21 10:17:36 +00:00
|
|
|
## Changelog
|
|
|
|
|
|
|
|
GitLab Pages were first introduced in GitLab EE 8.3. Since then, many features
|
|
|
|
where added, like custom CNAME and TLS support, and many more are likely to
|
2016-02-21 15:36:34 +00:00
|
|
|
come. Below is a brief changelog. If no changes were introduced or a version is
|
|
|
|
missing from the changelog, assume that the documentation is the same as the
|
|
|
|
latest previous version.
|
2016-02-21 10:17:36 +00:00
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
**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
|
|
|
|
|
|
|
|
[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.0
|
|
|
|
[NGINX configs]: https://gitlab.com/gitlab-org/gitlab-ee/tree/8-5-stable-ee/lib/support/nginx
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
**GitLab 8.4**
|
|
|
|
|
|
|
|
No new changes.
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
**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
|
|
|
|
|
|
|
|
---
|