Skip to content

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

Merge branch 'docs/pages-refactor' into 'master' 

GitLab Pages documentation refactor

Closes #465

See merge request !1072
parents 938624c9 6c2fb7e1
Show whitespace changes
Inline Side-by-side
Showing with 1013 additions and 937 deletions
doc/README.md
View file @ dda3aa8c
......@@ -13,7 +13,7 @@
- [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.
- [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 and exporting projects between instances](user/project/settings/import_export.md).
- [Koding](user/project/koding.md) Learn how to use Koding, the online IDE.
......@@ -65,7 +65,7 @@
- [git-annex configuration](workflow/git_annex.md#configuration)
- [Git LFS configuration](workflow/lfs/lfs_administration.md)
- [Housekeeping](administration/housekeeping.md) Keep your Git repository tidy and fast.
- [GitLab Pages configuration](pages/administration.md) Configure GitLab Pages.
- [GitLab Pages configuration](administration/pages/index.md) Configure GitLab Pages.
- [Elasticsearch](integration/elasticsearch.md) Enable Elasticsearch.
- [GitLab GEO](gitlab-geo/README.md) Configure GitLab GEO, a secondary read-only GitLab instance.
- [GitLab performance monitoring with InfluxDB](administration/monitoring/performance/introduction.md) Configure GitLab and InfluxDB for measuring performance metrics.
......
doc/administration/high_availability/load_balancer.md
View file @ dda3aa8c
......@@ -66,4 +66,4 @@ Read more on high-availability configuration:
configure custom domains with custom SSL, which would not be possible
if SSL was terminated at the load balancer.
[gitlab-pages]: http://docs.gitlab.com/ee/pages/administration.html
[gitlab-pages]: ../pages/index.md
doc/administration/pages/index.md 0 → 100644
View file @ dda3aa8c
# 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][ce-14605] to Community Edition in GitLab 8.17.
- This guide is for Omnibus GitLab installations. If you have installed
GitLab from source, follow the [Pages source installation document](source.md).
---
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. In this
document we assume that to be `example.io`.
1. Configure a **wildcard DNS record**.
1. (Optional) Have a **wildcard certificate** for that domain if you decide to
serve Pages under HTTPS.
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.
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.
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.
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.
1. Set the external URL for GitLab Pages in `/etc/gitlab/gitlab.rb`:
```ruby
pages_external_url 'http://example.io'
```
1. [Reconfigure GitLab][reconfigure]
## Change storage path
Follow the steps below to change the default path where GitLab Pages' contents
are stored.
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]
## 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.
## 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.17 ([documentation][8-17-docs])**
- GitLab Pages were ported to Community Edition in GitLab 8.17.
- 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-17-docs]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-17-stable-ce/doc/administration/pages/index.md
[backup]: ../raketasks/backup_restore.md
[ce-14605]: https://gitlab.com/gitlab-org/gitlab-ce/issues/14605
[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.4
doc/administration/pages/source.md 0 → 100644
View file @ dda3aa8c
# GitLab Pages administration for source installations
This is the documentation for configuring a GitLab Pages when you have installed
GitLab from source and not using the Omnibus packages.
You are encouraged to read the [Omnibus documentation](index.md) as it provides
some invaluable information to the configuration of GitLab Pages. Please proceed
to read it before going forward with this guide.
We also highly recommend that you use the Omnibus GitLab packages, as we
optimize them specifically for GitLab, and we will take care of upgrading GitLab
Pages to the latest supported version.
## Overview
[Read the Omnibus overview section.](index.md#overview)
## Prerequisites
[Read the Omnibus prerequisites section.](index.md#prerequisites)
## 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.
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.4
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.2:80
external_https: 1.1.1.2: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.2:80 -listen-https 1.1.1.2: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]
### 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.
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.4
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.2: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.2: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]
### 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.
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.4
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.
1. Restart NGINX
1. [Restart GitLab][restart]
### 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.
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.4
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]
## 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$;
```
## Change storage path
Follow the steps below to change the default path where GitLab Pages' contents
are stored.
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]
## 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.
## 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.
[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.4
doc/install/installation.md
View file @ dda3aa8c
......@@ -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
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.
......
doc/pages/README.md
View file @ dda3aa8c
# 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
This document was moved to [user/project/pages](../user/project/pages/index.md).
doc/pages/administration.md
View file @ dda3aa8c
# GitLab Pages Administration
> **Note:**
> This feature was first [introduced][ee-80] in GitLab EE 8.3.
> Custom CNAMEs with TLS support were [introduced][ee-173] in GitLab EE 8.5.
---
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).
## The GitLab Pages daemon
Starting from GitLab EE 8.5, GitLab Pages make use of the [GitLab Pages daemon],
a simple HTTP server written in Go that can listen on an external IP address
and provide support for custom domains and custom certificates. The GitLab
Pages Daemon supports dynamic certificates through SNI and exposes pages using
HTTP2 by default.
Here is a brief list with what it is supported when using the pages daemon:
- Multiple domains per-project
- One TLS certificate per-domain
- Validation of certificate
- Validation of certificate chain
- Validation of private key against certificate
You are encouraged to read its [README][pages-readme] to fully understand how
it works.
[gitlab pages daemon]: https://gitlab.com/gitlab-org/gitlab-pages
[pages-readme]: https://gitlab.com/gitlab-org/gitlab-pages/blob/master/README.md
### The GitLab Pages daemon and the case of custom domains
In the case of custom domains, the Pages daemon needs to listen on ports `80`
and/or `443`. For that reason, there is some flexibility in the way which you
can set it up, so you basically have three choices:
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. Let's begin by
installing the pages daemon.
### Install the Pages daemon
**Source installations**
```
cd /home/git
sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-pages.git
cd gitlab-pages
sudo -u git -H git checkout v0.2.1
sudo -u git -H make
```
**Omnibus installations**
The `gitlab-pages` daemon is included in the Omnibus package.
## Configuration
There are multiple ways to set up GitLab Pages according to what URL scheme you
are willing to support.
### Configuration prerequisites
In the next section you will find all possible scenarios to choose from.
In either scenario, you will need:
1. To use the [GitLab Pages daemon](#the-gitlab-pages-daemon)
1. A separate domain
1. A separate Nginx configuration file which needs to be explicitly added in
the server under which GitLab EE runs (Omnibus does that automatically)
1. (Optional) A wildcard certificate for that domain if you decide to serve
pages under HTTPS
1. (Optional but recommended) [Shared runners](../ci/runners/README.md) so that
your users don't have to bring their own
### Configuration scenarios
Before proceeding with setting up GitLab Pages, you have to decide which route
you want to take.
The possible scenarios are depicted in the table below.
| URL scheme | Option | Wildcard certificate | Custom domain with HTTP support | Custom domain with HTTPS support | Secondary IP |
| --- |:---:|:---:|:---:|:---:|:---:|:---:|:---:|
| `http://page.example.io` | 1 | no | no | no | no |
| `https://page.example.io` | 1 | yes | no | no | no |
| `http://page.example.io` and `http://page.com` | 2 | no | yes | no | yes |
| `https://page.example.io` and `https://page.com` | 2 | yes | redirects to HTTPS | yes | yes |
As you see from the table above, each URL scheme comes with an option:
1. Pages enabled, daemon is enabled and NGINX will proxy all requests to the
daemon. Pages daemon doesn't listen to the outside world.
1. Pages enabled, daemon is enabled AND pages has external IP support enabled.
In that case, the pages daemon is running, NGINX still proxies requests to
the daemon but the daemon is also able to receive requests from the outside
world. Custom domains and TLS are supported.
### 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.
You should not use the GitLab domain to serve user pages. For more information
see the [security section](#security).
[wiki-wildcard-dns]: https://en.wikipedia.org/wiki/Wildcard_DNS_record
## Setting up GitLab Pages
Below are the four scenarios that are described in
[#configuration-scenarios](#configuration-scenarios).
### Custom domains with HTTPS support
**Source installations:**
1. [Install the pages daemon](#install-the-pages-daemon)
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. Make sure to [configure NGINX](#nginx-configuration) properly.
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.
Read more at the
[NGINX configuration for custom domains](#nginx-configuration-for-custom-domains)
section.
1. [Reconfigure GitLab][reconfigure]
### Custom domains without HTTPS support
**Source installations:**
1. [Install the pages daemon](#install-the-pages-daemon)
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. Make sure to [configure NGINX](#nginx-configuration) properly.
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.
Read more at the
[NGINX configuration for custom domains](#nginx-configuration-for-custom-domains)
section.
1. [Reconfigure GitLab][reconfigure]
### Wildcard HTTP domain without custom domains
**Source installations:**
1. [Install the pages daemon](#install-the-pages-daemon)
1. Go to the GitLab installation directory:
```bash
cd /home/git/gitlab
```
1. Edit `gitlab.yml` and under the `pages` setting, set `enabled` to `true` and
the `host` to the FQDN under which GitLab Pages will be served:
```yaml
## GitLab Pages
pages:
enabled: true
# The location where pages are stored (default: shared/pages).
# path: shared/pages
host: example.io
port: 80
https: false
```
1. Make sure to [configure NGINX](#nginx-configuration) properly.
1. [Restart GitLab][restart]
---
**Omnibus installations:**
1. Set the external URL for GitLab Pages in `/etc/gitlab/gitlab.rb`:
```ruby
pages_external_url 'http://example.io'
```
1. [Reconfigure GitLab][reconfigure]
### Wildcard HTTPS domain without custom domains
**Source installations:**
1. [Install the pages daemon](#install-the-pages-daemon)
1. In `gitlab.yml`, set the port to `443` and https to `true`:
```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. Make sure to [configure NGINX](#nginx-configuration) properly.
---
**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]
## NGINX configuration
Depending on your setup, you will need to make some changes to NGINX.
Specifically you must change the domain name and the IP address where NGINX
listens to. Read the following sections for more details.
### NGINX configuration files
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.
### NGINX configuration for custom domains
> If you are not using custom domains ignore this section.
[In the case of custom domains](#the-gitlab-pages-daemon-and-the-case-of-custom-domains),
if you have the secondary IP address configured on the same server as GitLab,
you need to change **all** NGINX configs to listen on the first IP address.
**Source installations:**
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
**Omnibus installations:**
1. Edit `/etc/gitlab/gilab.rb`:
```
nginx['listen_addresses'] = ['1.1.1.1']
```
1. [Reconfigure GitLab][reconfigure]
### NGINX caveats
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.5 ([documentation][8-5-docs])**
- In GitLab 8.5 we introduced the [gitlab-pages][] daemon which is now the
recommended way to set up GitLab Pages.
- The [NGINX configs][] have changed to reflect this change. So make sure to
update them.
- Custom CNAME and TLS certificates support
- Documentation was moved to one place
[8-5-docs]: https://gitlab.com/gitlab-org/gitlab-ee/blob/8-5-stable-ee/doc/pages/administration.md
[gitlab-pages]: https://gitlab.com/gitlab-org/gitlab-pages/tree/v0.2.1
[NGINX configs]: https://gitlab.com/gitlab-org/gitlab-ee/tree/8-5-stable-ee/lib/support/nginx
---
**GitLab 8.4**
No new changes.
---
**GitLab 8.3 ([source docs][8-3-docs], [Omnibus docs][8-3-omnidocs])**
- GitLab Pages feature was introduced.
[8-3-docs]: https://gitlab.com/gitlab-org/gitlab-ee/blob/8-3-stable-ee/doc/pages/administration.md
[8-3-omnidocs]: https://gitlab.com/gitlab-org/omnibus-gitlab/blob/8-3-stable-ee/doc/settings/pages.md
[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
[reconfigure]: ../administration/restart_gitlab.md#omnibus-gitlab-reconfigure
[restart]: ../administration/restart_gitlab.md#installations-from-source
This document was moved to [administration/pages](../administration/pages/index.md).
doc/university/README.md
View file @ dda3aa8c
......@@ -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. [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
......
doc/university/support/README.md
View file @ dda3aa8c
......@@ -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
- 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)
- 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:
- 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)
......
doc/user/project/pages/index.md 0 → 100644
View file @ dda3aa8c
# GitLab Pages
> **Notes:**
> - 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.
> - This document is about the user guide. To learn how to enable GitLab Pages
> across your GitLab instance, visit the [administrator documentation](../../../administration/pages/index.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
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7