9.0 KiB

Raw Blame History

GitLab Pages Administration

Note: This feature was first introduced in GitLab EE 8.3. Custom CNAMEs with TLS support were introduced in GitLab EE 8.5.

This document describes how to set up the latest GitLab Pages feature. Make sure to read the 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.

Table of Contents generated with DocToc

Architecture
Configuration
Set maximum pages size
Change storage path
Backup
Security
Changelog

The GitLab Pages daemon

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 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:

Run the pages daemon in the same server as GitLab, listening on a secondary IP
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.
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.

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.

Configuration

There are a couple of things to consider before enabling GitLab pages in your GitLab EE instance.

You need to properly configure your DNS to point to the domain that pages will be served
Pages use a separate Nginx configuration file which needs to be explicitly added in the server under which GitLab EE runs
Optionally but recommended, you can add some shared runners so that your users don't have to bring their own.

Both of these settings are described in detail in the sections below.

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:

*.gitlab.io. 60 IN A 1.2.3.4

where gitlab.io is the domain under which GitLab Pages will be served and 1.2.3.4 is the IP address of your GitLab instance.

You should not use the GitLab domain to serve user pages. For more information see the security section.

Omnibus package installations

See the relevant documentation at http://doc.gitlab.com/omnibus/settings/pages.html.

Installations from source

Go to the GitLab installation directory:
```
cd /home/git/gitlab
```

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:

## 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
  host: gitlab.io
  port: 80 # Set to 443 if you serve the pages with HTTPS
  https: false # Set to true if you serve the pages with HTTPS

Make sure you have copied the new gitlab-pages Nginx configuration file:
```
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
```
Don't forget to add your domain name in the Nginx config. For example if your GitLab pages domain is gitlab.io, replace
```
server_name ~^(?<group>.*)\.YOUR_GITLAB_PAGES\.DOMAIN$;
```
with
```
server_name ~^(?<group>.*)\.gitlabpages\.com$;
```
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$;
```

Restart Nginx and GitLab:

sudo service nginx restart
sudo service gitlab restart

Running GitLab Pages with HTTPS

If you want the pages to be served under HTTPS, a wildcard SSL certificate is required.

In gitlab.yml, set the port to 443 and https to true:

## 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
  host: gitlab.io
  port: 443 # Set to 443 if you serve the pages with HTTPS
  https: true # Set to true if you serve the pages with HTTPS

Copy the gitlab-pages-ssl Nginx configuration file:
```
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
```
Make sure to edit the config to add your domain as well as correctly point to the right location of the SSL certificate files. Restart Nginx for the changes to take effect.

Set maximum pages size

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). The default is 100MB.

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:

pages:
  enabled: true
  # The location where pages are stored (default: shared/pages).
  path: /mnt/storage/pages

Restart GitLab for the changes to take effect:

sudo service gitlab restart

Backup

Pages are part of the regular backup so there is nothing to configure.

Security

You should strongly consider running GitLab pages under a different hostname than GitLab to prevent XSS attacks.

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 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.

GitLab 8.5 (documentation)

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

GitLab 8.4

No new changes.

GitLab 8.3 (documentation)

GitLab Pages feature was introduced.

9.0 KiB Raw Blame History