diff options
Diffstat (limited to 'doc/administration/pages/index.md')
| -rw-r--r-- | doc/administration/pages/index.md | 47 |
1 files changed, 29 insertions, 18 deletions
diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 8de0cc5af5c..0c63b0b59a7 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -26,22 +26,24 @@ 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: +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 +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 + 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. +In this document, we will proceed assuming the first option. If you are not +supporting custom domains a secondary IP is not needed. ## Prerequisites @@ -54,6 +56,7 @@ Before proceeding with the Pages configuration, you will need 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. +1. (Only for custom domains) Have a **secondary IP**. ### DNS configuration @@ -62,11 +65,13 @@ 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 +*.example.io. 1800 IN A 1.1.1.1 +*.example.io. 1800 IN AAAA 2001::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. +and `1.1.1.1` is the IPv4 address of your GitLab instance and `2001::1` is the +IPv6 address. If you don't have IPv6, you can omit the AAAA record. > **Note:** You should not use the GitLab domain to serve user pages. For more information @@ -102,6 +107,8 @@ The Pages daemon doesn't listen to the outside world. 1. [Reconfigure GitLab][reconfigure] +Watch the [video tutorial][video-admin] for this configuration. + ### Wildcard domains with TLS support >**Requirements:** @@ -136,7 +143,8 @@ outside world. 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. +that without TLS certificates. In either case, you'll need a secondary IP. If +you have IPv6 as well as IPv4 addresses, you can use them both. ### Custom domains @@ -148,7 +156,7 @@ that without TLS certificates. > URL scheme: `http://page.example.io` and `http://domain.com` -In that case, the pages daemon is running, Nginx still proxies requests to +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. @@ -158,11 +166,12 @@ world. Custom domains are supported, but no TLS. 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' + gitlab_pages['external_http'] = ['1.1.1.2:80', '[2001::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.1.1.2` and `2001::2` are the secondary IPs the GitLab Pages daemon + listens on. If you don't have IPv6, you can omit the IPv6 address. 1. [Reconfigure GitLab][reconfigure] @@ -177,7 +186,7 @@ world. Custom domains are supported, but no TLS. > URL scheme: `https://page.example.io` and `https://domain.com` -In that case, the pages daemon is running, Nginx still proxies requests to +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. @@ -189,12 +198,13 @@ world. Custom domains and TLS are supported. 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' + gitlab_pages['external_http'] = ['1.1.1.2:80', '[2001::2]:80'] + gitlab_pages['external_https'] = ['1.1.1.2:443', '[2001::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.1.1.2` and `2001::2` are the secondary IPs where the GitLab Pages daemon + listens on. If you don't have IPv6, you can omit the IPv6 address. 1. [Reconfigure GitLab][reconfigure] @@ -270,3 +280,4 @@ latest previous version. [reconfigure]: ../restart_gitlab.md#omnibus-gitlab-reconfigure [restart]: ../restart_gitlab.md#installations-from-source [gitlab-pages]: https://gitlab.com/gitlab-org/gitlab-pages/tree/v0.2.4 +[video-admin]: https://youtu.be/dD8c7WNcc6s |