source.md 14.4 KB
Newer Older
1 2
# GitLab Pages administration for source installations

3 4 5 6
>**Note:**
Before attempting to enable GitLab Pages, first make sure you have
[installed GitLab](../../install/installation.md) successfully.

7 8 9 10 11 12 13 14 15 16 17 18 19
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

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
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](#custom-domains) (but not
[wildcard domains](#wildcard-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. If you are not
supporting custom domains a secondary IP is not needed.
47 48 49

## Prerequisites

50 51 52 53 54 55 56 57 58 59 60
Before proceeding with the Pages configuration, make sure that:

1. You have a separate domain under which GitLab Pages will be served. In
   this document we assume that to be `example.io`.
1. You have configured a **wildcard DNS record** for that domain.
1. You have installed the `zip` and `unzip` packages in the same server that
   GitLab is installed since they are needed to compress/uncompress the
   Pages artifacts.
1. (Optional) You have a **wildcard certificate** for the Pages domain if you
   decide to serve Pages (`*.example.io`) under HTTPS.
1. (Optional but recommended) You have configured and enabled the [Shared Runners][]
61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80
   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.1.1.1
```

where `example.io` is the domain under which GitLab Pages will be served
and `1.1.1.1` 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
81 82 83

## Configuration

84 85 86 87
Depending on your needs, you can set up GitLab Pages in 4 different ways.
The following options are listed from the easiest setup to the most
advanced one. The absolute minimum requirement is to set up the wildcard DNS
since that is needed in all configurations.
88

89
### Wildcard domains
90

91 92 93 94 95 96
>**Requirements:**
- [Wildcard DNS setup](#dns-configuration)
>
>---
>
URL scheme: `http://page.example.io`
97

98 99 100
This is the minimum setup that you can use Pages with. It is the base for all
other setups as described below. Nginx will proxy all requests to the daemon.
The Pages daemon doesn't listen to the outside world.
101 102 103 104 105 106 107

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
108
    sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION)
109 110 111
    sudo -u git -H make
    ```

112 113 114 115 116 117 118 119
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:
120 121 122 123 124 125 126 127 128

     ```yaml
     ## GitLab Pages
     pages:
       enabled: true
       # The location where pages are stored (default: shared/pages).
       # path: shared/pages

       host: example.io
129 130
       port: 80
       https: false
131 132
     ```

133 134 135
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` must match the `host` setting that you set above.
136 137

    ```
138 139 140 141 142
    gitlab_pages_enabled=true
    gitlab_pages_options="-pages-domain example.io -pages-root $app_root/shared/pages -listen-proxy 127.0.0.1:8090
    ```

1. Copy the `gitlab-pages` Nginx configuration file:
143

144 145 146 147
    ```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
    ```
148 149 150 151

1. Restart NGINX
1. [Restart GitLab][restart]

152
### Wildcard domains with TLS support
153

154 155 156 157 158 159 160
>**Requirements:**
- [Wildcard DNS setup](#dns-configuration)
- Wildcard TLS certificate
>
>---
>
URL scheme: `https://page.example.io`
161

162 163
Nginx will proxy all requests to the daemon. Pages daemon doesn't listen to the
outside world.
164 165 166 167 168 169 170

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
171
    sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION)
172 173 174
    sudo -u git -H make
    ```

175
1. In `gitlab.yml`, set the port to `443` and https to `true`:
176

177 178
     ```bash
     ## GitLab Pages
179 180 181 182 183 184
     pages:
       enabled: true
       # The location where pages are stored (default: shared/pages).
       # path: shared/pages

       host: example.io
185 186
       port: 443
       https: true
187 188
     ```

189 190 191 192 193 194 195 196 197 198 199
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` must match the `host` setting that you set above.
   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 -root-cert /path/to/example.io.crt -root-key /path/to/example.io.key
    ```

200 201 202 203 204 205 206 207 208 209
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
    ```

1. Restart NGINX
1. [Restart GitLab][restart]

210 211 212 213 214 215
## Advanced configuration

In addition to the wildcard domains, you can also have the option to configure
GitLab Pages to work with custom domains. Again, there are two options here:
support custom domains with and without TLS certificates. The easiest setup is
that without TLS certificates.
216

217 218 219 220 221 222 223 224 225 226 227 228 229
### Custom domains

>**Requirements:**
- [Wildcard DNS setup](#dns-configuration)
- Secondary IP
>
---
>
URL scheme: `http://page.example.io` and `http://domain.com`

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 are supported, but no TLS.
230 231 232 233 234 235 236

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
237
    sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION)
238 239 240
    sudo -u git -H make
    ```

241 242 243 244 245 246
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
247 248 249 250 251 252
     pages:
       enabled: true
       # The location where pages are stored (default: shared/pages).
       # path: shared/pages

       host: example.io
253 254 255 256
       port: 80
       https: false

       external_http: 1.1.1.2:80
257 258
     ```

259 260 261 262 263 264 265 266 267 268
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"
    ```

269 270 271
1. Copy the `gitlab-pages-ssl` Nginx configuration file:

    ```bash
272 273
    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
274 275
    ```

276 277 278
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.
279 280 281
1. Restart NGINX
1. [Restart GitLab][restart]

282
### Custom domains with TLS support
283

284 285 286 287 288 289 290 291
>**Requirements:**
- [Wildcard DNS setup](#dns-configuration)
- Wildcard TLS certificate
- Secondary IP
>
---
>
URL scheme: `https://page.example.io` and `https://domain.com`
292

293 294 295
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.
296 297 298 299 300 301 302

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
303
    sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION)
304 305 306
    sudo -u git -H make
    ```

307 308 309 310
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:
311 312 313 314 315 316 317 318 319

     ```yaml
     ## GitLab Pages
     pages:
       enabled: true
       # The location where pages are stored (default: shared/pages).
       # path: shared/pages

       host: example.io
320 321 322 323 324
       port: 443
       https: true

       external_http: 1.1.1.2:80
       external_https: 1.1.1.2:443
325 326
     ```

327 328 329 330 331 332 333 334 335 336 337 338
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
    ```

339 340 341 342 343 344 345
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
    ```

346 347 348
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.
349 350 351
1. Restart NGINX
1. [Restart GitLab][restart]

352 353 354 355 356 357 358 359 360 361 362 363 364 365 366
## 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]

367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426
## 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.

427
[backup]: ../../raketasks/backup_restore.md
428 429 430 431 432 433
[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
434 435
[reconfigure]: ../restart_gitlab.md#omnibus-gitlab-reconfigure
[restart]: ../restart_gitlab.md#installations-from-source
436
[gitlab-pages]: https://gitlab.com/gitlab-org/gitlab-pages/tree/v0.4.0
437
[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/support/init.d/gitlab.default.example
438
[shared runners]: ../../ci/runners/README.md