Move Pages docs to new location
|
@ -12,7 +12,7 @@
|
||||||
- [GitLab as OAuth2 authentication service provider](integration/oauth_provider.md). It allows you to login to other applications from GitLab.
|
- [GitLab as OAuth2 authentication service provider](integration/oauth_provider.md). It allows you to login to other applications from GitLab.
|
||||||
- [Container Registry](user/project/container_registry.md) Learn how to use GitLab Container Registry.
|
- [Container Registry](user/project/container_registry.md) Learn how to use GitLab Container Registry.
|
||||||
- [GitLab basics](gitlab-basics/README.md) Find step by step how to start working on your commandline and on GitLab.
|
- [GitLab basics](gitlab-basics/README.md) Find step by step how to start working on your commandline and on GitLab.
|
||||||
- [GitLab Pages](pages/README.md) Using GitLab Pages.
|
- [GitLab Pages](user/project/pages/index.md) Using GitLab Pages.
|
||||||
- [Importing to GitLab](workflow/importing/README.md) Import your projects from GitHub, Bitbucket, GitLab.com, FogBugz and SVN into GitLab.
|
- [Importing to GitLab](workflow/importing/README.md) Import your projects from GitHub, Bitbucket, GitLab.com, FogBugz and SVN into GitLab.
|
||||||
- [Importing and exporting projects between instances](user/project/settings/import_export.md).
|
- [Importing and exporting projects between instances](user/project/settings/import_export.md).
|
||||||
- [Markdown](user/markdown.md) GitLab's advanced formatting system.
|
- [Markdown](user/markdown.md) GitLab's advanced formatting system.
|
||||||
|
@ -54,7 +54,7 @@
|
||||||
- [Migrate GitLab CI to CE/EE](migrate_ci_to_ce/README.md) Follow this guide to migrate your existing GitLab CI data to GitLab CE/EE.
|
- [Migrate GitLab CI to CE/EE](migrate_ci_to_ce/README.md) Follow this guide to migrate your existing GitLab CI data to GitLab CE/EE.
|
||||||
- [Git LFS configuration](workflow/lfs/lfs_administration.md)
|
- [Git LFS configuration](workflow/lfs/lfs_administration.md)
|
||||||
- [Housekeeping](administration/housekeeping.md) Keep your Git repository tidy and fast.
|
- [Housekeeping](administration/housekeeping.md) Keep your Git repository tidy and fast.
|
||||||
- [GitLab Pages configuration](pages/administration.md)
|
- [GitLab Pages configuration](administration/pages/index.md) Configure GitLab Pages.
|
||||||
- [GitLab performance monitoring with InfluxDB](administration/monitoring/performance/introduction.md) Configure GitLab and InfluxDB for measuring performance metrics.
|
- [GitLab performance monitoring with InfluxDB](administration/monitoring/performance/introduction.md) Configure GitLab and InfluxDB for measuring performance metrics.
|
||||||
- [GitLab performance monitoring with Prometheus](administration/monitoring/performance/prometheus.md) Configure GitLab and Prometheus for measuring performance metrics.
|
- [GitLab performance monitoring with Prometheus](administration/monitoring/performance/prometheus.md) Configure GitLab and Prometheus for measuring performance metrics.
|
||||||
- [Request Profiling](administration/monitoring/performance/request_profiling.md) Get a detailed profile on slow requests.
|
- [Request Profiling](administration/monitoring/performance/request_profiling.md) Get a detailed profile on slow requests.
|
||||||
|
|
|
@ -66,4 +66,4 @@ Read more on high-availability configuration:
|
||||||
configure custom domains with custom SSL, which would not be possible
|
configure custom domains with custom SSL, which would not be possible
|
||||||
if SSL was terminated at the load balancer.
|
if SSL was terminated at the load balancer.
|
||||||
|
|
||||||
[gitlab-pages]: http://docs.gitlab.com/ee/pages/administration.html
|
[gitlab-pages]: ../pages/index.md
|
||||||
|
|
|
@ -0,0 +1,497 @@
|
||||||
|
# GitLab Pages Administration
|
||||||
|
|
||||||
|
> **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.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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
|
||||||
|
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.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
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 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.
|
||||||
|
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. If you choose that route note that you should use TCP load
|
||||||
|
balancing for HTTPS. If you use TLS-termination (HTTPS-load balancing) the
|
||||||
|
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.
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
Before proceeding with the Pages configuration, you will need to:
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
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.2.3.4
|
||||||
|
```
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
Depending on your needs, you can install GitLab Pages in four different ways.
|
||||||
|
|
||||||
|
### 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:
|
||||||
|
|
||||||
|
```
|
||||||
|
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
|
||||||
|
daemon will listen for connections:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
## GitLab Pages
|
||||||
|
pages:
|
||||||
|
enabled: true
|
||||||
|
# The location where pages are stored (default: shared/pages).
|
||||||
|
# path: shared/pages
|
||||||
|
|
||||||
|
host: example.io
|
||||||
|
port: 443
|
||||||
|
https: true
|
||||||
|
|
||||||
|
external_http: 1.1.1.1:80
|
||||||
|
external_https: 1.1.1.1: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.1:80 -listen-https 1.1.1.1: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
|
||||||
|
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/gitlab.rb`:
|
||||||
|
|
||||||
|
```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'
|
||||||
|
```
|
||||||
|
|
||||||
|
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]
|
||||||
|
|
||||||
|
### 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:
|
||||||
|
|
||||||
|
```
|
||||||
|
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
|
||||||
|
for connections:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
pages:
|
||||||
|
enabled: true
|
||||||
|
# The location where pages are stored (default: shared/pages).
|
||||||
|
# path: shared/pages
|
||||||
|
|
||||||
|
host: example.io
|
||||||
|
port: 80
|
||||||
|
https: false
|
||||||
|
|
||||||
|
external_http: 1.1.1.1:80
|
||||||
|
```
|
||||||
|
|
||||||
|
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` and `-listen-http` must match the `host` and `external_http`
|
||||||
|
settings that you set above respectively:
|
||||||
|
|
||||||
|
```
|
||||||
|
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.1:80"
|
||||||
|
```
|
||||||
|
|
||||||
|
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/gitlab.rb`:
|
||||||
|
|
||||||
|
```ruby
|
||||||
|
pages_external_url "http://example.io"
|
||||||
|
nginx['listen_addresses'] = ['1.1.1.1']
|
||||||
|
pages_nginx['enable'] = false
|
||||||
|
gitlab_pages['external_http'] = '1.1.1.2:80'
|
||||||
|
```
|
||||||
|
|
||||||
|
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]
|
||||||
|
|
||||||
|
### Option 3. Wildcard HTTPS domain without custom domains
|
||||||
|
|
||||||
|
| 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.
|
||||||
|
|
||||||
|
**Source installations:**
|
||||||
|
|
||||||
|
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. 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
|
||||||
|
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.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Omnibus installations:**
|
||||||
|
|
||||||
|
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'
|
||||||
|
|
||||||
|
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 `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.
|
||||||
|
|
||||||
|
**Source installations:**
|
||||||
|
|
||||||
|
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. 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. 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]
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**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]
|
||||||
|
|
||||||
|
## 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.
|
||||||
|
|
||||||
|
If your GitLab pages domain is `example.io`, replace:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
server_name ~^.*\.YOUR_GITLAB_PAGES\.DOMAIN$;
|
||||||
|
```
|
||||||
|
|
||||||
|
with:
|
||||||
|
|
||||||
|
```
|
||||||
|
server_name ~^.*\.example\.io$;
|
||||||
|
```
|
||||||
|
|
||||||
|
If you are using a subdomain, make sure to escape all dots (`.`) except from
|
||||||
|
the first one with a backslash (\). For example `pages.example.io` would be:
|
||||||
|
|
||||||
|
```
|
||||||
|
server_name ~^.*\.pages\.example\.io$;
|
||||||
|
```
|
||||||
|
|
||||||
|
## 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
|
||||||
|
|
||||||
|
**Source installations:**
|
||||||
|
|
||||||
|
1. 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
|
||||||
|
```
|
||||||
|
|
||||||
|
1. [Restart GitLab][restart]
|
||||||
|
|
||||||
|
**Omnibus installations:**
|
||||||
|
|
||||||
|
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`:
|
||||||
|
|
||||||
|
```ruby
|
||||||
|
gitlab_rails['pages_path'] = "/mnt/storage/pages"
|
||||||
|
```
|
||||||
|
|
||||||
|
1. [Reconfigure GitLab][reconfigure]
|
||||||
|
|
||||||
|
## Backup
|
||||||
|
|
||||||
|
Pages are part of the [regular backup][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.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.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**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-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/administration/pages/index.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
|
||||||
|
[pages-userguide]: ../../user/project/pages/index.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
|
|
@ -489,7 +489,7 @@ Make sure to edit the config file to match your setup. Also, ensure that you mat
|
||||||
|
|
||||||
If you intend to enable GitLab pages, there is a separate Nginx config you need
|
If you intend to enable GitLab pages, there is a separate Nginx config you need
|
||||||
to use. Read all about the needed configuration at the
|
to use. Read all about the needed configuration at the
|
||||||
[GitLab Pages administration guide](../pages/administration.md).
|
[GitLab Pages administration guide](../administration/pages/index.md).
|
||||||
|
|
||||||
**Note:** If you want to use HTTPS, replace the `gitlab` Nginx config with `gitlab-ssl`. See [Using HTTPS](#using-https) for HTTPS configuration details.
|
**Note:** If you want to use HTTPS, replace the `gitlab` Nginx config with `gitlab-ssl`. See [Using HTTPS](#using-https) for HTTPS configuration details.
|
||||||
|
|
||||||
|
|
|
@ -1,435 +1 @@
|
||||||
# GitLab Pages
|
This document was moved to [user/project/pages](../user/project/pages).
|
||||||
|
|
||||||
> **Note:**
|
|
||||||
> This feature was [introduced][ee-80] in GitLab EE 8.3.
|
|
||||||
> Custom CNAMEs with TLS support were [introduced][ee-173] in GitLab EE 8.5.
|
|
||||||
|
|
||||||
> **Note:**
|
|
||||||
> This document is about the user guide. To learn how to enable GitLab Pages
|
|
||||||
> across your GitLab instance, visit the [administrator documentation](administration.md).
|
|
||||||
|
|
||||||
With GitLab Pages you can host for free your static websites on GitLab.
|
|
||||||
Combined with the power of [GitLab CI] and the help of [GitLab Runner] you can
|
|
||||||
deploy static pages for your individual projects, your user or your group.
|
|
||||||
|
|
||||||
Read [GitLab Pages on GitLab.com](#gitlab-pages-on-gitlab-com) for specific
|
|
||||||
information, if you are using GitLab.com to host your website.
|
|
||||||
|
|
||||||
## Getting started with GitLab Pages
|
|
||||||
|
|
||||||
> **Note:**
|
|
||||||
> In the rest of this document we will assume that the general domain name that
|
|
||||||
> is used for GitLab Pages is `example.io`.
|
|
||||||
|
|
||||||
In general there are two types of pages one might create:
|
|
||||||
|
|
||||||
- Pages per user (`username.example.io`) or per group (`groupname.example.io`)
|
|
||||||
- Pages per project (`username.example.io/projectname` or `groupname.example.io/projectname`)
|
|
||||||
|
|
||||||
In GitLab, usernames and groupnames are unique and we often refer to them
|
|
||||||
as namespaces. There can be only one namespace in a GitLab instance. Below you
|
|
||||||
can see the connection between the type of GitLab Pages, what the project name
|
|
||||||
that is created on GitLab looks like and the website URL it will be ultimately
|
|
||||||
be served on.
|
|
||||||
|
|
||||||
| Type of GitLab Pages | The name of the project created in GitLab | Website URL |
|
|
||||||
| -------------------- | ------------ | ----------- |
|
|
||||||
| User pages | `username.example.io` | `http(s)://username.example.io` |
|
|
||||||
| Group pages | `groupname.example.io` | `http(s)://groupname.example.io` |
|
|
||||||
| Project pages owned by a user | `projectname` | `http(s)://username.example.io/projectname` |
|
|
||||||
| Project pages owned by a group | `projectname` | `http(s)://groupname.example.io/projectname`|
|
|
||||||
|
|
||||||
> **Warning:**
|
|
||||||
> There are some known [limitations](#limitations) regarding namespaces served
|
|
||||||
> under the general domain name and HTTPS. Make sure to read that section.
|
|
||||||
|
|
||||||
### GitLab Pages requirements
|
|
||||||
|
|
||||||
In brief, this is what you need to upload your website in GitLab Pages:
|
|
||||||
|
|
||||||
1. Find out the general domain name that is used for GitLab Pages
|
|
||||||
(ask your administrator). This is very important, so you should first make
|
|
||||||
sure you get that right.
|
|
||||||
1. Create a project
|
|
||||||
1. Push a [`.gitlab-ci.yml` file](../ci/yaml/README.md) in the root directory
|
|
||||||
of your repository with a specific job named [`pages`][pages]
|
|
||||||
1. Set up a GitLab Runner to build your website
|
|
||||||
|
|
||||||
> **Note:**
|
|
||||||
> If [shared runners](../ci/runners/README.md) are enabled by your GitLab
|
|
||||||
> administrator, you should be able to use them instead of bringing your own.
|
|
||||||
|
|
||||||
### User or group Pages
|
|
||||||
|
|
||||||
For user and group pages, the name of the project should be specific to the
|
|
||||||
username or groupname and the general domain name that is used for GitLab Pages.
|
|
||||||
Head over your GitLab instance that supports GitLab Pages and create a
|
|
||||||
repository named `username.example.io`, where `username` is your username on
|
|
||||||
GitLab. If the first part of the project name doesn't match exactly your
|
|
||||||
username, it won’t work, so make sure to get it right.
|
|
||||||
|
|
||||||
To create a group page, the steps are the same like when creating a website for
|
|
||||||
users. Just make sure that you are creating the project within the group's
|
|
||||||
namespace.
|
|
||||||
|
|
||||||
![Create a user-based pages project](img/pages_create_user_page.png)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
After you push some static content to your repository and GitLab Runner uploads
|
|
||||||
the artifacts to GitLab CI, you will be able to access your website under
|
|
||||||
`http(s)://username.example.io`. Keep reading to find out how.
|
|
||||||
|
|
||||||
>**Note:**
|
|
||||||
If your username/groupname contains a dot, for example `foo.bar`, you will not
|
|
||||||
be able to use the wildcard domain HTTPS, read more at [limitations](#limitations).
|
|
||||||
|
|
||||||
### Project Pages
|
|
||||||
|
|
||||||
GitLab Pages for projects can be created by both user and group accounts.
|
|
||||||
The steps to create a project page for a user or a group are identical:
|
|
||||||
|
|
||||||
1. Create a new project
|
|
||||||
1. Push a [`.gitlab-ci.yml` file](../ci/yaml/README.md) in the root directory
|
|
||||||
of your repository with a specific job named [`pages`][pages].
|
|
||||||
1. Set up a GitLab Runner to build your website
|
|
||||||
|
|
||||||
A user's project will be served under `http(s)://username.example.io/projectname`
|
|
||||||
whereas a group's project under `http(s)://groupname.example.io/projectname`.
|
|
||||||
|
|
||||||
### Explore the contents of `.gitlab-ci.yml`
|
|
||||||
|
|
||||||
The key thing about GitLab Pages is the `.gitlab-ci.yml` file, something that
|
|
||||||
gives you absolute control over the build process. You can actually watch your
|
|
||||||
website being built live by following the CI build traces.
|
|
||||||
|
|
||||||
> **Note:**
|
|
||||||
> Before reading this section, make sure you familiarize yourself with GitLab CI
|
|
||||||
> and the specific syntax of[`.gitlab-ci.yml`](../ci/yaml/README.md) by
|
|
||||||
> following our [quick start guide](../ci/quick_start/README.md).
|
|
||||||
|
|
||||||
To make use of GitLab Pages, the contents of `.gitlab-ci.yml` must follow the
|
|
||||||
rules below:
|
|
||||||
|
|
||||||
1. A special job named [`pages`][pages] must be defined
|
|
||||||
1. Any static content which will be served by GitLab Pages must be placed under
|
|
||||||
a `public/` directory
|
|
||||||
1. `artifacts` with a path to the `public/` directory must be defined
|
|
||||||
|
|
||||||
In its simplest form, `.gitlab-ci.yml` looks like:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
pages:
|
|
||||||
script:
|
|
||||||
- my_commands
|
|
||||||
artifacts:
|
|
||||||
paths:
|
|
||||||
- public
|
|
||||||
```
|
|
||||||
|
|
||||||
When the Runner reaches to build the `pages` job, it executes whatever is
|
|
||||||
defined in the `script` parameter and if the build completes with a non-zero
|
|
||||||
exit status, it then uploads the `public/` directory to GitLab Pages.
|
|
||||||
|
|
||||||
The `public/` directory should contain all the static content of your website.
|
|
||||||
Depending on how you plan to publish your website, the steps defined in the
|
|
||||||
[`script` parameter](../ci/yaml/README.md#script) may differ.
|
|
||||||
|
|
||||||
Be aware that Pages are by default branch/tag agnostic and their deployment
|
|
||||||
relies solely on what you specify in `.gitlab-ci.yml`. If you don't limit the
|
|
||||||
`pages` job with the [`only` parameter](../ci/yaml/README.md#only-and-except),
|
|
||||||
whenever a new commit is pushed to whatever branch or tag, the Pages will be
|
|
||||||
overwritten. In the example below, we limit the Pages to be deployed whenever
|
|
||||||
a commit is pushed only on the `master` branch:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
pages:
|
|
||||||
script:
|
|
||||||
- my_commands
|
|
||||||
artifacts:
|
|
||||||
paths:
|
|
||||||
- public
|
|
||||||
only:
|
|
||||||
- master
|
|
||||||
```
|
|
||||||
|
|
||||||
We then tell the Runner to treat the `public/` directory as `artifacts` and
|
|
||||||
upload it to GitLab. And since all these parameters were all under a `pages`
|
|
||||||
job, the contents of the `public` directory will be served by GitLab Pages.
|
|
||||||
|
|
||||||
#### How `.gitlab-ci.yml` looks like when the static content is in your repository
|
|
||||||
|
|
||||||
Supposedly your repository contained the following files:
|
|
||||||
|
|
||||||
```
|
|
||||||
├── index.html
|
|
||||||
├── css
|
|
||||||
│ └── main.css
|
|
||||||
└── js
|
|
||||||
└── main.js
|
|
||||||
```
|
|
||||||
|
|
||||||
Then the `.gitlab-ci.yml` example below simply moves all files from the root
|
|
||||||
directory of the project to the `public/` directory. The `.public` workaround
|
|
||||||
is so `cp` doesn't also copy `public/` to itself in an infinite loop:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
pages:
|
|
||||||
script:
|
|
||||||
- mkdir .public
|
|
||||||
- cp -r * .public
|
|
||||||
- mv .public public
|
|
||||||
artifacts:
|
|
||||||
paths:
|
|
||||||
- public
|
|
||||||
only:
|
|
||||||
- master
|
|
||||||
```
|
|
||||||
|
|
||||||
#### How `.gitlab-ci.yml` looks like when using a static generator
|
|
||||||
|
|
||||||
In general, GitLab Pages support any kind of [static site generator][staticgen],
|
|
||||||
since `.gitlab-ci.yml` can be configured to run any possible command.
|
|
||||||
|
|
||||||
In the root directory of your Git repository, place the source files of your
|
|
||||||
favorite static generator. Then provide a `.gitlab-ci.yml` file which is
|
|
||||||
specific to your static generator.
|
|
||||||
|
|
||||||
The example below, uses [Jekyll] to build the static site:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
image: ruby:2.1 # the script will run in Ruby 2.1 using the Docker image ruby:2.1
|
|
||||||
|
|
||||||
pages: # the build job must be named pages
|
|
||||||
script:
|
|
||||||
- gem install jekyll # we install jekyll
|
|
||||||
- jekyll build -d public/ # we tell jekyll to build the site for us
|
|
||||||
artifacts:
|
|
||||||
paths:
|
|
||||||
- public # this is where the site will live and the Runner uploads it in GitLab
|
|
||||||
only:
|
|
||||||
- master # this script is only affecting the master branch
|
|
||||||
```
|
|
||||||
|
|
||||||
Here, we used the Docker executor and in the first line we specified the base
|
|
||||||
image against which our builds will run.
|
|
||||||
|
|
||||||
You have to make sure that the generated static files are ultimately placed
|
|
||||||
under the `public` directory, that's why in the `script` section we run the
|
|
||||||
`jekyll` command that builds the website and puts all content in the `public/`
|
|
||||||
directory. Depending on the static generator of your choice, this command will
|
|
||||||
differ. Search in the documentation of the static generator you will use if
|
|
||||||
there is an option to explicitly set the output directory. If there is not
|
|
||||||
such an option, you can always add one more line under `script` to rename the
|
|
||||||
resulting directory in `public/`.
|
|
||||||
|
|
||||||
We then tell the Runner to treat the `public/` directory as `artifacts` and
|
|
||||||
upload it to GitLab.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
See the [jekyll example project][pages-jekyll] to better understand how this
|
|
||||||
works.
|
|
||||||
|
|
||||||
For a list of Pages projects, see the [example projects](#example-projects) to
|
|
||||||
get you started.
|
|
||||||
|
|
||||||
#### How to set up GitLab Pages in a repository where there's also actual code
|
|
||||||
|
|
||||||
Remember that GitLab Pages are by default branch/tag agnostic and their
|
|
||||||
deployment relies solely on what you specify in `.gitlab-ci.yml`. You can limit
|
|
||||||
the `pages` job with the [`only` parameter](../ci/yaml/README.md#only-and-except),
|
|
||||||
whenever a new commit is pushed to a branch that will be used specifically for
|
|
||||||
your pages.
|
|
||||||
|
|
||||||
That way, you can have your project's code in the `master` branch and use an
|
|
||||||
orphan branch (let's name it `pages`) that will host your static generator site.
|
|
||||||
|
|
||||||
You can create a new empty branch like this:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git checkout --orphan pages
|
|
||||||
```
|
|
||||||
|
|
||||||
The first commit made on this new branch will have no parents and it will be
|
|
||||||
the root of a new history totally disconnected from all the other branches and
|
|
||||||
commits. Push the source files of your static generator in the `pages` branch.
|
|
||||||
|
|
||||||
Below is a copy of `.gitlab-ci.yml` where the most significant line is the last
|
|
||||||
one, specifying to execute everything in the `pages` branch:
|
|
||||||
|
|
||||||
```
|
|
||||||
image: ruby:2.1
|
|
||||||
|
|
||||||
pages:
|
|
||||||
script:
|
|
||||||
- gem install jekyll
|
|
||||||
- jekyll build -d public/
|
|
||||||
artifacts:
|
|
||||||
paths:
|
|
||||||
- public
|
|
||||||
only:
|
|
||||||
- pages
|
|
||||||
```
|
|
||||||
|
|
||||||
See an example that has different files in the [`master` branch][jekyll-master]
|
|
||||||
and the source files for Jekyll are in a [`pages` branch][jekyll-pages] which
|
|
||||||
also includes `.gitlab-ci.yml`.
|
|
||||||
|
|
||||||
[jekyll-master]: https://gitlab.com/pages/jekyll-branched/tree/master
|
|
||||||
[jekyll-pages]: https://gitlab.com/pages/jekyll-branched/tree/pages
|
|
||||||
|
|
||||||
## Next steps
|
|
||||||
|
|
||||||
So you have successfully deployed your website, congratulations! Let's check
|
|
||||||
what more you can do with GitLab Pages.
|
|
||||||
|
|
||||||
### Example projects
|
|
||||||
|
|
||||||
Below is a list of example projects for GitLab Pages with a plain HTML website
|
|
||||||
or various static site generators. Contributions are very welcome.
|
|
||||||
|
|
||||||
- [Plain HTML](https://gitlab.com/pages/plain-html)
|
|
||||||
- [Jekyll](https://gitlab.com/pages/jekyll)
|
|
||||||
- [Hugo](https://gitlab.com/pages/hugo)
|
|
||||||
- [Middleman](https://gitlab.com/pages/middleman)
|
|
||||||
- [Hexo](https://gitlab.com/pages/hexo)
|
|
||||||
- [Brunch](https://gitlab.com/pages/brunch)
|
|
||||||
- [Metalsmith](https://gitlab.com/pages/metalsmith)
|
|
||||||
- [Harp](https://gitlab.com/pages/harp)
|
|
||||||
|
|
||||||
Visit the GitLab Pages group for a full list of example projects:
|
|
||||||
<https://gitlab.com/groups/pages>.
|
|
||||||
|
|
||||||
### Add a custom domain to your Pages website
|
|
||||||
|
|
||||||
If this setting is enabled by your GitLab administrator, you should be able to
|
|
||||||
see the **New Domain** button when visiting your project's settings through the
|
|
||||||
gear icon in the top right and then navigating to **Pages**.
|
|
||||||
|
|
||||||
![New domain button](img/pages_new_domain_button.png)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
You can add multiple domains pointing to your website hosted under GitLab.
|
|
||||||
Once the domain is added, you can see it listed under the **Domains** section.
|
|
||||||
|
|
||||||
![Pages multiple domains](img/pages_multiple_domains.png)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
As a last step, you need to configure your DNS and add a CNAME pointing to your
|
|
||||||
user/group page. Click on the **Details** button of a domain for further
|
|
||||||
instructions.
|
|
||||||
|
|
||||||
![Pages DNS details](img/pages_dns_details.png)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
>**Note:**
|
|
||||||
Currently there is support only for custom domains on per-project basis. That
|
|
||||||
means that if you add a custom domain (`example.com`) for your user website
|
|
||||||
(`username.example.io`), a project that is served under `username.example.io/foo`,
|
|
||||||
will not be accessible under `example.com/foo`.
|
|
||||||
|
|
||||||
### Secure your custom domain website with TLS
|
|
||||||
|
|
||||||
When you add a new custom domain, you also have the chance to add a TLS
|
|
||||||
certificate. If this setting is enabled by your GitLab administrator, you
|
|
||||||
should be able to see the option to upload the public certificate and the
|
|
||||||
private key when adding a new domain.
|
|
||||||
|
|
||||||
![Pages upload cert](img/pages_upload_cert.png)
|
|
||||||
|
|
||||||
### Custom error codes pages
|
|
||||||
|
|
||||||
You can provide your own 403 and 404 error pages by creating the `403.html` and
|
|
||||||
`404.html` files respectively in the root directory of the `public/` directory
|
|
||||||
that will be included in the artifacts. Usually this is the root directory of
|
|
||||||
your project, but that may differ depending on your static generator
|
|
||||||
configuration.
|
|
||||||
|
|
||||||
If the case of `404.html`, there are different scenarios. For example:
|
|
||||||
|
|
||||||
- If you use project Pages (served under `/projectname/`) and try to access
|
|
||||||
`/projectname/non/exsiting_file`, GitLab Pages will try to serve first
|
|
||||||
`/projectname/404.html`, and then `/404.html`.
|
|
||||||
- If you use user/group Pages (served under `/`) and try to access
|
|
||||||
`/non/existing_file` GitLab Pages will try to serve `/404.html`.
|
|
||||||
- If you use a custom domain and try to access `/non/existing_file`, GitLab
|
|
||||||
Pages will try to serve only `/404.html`.
|
|
||||||
|
|
||||||
### Remove the contents of your pages
|
|
||||||
|
|
||||||
If you ever feel the need to purge your Pages content, you can do so by going
|
|
||||||
to your project's settings through the gear icon in the top right, and then
|
|
||||||
navigating to **Pages**. Hit the **Remove pages** button and your Pages website
|
|
||||||
will be deleted. Simple as that.
|
|
||||||
|
|
||||||
![Remove pages](img/pages_remove.png)
|
|
||||||
|
|
||||||
## GitLab Pages on GitLab.com
|
|
||||||
|
|
||||||
If you are using GitLab.com to host your website, then:
|
|
||||||
|
|
||||||
- The general domain name for GitLab Pages on GitLab.com is `gitlab.io`.
|
|
||||||
- Custom domains and TLS support are enabled.
|
|
||||||
- Shared runners are enabled by default, provided for free and can be used to
|
|
||||||
build your website. If you want you can still bring your own Runner.
|
|
||||||
|
|
||||||
The rest of the guide still applies.
|
|
||||||
|
|
||||||
## Limitations
|
|
||||||
|
|
||||||
When using Pages under the general domain of a GitLab instance (`*.example.io`),
|
|
||||||
you _cannot_ use HTTPS with sub-subdomains. That means that if your
|
|
||||||
username/groupname contains a dot, for example `foo.bar`, the domain
|
|
||||||
`https://foo.bar.example.io` will _not_ work. This is a limitation of the
|
|
||||||
[HTTP Over TLS protocol][rfc]. HTTP pages will continue to work provided you
|
|
||||||
don't redirect HTTP to HTTPS.
|
|
||||||
|
|
||||||
[rfc]: https://tools.ietf.org/html/rfc2818#section-3.1 "HTTP Over TLS RFC"
|
|
||||||
|
|
||||||
## Redirects in GitLab Pages
|
|
||||||
|
|
||||||
Since you cannot use any custom server configuration files, like `.htaccess` or
|
|
||||||
any `.conf` file for that matter, if you want to redirect a web page to another
|
|
||||||
location, you can use the [HTTP meta refresh tag][metarefresh].
|
|
||||||
|
|
||||||
Some static site generators provide plugins for that functionality so that you
|
|
||||||
don't have to create and edit HTML files manually. For example, Jekyll has the
|
|
||||||
[redirect-from plugin](https://github.com/jekyll/jekyll-redirect-from).
|
|
||||||
|
|
||||||
## Frequently Asked Questions
|
|
||||||
|
|
||||||
### Can I download my generated pages?
|
|
||||||
|
|
||||||
Sure. All you need to do is download the artifacts archive from the build page.
|
|
||||||
|
|
||||||
### Can I use GitLab Pages if my project is private?
|
|
||||||
|
|
||||||
Yes. GitLab Pages don't care whether you set your project's visibility level
|
|
||||||
to private, internal or public.
|
|
||||||
|
|
||||||
### Do I need to create a user/group website before creating a project website?
|
|
||||||
|
|
||||||
No, you don't. You can create your project first and it will be accessed under
|
|
||||||
`http(s)://namespace.example.io/projectname`.
|
|
||||||
|
|
||||||
## Known issues
|
|
||||||
|
|
||||||
For a list of known issues, visit GitLab's [public issue tracker].
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
[jekyll]: http://jekyllrb.com/
|
|
||||||
[ee-80]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/80
|
|
||||||
[ee-173]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/173
|
|
||||||
[pages-daemon]: https://gitlab.com/gitlab-org/gitlab-pages
|
|
||||||
[gitlab ci]: https://about.gitlab.com/gitlab-ci
|
|
||||||
[gitlab runner]: https://gitlab.com/gitlab-org/gitlab-ci-multi-runner
|
|
||||||
[pages]: ../ci/yaml/README.md#pages
|
|
||||||
[staticgen]: https://www.staticgen.com/
|
|
||||||
[pages-jekyll]: https://gitlab.com/pages/jekyll
|
|
||||||
[metarefresh]: https://en.wikipedia.org/wiki/Meta_refresh
|
|
||||||
[public issue tracker]: https://gitlab.com/gitlab-org/gitlab-ee/issues?label_name=Pages
|
|
||||||
|
|
|
@ -1,496 +1 @@
|
||||||
# GitLab Pages Administration
|
This document was moved to [administration/pages](../administration/pages/index.md).
|
||||||
|
|
||||||
> **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.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
If you are looking for ways to upload your static content in GitLab Pages, you
|
|
||||||
probably want to read the [user documentation](README.md).
|
|
||||||
|
|
||||||
## 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.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
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 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.
|
|
||||||
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. If you choose that route note that you should use TCP load
|
|
||||||
balancing for HTTPS. If you use TLS-termination (HTTPS-load balancing) the
|
|
||||||
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.
|
|
||||||
|
|
||||||
## Prerequisites
|
|
||||||
|
|
||||||
Before proceeding with the Pages configuration, you will need to:
|
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
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.2.3.4
|
|
||||||
```
|
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
## Configuration
|
|
||||||
|
|
||||||
Depending on your needs, you can install GitLab Pages in four different ways.
|
|
||||||
|
|
||||||
### 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:
|
|
||||||
|
|
||||||
```
|
|
||||||
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
|
|
||||||
daemon will listen for connections:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
## GitLab Pages
|
|
||||||
pages:
|
|
||||||
enabled: true
|
|
||||||
# The location where pages are stored (default: shared/pages).
|
|
||||||
# path: shared/pages
|
|
||||||
|
|
||||||
host: example.io
|
|
||||||
port: 443
|
|
||||||
https: true
|
|
||||||
|
|
||||||
external_http: 1.1.1.1:80
|
|
||||||
external_https: 1.1.1.1: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.1:80 -listen-https 1.1.1.1: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
|
|
||||||
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/gitlab.rb`:
|
|
||||||
|
|
||||||
```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'
|
|
||||||
```
|
|
||||||
|
|
||||||
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]
|
|
||||||
|
|
||||||
### 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:
|
|
||||||
|
|
||||||
```
|
|
||||||
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
|
|
||||||
for connections:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
pages:
|
|
||||||
enabled: true
|
|
||||||
# The location where pages are stored (default: shared/pages).
|
|
||||||
# path: shared/pages
|
|
||||||
|
|
||||||
host: example.io
|
|
||||||
port: 80
|
|
||||||
https: false
|
|
||||||
|
|
||||||
external_http: 1.1.1.1:80
|
|
||||||
```
|
|
||||||
|
|
||||||
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` and `-listen-http` must match the `host` and `external_http`
|
|
||||||
settings that you set above respectively:
|
|
||||||
|
|
||||||
```
|
|
||||||
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.1:80"
|
|
||||||
```
|
|
||||||
|
|
||||||
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/gitlab.rb`:
|
|
||||||
|
|
||||||
```ruby
|
|
||||||
pages_external_url "http://example.io"
|
|
||||||
nginx['listen_addresses'] = ['1.1.1.1']
|
|
||||||
pages_nginx['enable'] = false
|
|
||||||
gitlab_pages['external_http'] = '1.1.1.2:80'
|
|
||||||
```
|
|
||||||
|
|
||||||
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]
|
|
||||||
|
|
||||||
### Option 3. Wildcard HTTPS domain without custom domains
|
|
||||||
|
|
||||||
| 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.
|
|
||||||
|
|
||||||
**Source installations:**
|
|
||||||
|
|
||||||
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. 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
|
|
||||||
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.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**Omnibus installations:**
|
|
||||||
|
|
||||||
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'
|
|
||||||
|
|
||||||
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 `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.
|
|
||||||
|
|
||||||
**Source installations:**
|
|
||||||
|
|
||||||
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. 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. 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]
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**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]
|
|
||||||
|
|
||||||
## 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.
|
|
||||||
|
|
||||||
If your GitLab pages domain is `example.io`, replace:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
server_name ~^.*\.YOUR_GITLAB_PAGES\.DOMAIN$;
|
|
||||||
```
|
|
||||||
|
|
||||||
with:
|
|
||||||
|
|
||||||
```
|
|
||||||
server_name ~^.*\.example\.io$;
|
|
||||||
```
|
|
||||||
|
|
||||||
If you are using a subdomain, make sure to escape all dots (`.`) except from
|
|
||||||
the first one with a backslash (\). For example `pages.example.io` would be:
|
|
||||||
|
|
||||||
```
|
|
||||||
server_name ~^.*\.pages\.example\.io$;
|
|
||||||
```
|
|
||||||
|
|
||||||
## 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
|
|
||||||
|
|
||||||
**Source installations:**
|
|
||||||
|
|
||||||
1. 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
|
|
||||||
```
|
|
||||||
|
|
||||||
1. [Restart GitLab][restart]
|
|
||||||
|
|
||||||
**Omnibus installations:**
|
|
||||||
|
|
||||||
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`:
|
|
||||||
|
|
||||||
```ruby
|
|
||||||
gitlab_rails['pages_path'] = "/mnt/storage/pages"
|
|
||||||
```
|
|
||||||
|
|
||||||
1. [Reconfigure GitLab][reconfigure]
|
|
||||||
|
|
||||||
## Backup
|
|
||||||
|
|
||||||
Pages are part of the [regular backup][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.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.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**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-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
|
|
||||||
|
|
|
@ -91,7 +91,7 @@ The curriculum is composed of GitLab videos, screencasts, presentations, project
|
||||||
|
|
||||||
1. [Using any Static Site Generator with GitLab Pages](https://about.gitlab.com/2016/06/17/ssg-overview-gitlab-pages-part-3-examples-ci/)
|
1. [Using any Static Site Generator with GitLab Pages](https://about.gitlab.com/2016/06/17/ssg-overview-gitlab-pages-part-3-examples-ci/)
|
||||||
1. [Securing GitLab Pages with SSL](https://about.gitlab.com/2016/06/24/secure-gitlab-pages-with-startssl/)
|
1. [Securing GitLab Pages with SSL](https://about.gitlab.com/2016/06/24/secure-gitlab-pages-with-startssl/)
|
||||||
1. [GitLab Pages Documentation](https://docs.gitlab.com/ee/pages/README.html)
|
1. [GitLab Pages Documentation](https://docs.gitlab.com/ce/user/project/pages/)
|
||||||
|
|
||||||
#### 2.2. GitLab Issues
|
#### 2.2. GitLab Issues
|
||||||
|
|
||||||
|
|
|
@ -172,7 +172,7 @@ Move on to understanding some of GitLab's more advanced features. You can make u
|
||||||
- Get to know the [GitLab API](https://docs.gitlab.com/ee/api/README.html), its capabilities and shortcomings
|
- Get to know the [GitLab API](https://docs.gitlab.com/ee/api/README.html), its capabilities and shortcomings
|
||||||
- Learn how to [migrate from SVN to Git](https://docs.gitlab.com/ee/workflow/importing/migrating_from_svn.html)
|
- Learn how to [migrate from SVN to Git](https://docs.gitlab.com/ee/workflow/importing/migrating_from_svn.html)
|
||||||
- Set up [GitLab CI](https://docs.gitlab.com/ee/ci/quick_start/README.html)
|
- Set up [GitLab CI](https://docs.gitlab.com/ee/ci/quick_start/README.html)
|
||||||
- Create your first [GitLab Page](https://docs.gitlab.com/ee/pages/administration.html)
|
- Create your first [GitLab Page](https://docs.gitlab.com/ce/administration/pages/)
|
||||||
- Get to know the GitLab Codebase by reading through the source code:
|
- Get to know the GitLab Codebase by reading through the source code:
|
||||||
- Find the differences between the [EE codebase](https://gitlab.com/gitlab-org/gitlab-ce)
|
- Find the differences between the [EE codebase](https://gitlab.com/gitlab-org/gitlab-ce)
|
||||||
and the [CE codebase](https://gitlab.com/gitlab-org/gitlab-ce)
|
and the [CE codebase](https://gitlab.com/gitlab-org/gitlab-ce)
|
||||||
|
|
Before Width: | Height: | Size: 33 KiB After Width: | Height: | Size: 33 KiB |
Before Width: | Height: | Size: 85 KiB After Width: | Height: | Size: 85 KiB |
Before Width: | Height: | Size: 34 KiB After Width: | Height: | Size: 34 KiB |
Before Width: | Height: | Size: 62 KiB After Width: | Height: | Size: 62 KiB |
Before Width: | Height: | Size: 50 KiB After Width: | Height: | Size: 50 KiB |
Before Width: | Height: | Size: 27 KiB After Width: | Height: | Size: 27 KiB |
Before Width: | Height: | Size: 101 KiB After Width: | Height: | Size: 101 KiB |
|
@ -0,0 +1,435 @@
|
||||||
|
# GitLab Pages
|
||||||
|
|
||||||
|
> **Note:**
|
||||||
|
> This feature was [introduced][ee-80] in GitLab EE 8.3.
|
||||||
|
> Custom CNAMEs with TLS support were [introduced][ee-173] in GitLab EE 8.5.
|
||||||
|
|
||||||
|
> **Note:**
|
||||||
|
> This document is about the user guide. To learn how to enable GitLab Pages
|
||||||
|
> across your GitLab instance, visit the [administrator documentation](administration.md).
|
||||||
|
|
||||||
|
With GitLab Pages you can host for free your static websites on GitLab.
|
||||||
|
Combined with the power of [GitLab CI] and the help of [GitLab Runner] you can
|
||||||
|
deploy static pages for your individual projects, your user or your group.
|
||||||
|
|
||||||
|
Read [GitLab Pages on GitLab.com](#gitlab-pages-on-gitlab-com) for specific
|
||||||
|
information, if you are using GitLab.com to host your website.
|
||||||
|
|
||||||
|
## Getting started with GitLab Pages
|
||||||
|
|
||||||
|
> **Note:**
|
||||||
|
> In the rest of this document we will assume that the general domain name that
|
||||||
|
> is used for GitLab Pages is `example.io`.
|
||||||
|
|
||||||
|
In general there are two types of pages one might create:
|
||||||
|
|
||||||
|
- Pages per user (`username.example.io`) or per group (`groupname.example.io`)
|
||||||
|
- Pages per project (`username.example.io/projectname` or `groupname.example.io/projectname`)
|
||||||
|
|
||||||
|
In GitLab, usernames and groupnames are unique and we often refer to them
|
||||||
|
as namespaces. There can be only one namespace in a GitLab instance. Below you
|
||||||
|
can see the connection between the type of GitLab Pages, what the project name
|
||||||
|
that is created on GitLab looks like and the website URL it will be ultimately
|
||||||
|
be served on.
|
||||||
|
|
||||||
|
| Type of GitLab Pages | The name of the project created in GitLab | Website URL |
|
||||||
|
| -------------------- | ------------ | ----------- |
|
||||||
|
| User pages | `username.example.io` | `http(s)://username.example.io` |
|
||||||
|
| Group pages | `groupname.example.io` | `http(s)://groupname.example.io` |
|
||||||
|
| Project pages owned by a user | `projectname` | `http(s)://username.example.io/projectname` |
|
||||||
|
| Project pages owned by a group | `projectname` | `http(s)://groupname.example.io/projectname`|
|
||||||
|
|
||||||
|
> **Warning:**
|
||||||
|
> There are some known [limitations](#limitations) regarding namespaces served
|
||||||
|
> under the general domain name and HTTPS. Make sure to read that section.
|
||||||
|
|
||||||
|
### GitLab Pages requirements
|
||||||
|
|
||||||
|
In brief, this is what you need to upload your website in GitLab Pages:
|
||||||
|
|
||||||
|
1. Find out the general domain name that is used for GitLab Pages
|
||||||
|
(ask your administrator). This is very important, so you should first make
|
||||||
|
sure you get that right.
|
||||||
|
1. Create a project
|
||||||
|
1. Push a [`.gitlab-ci.yml` file](../ci/yaml/README.md) in the root directory
|
||||||
|
of your repository with a specific job named [`pages`][pages]
|
||||||
|
1. Set up a GitLab Runner to build your website
|
||||||
|
|
||||||
|
> **Note:**
|
||||||
|
> If [shared runners](../ci/runners/README.md) are enabled by your GitLab
|
||||||
|
> administrator, you should be able to use them instead of bringing your own.
|
||||||
|
|
||||||
|
### User or group Pages
|
||||||
|
|
||||||
|
For user and group pages, the name of the project should be specific to the
|
||||||
|
username or groupname and the general domain name that is used for GitLab Pages.
|
||||||
|
Head over your GitLab instance that supports GitLab Pages and create a
|
||||||
|
repository named `username.example.io`, where `username` is your username on
|
||||||
|
GitLab. If the first part of the project name doesn't match exactly your
|
||||||
|
username, it won’t work, so make sure to get it right.
|
||||||
|
|
||||||
|
To create a group page, the steps are the same like when creating a website for
|
||||||
|
users. Just make sure that you are creating the project within the group's
|
||||||
|
namespace.
|
||||||
|
|
||||||
|
![Create a user-based pages project](img/pages_create_user_page.png)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
After you push some static content to your repository and GitLab Runner uploads
|
||||||
|
the artifacts to GitLab CI, you will be able to access your website under
|
||||||
|
`http(s)://username.example.io`. Keep reading to find out how.
|
||||||
|
|
||||||
|
>**Note:**
|
||||||
|
If your username/groupname contains a dot, for example `foo.bar`, you will not
|
||||||
|
be able to use the wildcard domain HTTPS, read more at [limitations](#limitations).
|
||||||
|
|
||||||
|
### Project Pages
|
||||||
|
|
||||||
|
GitLab Pages for projects can be created by both user and group accounts.
|
||||||
|
The steps to create a project page for a user or a group are identical:
|
||||||
|
|
||||||
|
1. Create a new project
|
||||||
|
1. Push a [`.gitlab-ci.yml` file](../ci/yaml/README.md) in the root directory
|
||||||
|
of your repository with a specific job named [`pages`][pages].
|
||||||
|
1. Set up a GitLab Runner to build your website
|
||||||
|
|
||||||
|
A user's project will be served under `http(s)://username.example.io/projectname`
|
||||||
|
whereas a group's project under `http(s)://groupname.example.io/projectname`.
|
||||||
|
|
||||||
|
### Explore the contents of `.gitlab-ci.yml`
|
||||||
|
|
||||||
|
The key thing about GitLab Pages is the `.gitlab-ci.yml` file, something that
|
||||||
|
gives you absolute control over the build process. You can actually watch your
|
||||||
|
website being built live by following the CI build traces.
|
||||||
|
|
||||||
|
> **Note:**
|
||||||
|
> Before reading this section, make sure you familiarize yourself with GitLab CI
|
||||||
|
> and the specific syntax of[`.gitlab-ci.yml`](../ci/yaml/README.md) by
|
||||||
|
> following our [quick start guide](../ci/quick_start/README.md).
|
||||||
|
|
||||||
|
To make use of GitLab Pages, the contents of `.gitlab-ci.yml` must follow the
|
||||||
|
rules below:
|
||||||
|
|
||||||
|
1. A special job named [`pages`][pages] must be defined
|
||||||
|
1. Any static content which will be served by GitLab Pages must be placed under
|
||||||
|
a `public/` directory
|
||||||
|
1. `artifacts` with a path to the `public/` directory must be defined
|
||||||
|
|
||||||
|
In its simplest form, `.gitlab-ci.yml` looks like:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
pages:
|
||||||
|
script:
|
||||||
|
- my_commands
|
||||||
|
artifacts:
|
||||||
|
paths:
|
||||||
|
- public
|
||||||
|
```
|
||||||
|
|
||||||
|
When the Runner reaches to build the `pages` job, it executes whatever is
|
||||||
|
defined in the `script` parameter and if the build completes with a non-zero
|
||||||
|
exit status, it then uploads the `public/` directory to GitLab Pages.
|
||||||
|
|
||||||
|
The `public/` directory should contain all the static content of your website.
|
||||||
|
Depending on how you plan to publish your website, the steps defined in the
|
||||||
|
[`script` parameter](../ci/yaml/README.md#script) may differ.
|
||||||
|
|
||||||
|
Be aware that Pages are by default branch/tag agnostic and their deployment
|
||||||
|
relies solely on what you specify in `.gitlab-ci.yml`. If you don't limit the
|
||||||
|
`pages` job with the [`only` parameter](../ci/yaml/README.md#only-and-except),
|
||||||
|
whenever a new commit is pushed to whatever branch or tag, the Pages will be
|
||||||
|
overwritten. In the example below, we limit the Pages to be deployed whenever
|
||||||
|
a commit is pushed only on the `master` branch:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
pages:
|
||||||
|
script:
|
||||||
|
- my_commands
|
||||||
|
artifacts:
|
||||||
|
paths:
|
||||||
|
- public
|
||||||
|
only:
|
||||||
|
- master
|
||||||
|
```
|
||||||
|
|
||||||
|
We then tell the Runner to treat the `public/` directory as `artifacts` and
|
||||||
|
upload it to GitLab. And since all these parameters were all under a `pages`
|
||||||
|
job, the contents of the `public` directory will be served by GitLab Pages.
|
||||||
|
|
||||||
|
#### How `.gitlab-ci.yml` looks like when the static content is in your repository
|
||||||
|
|
||||||
|
Supposedly your repository contained the following files:
|
||||||
|
|
||||||
|
```
|
||||||
|
├── index.html
|
||||||
|
├── css
|
||||||
|
│ └── main.css
|
||||||
|
└── js
|
||||||
|
└── main.js
|
||||||
|
```
|
||||||
|
|
||||||
|
Then the `.gitlab-ci.yml` example below simply moves all files from the root
|
||||||
|
directory of the project to the `public/` directory. The `.public` workaround
|
||||||
|
is so `cp` doesn't also copy `public/` to itself in an infinite loop:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
pages:
|
||||||
|
script:
|
||||||
|
- mkdir .public
|
||||||
|
- cp -r * .public
|
||||||
|
- mv .public public
|
||||||
|
artifacts:
|
||||||
|
paths:
|
||||||
|
- public
|
||||||
|
only:
|
||||||
|
- master
|
||||||
|
```
|
||||||
|
|
||||||
|
#### How `.gitlab-ci.yml` looks like when using a static generator
|
||||||
|
|
||||||
|
In general, GitLab Pages support any kind of [static site generator][staticgen],
|
||||||
|
since `.gitlab-ci.yml` can be configured to run any possible command.
|
||||||
|
|
||||||
|
In the root directory of your Git repository, place the source files of your
|
||||||
|
favorite static generator. Then provide a `.gitlab-ci.yml` file which is
|
||||||
|
specific to your static generator.
|
||||||
|
|
||||||
|
The example below, uses [Jekyll] to build the static site:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
image: ruby:2.1 # the script will run in Ruby 2.1 using the Docker image ruby:2.1
|
||||||
|
|
||||||
|
pages: # the build job must be named pages
|
||||||
|
script:
|
||||||
|
- gem install jekyll # we install jekyll
|
||||||
|
- jekyll build -d public/ # we tell jekyll to build the site for us
|
||||||
|
artifacts:
|
||||||
|
paths:
|
||||||
|
- public # this is where the site will live and the Runner uploads it in GitLab
|
||||||
|
only:
|
||||||
|
- master # this script is only affecting the master branch
|
||||||
|
```
|
||||||
|
|
||||||
|
Here, we used the Docker executor and in the first line we specified the base
|
||||||
|
image against which our builds will run.
|
||||||
|
|
||||||
|
You have to make sure that the generated static files are ultimately placed
|
||||||
|
under the `public` directory, that's why in the `script` section we run the
|
||||||
|
`jekyll` command that builds the website and puts all content in the `public/`
|
||||||
|
directory. Depending on the static generator of your choice, this command will
|
||||||
|
differ. Search in the documentation of the static generator you will use if
|
||||||
|
there is an option to explicitly set the output directory. If there is not
|
||||||
|
such an option, you can always add one more line under `script` to rename the
|
||||||
|
resulting directory in `public/`.
|
||||||
|
|
||||||
|
We then tell the Runner to treat the `public/` directory as `artifacts` and
|
||||||
|
upload it to GitLab.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
See the [jekyll example project][pages-jekyll] to better understand how this
|
||||||
|
works.
|
||||||
|
|
||||||
|
For a list of Pages projects, see the [example projects](#example-projects) to
|
||||||
|
get you started.
|
||||||
|
|
||||||
|
#### How to set up GitLab Pages in a repository where there's also actual code
|
||||||
|
|
||||||
|
Remember that GitLab Pages are by default branch/tag agnostic and their
|
||||||
|
deployment relies solely on what you specify in `.gitlab-ci.yml`. You can limit
|
||||||
|
the `pages` job with the [`only` parameter](../ci/yaml/README.md#only-and-except),
|
||||||
|
whenever a new commit is pushed to a branch that will be used specifically for
|
||||||
|
your pages.
|
||||||
|
|
||||||
|
That way, you can have your project's code in the `master` branch and use an
|
||||||
|
orphan branch (let's name it `pages`) that will host your static generator site.
|
||||||
|
|
||||||
|
You can create a new empty branch like this:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git checkout --orphan pages
|
||||||
|
```
|
||||||
|
|
||||||
|
The first commit made on this new branch will have no parents and it will be
|
||||||
|
the root of a new history totally disconnected from all the other branches and
|
||||||
|
commits. Push the source files of your static generator in the `pages` branch.
|
||||||
|
|
||||||
|
Below is a copy of `.gitlab-ci.yml` where the most significant line is the last
|
||||||
|
one, specifying to execute everything in the `pages` branch:
|
||||||
|
|
||||||
|
```
|
||||||
|
image: ruby:2.1
|
||||||
|
|
||||||
|
pages:
|
||||||
|
script:
|
||||||
|
- gem install jekyll
|
||||||
|
- jekyll build -d public/
|
||||||
|
artifacts:
|
||||||
|
paths:
|
||||||
|
- public
|
||||||
|
only:
|
||||||
|
- pages
|
||||||
|
```
|
||||||
|
|
||||||
|
See an example that has different files in the [`master` branch][jekyll-master]
|
||||||
|
and the source files for Jekyll are in a [`pages` branch][jekyll-pages] which
|
||||||
|
also includes `.gitlab-ci.yml`.
|
||||||
|
|
||||||
|
[jekyll-master]: https://gitlab.com/pages/jekyll-branched/tree/master
|
||||||
|
[jekyll-pages]: https://gitlab.com/pages/jekyll-branched/tree/pages
|
||||||
|
|
||||||
|
## Next steps
|
||||||
|
|
||||||
|
So you have successfully deployed your website, congratulations! Let's check
|
||||||
|
what more you can do with GitLab Pages.
|
||||||
|
|
||||||
|
### Example projects
|
||||||
|
|
||||||
|
Below is a list of example projects for GitLab Pages with a plain HTML website
|
||||||
|
or various static site generators. Contributions are very welcome.
|
||||||
|
|
||||||
|
- [Plain HTML](https://gitlab.com/pages/plain-html)
|
||||||
|
- [Jekyll](https://gitlab.com/pages/jekyll)
|
||||||
|
- [Hugo](https://gitlab.com/pages/hugo)
|
||||||
|
- [Middleman](https://gitlab.com/pages/middleman)
|
||||||
|
- [Hexo](https://gitlab.com/pages/hexo)
|
||||||
|
- [Brunch](https://gitlab.com/pages/brunch)
|
||||||
|
- [Metalsmith](https://gitlab.com/pages/metalsmith)
|
||||||
|
- [Harp](https://gitlab.com/pages/harp)
|
||||||
|
|
||||||
|
Visit the GitLab Pages group for a full list of example projects:
|
||||||
|
<https://gitlab.com/groups/pages>.
|
||||||
|
|
||||||
|
### Add a custom domain to your Pages website
|
||||||
|
|
||||||
|
If this setting is enabled by your GitLab administrator, you should be able to
|
||||||
|
see the **New Domain** button when visiting your project's settings through the
|
||||||
|
gear icon in the top right and then navigating to **Pages**.
|
||||||
|
|
||||||
|
![New domain button](img/pages_new_domain_button.png)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
You can add multiple domains pointing to your website hosted under GitLab.
|
||||||
|
Once the domain is added, you can see it listed under the **Domains** section.
|
||||||
|
|
||||||
|
![Pages multiple domains](img/pages_multiple_domains.png)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
As a last step, you need to configure your DNS and add a CNAME pointing to your
|
||||||
|
user/group page. Click on the **Details** button of a domain for further
|
||||||
|
instructions.
|
||||||
|
|
||||||
|
![Pages DNS details](img/pages_dns_details.png)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
>**Note:**
|
||||||
|
Currently there is support only for custom domains on per-project basis. That
|
||||||
|
means that if you add a custom domain (`example.com`) for your user website
|
||||||
|
(`username.example.io`), a project that is served under `username.example.io/foo`,
|
||||||
|
will not be accessible under `example.com/foo`.
|
||||||
|
|
||||||
|
### Secure your custom domain website with TLS
|
||||||
|
|
||||||
|
When you add a new custom domain, you also have the chance to add a TLS
|
||||||
|
certificate. If this setting is enabled by your GitLab administrator, you
|
||||||
|
should be able to see the option to upload the public certificate and the
|
||||||
|
private key when adding a new domain.
|
||||||
|
|
||||||
|
![Pages upload cert](img/pages_upload_cert.png)
|
||||||
|
|
||||||
|
### Custom error codes pages
|
||||||
|
|
||||||
|
You can provide your own 403 and 404 error pages by creating the `403.html` and
|
||||||
|
`404.html` files respectively in the root directory of the `public/` directory
|
||||||
|
that will be included in the artifacts. Usually this is the root directory of
|
||||||
|
your project, but that may differ depending on your static generator
|
||||||
|
configuration.
|
||||||
|
|
||||||
|
If the case of `404.html`, there are different scenarios. For example:
|
||||||
|
|
||||||
|
- If you use project Pages (served under `/projectname/`) and try to access
|
||||||
|
`/projectname/non/exsiting_file`, GitLab Pages will try to serve first
|
||||||
|
`/projectname/404.html`, and then `/404.html`.
|
||||||
|
- If you use user/group Pages (served under `/`) and try to access
|
||||||
|
`/non/existing_file` GitLab Pages will try to serve `/404.html`.
|
||||||
|
- If you use a custom domain and try to access `/non/existing_file`, GitLab
|
||||||
|
Pages will try to serve only `/404.html`.
|
||||||
|
|
||||||
|
### Remove the contents of your pages
|
||||||
|
|
||||||
|
If you ever feel the need to purge your Pages content, you can do so by going
|
||||||
|
to your project's settings through the gear icon in the top right, and then
|
||||||
|
navigating to **Pages**. Hit the **Remove pages** button and your Pages website
|
||||||
|
will be deleted. Simple as that.
|
||||||
|
|
||||||
|
![Remove pages](img/pages_remove.png)
|
||||||
|
|
||||||
|
## GitLab Pages on GitLab.com
|
||||||
|
|
||||||
|
If you are using GitLab.com to host your website, then:
|
||||||
|
|
||||||
|
- The general domain name for GitLab Pages on GitLab.com is `gitlab.io`.
|
||||||
|
- Custom domains and TLS support are enabled.
|
||||||
|
- Shared runners are enabled by default, provided for free and can be used to
|
||||||
|
build your website. If you want you can still bring your own Runner.
|
||||||
|
|
||||||
|
The rest of the guide still applies.
|
||||||
|
|
||||||
|
## Limitations
|
||||||
|
|
||||||
|
When using Pages under the general domain of a GitLab instance (`*.example.io`),
|
||||||
|
you _cannot_ use HTTPS with sub-subdomains. That means that if your
|
||||||
|
username/groupname contains a dot, for example `foo.bar`, the domain
|
||||||
|
`https://foo.bar.example.io` will _not_ work. This is a limitation of the
|
||||||
|
[HTTP Over TLS protocol][rfc]. HTTP pages will continue to work provided you
|
||||||
|
don't redirect HTTP to HTTPS.
|
||||||
|
|
||||||
|
[rfc]: https://tools.ietf.org/html/rfc2818#section-3.1 "HTTP Over TLS RFC"
|
||||||
|
|
||||||
|
## Redirects in GitLab Pages
|
||||||
|
|
||||||
|
Since you cannot use any custom server configuration files, like `.htaccess` or
|
||||||
|
any `.conf` file for that matter, if you want to redirect a web page to another
|
||||||
|
location, you can use the [HTTP meta refresh tag][metarefresh].
|
||||||
|
|
||||||
|
Some static site generators provide plugins for that functionality so that you
|
||||||
|
don't have to create and edit HTML files manually. For example, Jekyll has the
|
||||||
|
[redirect-from plugin](https://github.com/jekyll/jekyll-redirect-from).
|
||||||
|
|
||||||
|
## Frequently Asked Questions
|
||||||
|
|
||||||
|
### Can I download my generated pages?
|
||||||
|
|
||||||
|
Sure. All you need to do is download the artifacts archive from the build page.
|
||||||
|
|
||||||
|
### Can I use GitLab Pages if my project is private?
|
||||||
|
|
||||||
|
Yes. GitLab Pages don't care whether you set your project's visibility level
|
||||||
|
to private, internal or public.
|
||||||
|
|
||||||
|
### Do I need to create a user/group website before creating a project website?
|
||||||
|
|
||||||
|
No, you don't. You can create your project first and it will be accessed under
|
||||||
|
`http(s)://namespace.example.io/projectname`.
|
||||||
|
|
||||||
|
## Known issues
|
||||||
|
|
||||||
|
For a list of known issues, visit GitLab's [public issue tracker].
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
[jekyll]: http://jekyllrb.com/
|
||||||
|
[ee-80]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/80
|
||||||
|
[ee-173]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/173
|
||||||
|
[pages-daemon]: https://gitlab.com/gitlab-org/gitlab-pages
|
||||||
|
[gitlab ci]: https://about.gitlab.com/gitlab-ci
|
||||||
|
[gitlab runner]: https://gitlab.com/gitlab-org/gitlab-ci-multi-runner
|
||||||
|
[pages]: ../ci/yaml/README.md#pages
|
||||||
|
[staticgen]: https://www.staticgen.com/
|
||||||
|
[pages-jekyll]: https://gitlab.com/pages/jekyll
|
||||||
|
[metarefresh]: https://en.wikipedia.org/wiki/Meta_refresh
|
||||||
|
[public issue tracker]: https://gitlab.com/gitlab-org/gitlab-ee/issues?label_name=Pages
|