1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
|
# GitLab Pages Administration
> **Note:**
This feature was [introduced][ee-80] in GitLab EE 8.3.
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).
[ee-80]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/80
## Architecture
GitLab uses a separate tool ([gitlab-pages]), a simple HTTP server written in
Go that serves GitLab Pages with CNAMEs and SNI using HTTP/HTTP2. You are
encouraged to read its [README][pages-readme] to fully understand how it works.
[pages-readme]: https://gitlab.com/gitlab-org/gitlab-pages/blob/master/README.md
## Configuration
There are a couple of things to consider before enabling GitLab pages in your
GitLab EE instance.
1. You need to properly configure your DNS to point to the domain that pages
will be served
1. Pages use a separate Nginx configuration file which needs to be explicitly
added in the server under which GitLab EE runs
1. Optionally but recommended, you can add some
[shared runners](../ci/runners/README.md) so that your users don't have to
bring their own.
Both of these settings are described in detail in the sections below.
### DNS configuration
GitLab Pages expect to run on their own virtual host. In your DNS server/provider
you need to add a [wildcard DNS A record][wiki-wildcard-dns] pointing to the
host that GitLab runs. For example, an entry would look like this:
```
*.gitlab.io. 60 IN A 1.2.3.4
```
where `gitlab.io` is the domain under which GitLab Pages will be served
and `1.2.3.4` is the IP address of your GitLab instance.
You should not use the GitLab domain to serve user pages. For more information
see the [security section](#security).
### Omnibus package installations
See the relevant documentation at <http://doc.gitlab.com/omnibus/settings/pages.html>.
### Installations from source
1. Go to the GitLab installation directory:
```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
# The domain under which the pages are served:
# http://group.example.com/project
# or project path can be a group page: group.example.com
host: gitlab.io
port: 80 # Set to 443 if you serve the pages with HTTPS
https: false # Set to true if you serve the pages with HTTPS
```
1. Make sure you have copied the new `gitlab-pages` Nginx configuration file:
```bash
sudo cp lib/support/nginx/gitlab-pages /etc/nginx/sites-available/gitlab-pages.conf
sudo ln -sf /etc/nginx/sites-{available,enabled}/gitlab-pages.conf
```
Don't forget to add your domain name in the Nginx config. For example if
your GitLab pages domain is `gitlab.io`, replace
```bash
server_name ~^(?<group>.*)\.YOUR_GITLAB_PAGES\.DOMAIN$;
```
with
```
server_name ~^(?<group>.*)\.gitlabpages\.com$;
```
You must be extra careful to not remove the backslashes. If you are using
a subdomain, make sure to escape all dots (`.`) with a backslash (\).
For example `pages.gitlab.io` would be:
```
server_name ~^(?<group>.*)\.pages\.gitlab\.io$;
```
1. Restart Nginx and GitLab:
```bash
sudo service nginx restart
sudo service gitlab restart
```
### Running GitLab Pages with HTTPS
If you want the pages to be served under HTTPS, a wildcard SSL certificate is
required.
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
# The domain under which the pages are served:
# http://group.example.com/project
# or project path can be a group page: group.example.com
host: gitlab.io
port: 443 # Set to 443 if you serve the pages with HTTPS
https: true # Set to true if you serve the pages with HTTPS
```
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.conf
```
Make sure to edit the config to add your domain as well as correctly point
to the right location of the SSL certificate files. Restart Nginx for the
changes to take effect.
## Set maximum pages size
The maximum size of the unpacked archive per project can be configured in the
Admin area under the Application settings in the **Maximum size of pages (MB)**.
The default is 100MB.
## Change storage path
Pages are stored by default in `/home/git/gitlab/shared/pages`.
If you wish to store them in another location you must set it up in
`gitlab.yml` under the `pages` section:
```yaml
pages:
enabled: true
# The location where pages are stored (default: shared/pages).
path: /mnt/storage/pages
```
Restart GitLab for the changes to take effect:
```bash
sudo service gitlab restart
```
## Backup
Pages are part of the regular backup so there is nothing to configure.
## Security
You should strongly consider running GitLab pages under a different hostname
than GitLab to prevent XSS attacks.
## Changelog
GitLab Pages were first introduced in GitLab EE 8.3. Since then, many features
where added, like custom CNAME and TLS support, and many more are likely to
come. Below is a brief changelog. If no changes were introduced, assume that
the documentation is the same as the previous version(s).
---
**GitLab 8.5 ([documentation][8-5-docs])**
- In GitLab 8.5 we introduced the [gitlab-pages][] daemon which is now the
recommended way to set up GitLab Pages.
- The [NGINX configs][] have changed to reflect this change. So make sure to
update them.
- Custom CNAME and TLS certificates support
[8-5-docs]: https://gitlab.com/gitlab-org/gitlab-ee/blob/8-5-stable-ee/doc/pages/administration.md
[gitlab-pages]: https://gitlab.com/gitlab-org/gitlab-pages/tree/v0.2.0
[NGINX configs]: https://gitlab.com/gitlab-org/gitlab-ee/tree/8-5-stable-ee/lib/support/nginx
---
**GitLab 8.4**
No new changes.
---
**GitLab 8.3 ([documentation][8-3-docs])**
- GitLab Pages feature was introduced.
[8-3-docs]: https://gitlab.com/gitlab-org/gitlab-ee/blob/8-3-stable-ee/doc/pages/administration.md
---
|
