diff options
author | Achilleas Pipinellis <axilleas@axilleas.me> | 2017-02-16 19:25:59 +0000 |
---|---|---|
committer | Felipe Artur <felipefac@gmail.com> | 2017-02-17 17:25:42 -0200 |
commit | 5ae32ae3ba017d2ae3f5c9fd1ba59d6eac1a219b (patch) | |
tree | daa21da3b06f0bb20bc4b5679f5c13b1aab9c28e | |
parent | a7b32ded035e6d37adb149579a62837f7ed1b66f (diff) | |
download | gitlab-ce-5ae32ae3ba017d2ae3f5c9fd1ba59d6eac1a219b.tar.gz |
Merge branch 'docs/pages-admin' into 'master'
Simplify GitLab Pages admin docs
See merge request !9303
-rw-r--r-- | doc/administration/pages/index.md | 153 | ||||
-rw-r--r-- | doc/administration/pages/source.md | 251 |
2 files changed, 248 insertions, 156 deletions
diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index c352caf1115..1fe68986876 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -1,4 +1,4 @@ -# GitLab Pages Administration +# GitLab Pages administration > **Notes:** - [Introduced][ee-80] in GitLab EE 8.3. @@ -6,6 +6,7 @@ - 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). +- To learn how to use GitLab Pages, read the [user documentation][pages-userguide]. --- @@ -14,9 +15,6 @@ 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 @@ -32,7 +30,7 @@ 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 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. @@ -64,11 +62,11 @@ 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 +*.example.io. 1800 IN A 1.1.1.1 ``` 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. +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 @@ -78,101 +76,126 @@ see the [security section](#security). ## Configuration -Depending on your needs, you can install GitLab Pages in four different ways. +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. -### Option 1. Custom domains with HTTPS support +### Wildcard domains -| 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 | +>**Requirements:** +- [Wildcard DNS setup](#dns-configuration) +> +>--- +> +URL scheme: `http://page.example.io` -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. +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. -1. Edit `/etc/gitlab/gitlab.rb`: +1. Set the external URL for GitLab Pages in `/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' + pages_external_url 'http://example.io' ``` - 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 +### Wildcard domains with TLS 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 | +>**Requirements:** +- [Wildcard DNS setup](#dns-configuration) +- Wildcard TLS certificate +> +>--- +> +URL scheme: `https://page.example.io` -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. +Nginx will proxy all requests to the daemon. Pages daemon doesn't listen to the +outside world. -1. Edit `/etc/gitlab/gitlab.rb`: +1. Place the certificate and key inside `/etc/gitlab/ssl` +1. In `/etc/gitlab/gitlab.rb` specify the following configuration: ```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' + 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 `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. + where `pages-nginx.crt` and `pages-nginx.key` are the SSL cert and key, + respectively. 1. [Reconfigure GitLab][reconfigure] -### Option 3. Wildcard HTTPS domain without custom domains +## Advanced configuration -| URL scheme | Wildcard certificate | Custom domain with HTTP support | Custom domain with HTTPS support | Secondary IP | -| --- |:---:|:---:|:---:|:---:|:---:|:---:|:---:| -| `https://page.example.io` | yes | no | no | no | +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. -Pages enabled, daemon is enabled and NGINX will proxy all requests to the -daemon. Pages daemon doesn't listen to the outside world. +### Custom domains -1. Place the certificate and key inside `/etc/gitlab/ssl` -1. In `/etc/gitlab/gitlab.rb` specify the following configuration: +>**Requirements:** +- [Wildcard DNS setup](#dns-configuration) +- Secondary IP +> +--- +> +URL scheme: `http://page.example.io` and `http://domain.com` - ```ruby - pages_external_url 'https://example.io' +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. - 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" +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 `pages-nginx.crt` and `pages-nginx.key` are the SSL cert and key, - respectively. + 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 4. Wildcard HTTP domain without custom domains +### Custom domains with TLS support -| URL scheme | Wildcard certificate | Custom domain with HTTP support | Custom domain with HTTPS support | Secondary IP | -| --- |:---:|:---:|:---:|:---:|:---:|:---:|:---:| -| `http://page.example.io` | no | no | no | no | +>**Requirements:** +- [Wildcard DNS setup](#dns-configuration) +- Wildcard TLS certificate +- Secondary IP +> +--- +> +URL scheme: `https://page.example.io` and `https://domain.com` -Pages enabled, daemon is enabled and NGINX will proxy all requests to the -daemon. Pages daemon doesn't listen to the outside world. +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. Set the external URL for GitLab Pages in `/etc/gitlab/gitlab.rb`: +1. Edit `/etc/gitlab/gitlab.rb`: ```ruby - pages_external_url 'http://example.io' + 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] ## Change storage path diff --git a/doc/administration/pages/source.md b/doc/administration/pages/source.md index d4468b99992..83efe54c88d 100644 --- a/doc/administration/pages/source.md +++ b/doc/administration/pages/source.md @@ -17,22 +17,54 @@ Pages to the latest supported version. ## Prerequisites -[Read the Omnibus prerequisites section.](index.md#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.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 ## Configuration -Depending on your needs, you can install GitLab Pages in four different ways. +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. -### Option 1. Custom domains with HTTPS support +### Wildcard domains -| 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 | +>**Requirements:** +- [Wildcard DNS setup](#dns-configuration) +> +>--- +> +URL scheme: `http://page.example.io` -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. +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. 1. Install the Pages daemon: @@ -44,10 +76,14 @@ world. Custom domains and TLS are supported. 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: +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 @@ -57,25 +93,10 @@ world. Custom domains and TLS are supported. # path: shared/pages host: example.io - port: 443 - https: true - - external_http: 1.1.1.2:80 - external_https: 1.1.1.2:443 + port: 80 + https: false ``` -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 @@ -85,22 +106,21 @@ world. Custom domains and TLS are supported. 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 +### Wildcard domains with TLS 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 | +>**Requirements:** +- [Wildcard DNS setup](#dns-configuration) +- Wildcard TLS certificate +> +>--- +> +URL scheme: `https://page.example.io` -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. +Nginx will proxy all requests to the daemon. Pages daemon doesn't listen to the +outside world. 1. Install the Pages daemon: @@ -112,34 +132,20 @@ world. Custom domains and TLS are supported. 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: +1. In `gitlab.yml`, set the port to `443` and https to `true`: - ```yaml + ```bash + ## GitLab Pages 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 + port: 443 + https: true ``` -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 @@ -149,20 +155,30 @@ world. Custom domains and TLS are supported. 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 | +## 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. + +### Custom domains -Pages enabled, daemon is enabled and NGINX will proxy all requests to the -daemon. Pages daemon doesn't listen to the outside world. +>**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. 1. Install the Pages daemon: @@ -173,20 +189,35 @@ daemon. Pages daemon doesn't listen to the outside world. 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 +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: 443 - https: true + 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 @@ -196,17 +227,26 @@ daemon. Pages daemon doesn't listen to the outside world. 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 4. Wildcard HTTP domain without custom domains +### Custom domains with TLS support -| URL scheme | Wildcard certificate | Custom domain with HTTP support | Custom domain with HTTPS support | Secondary IP | -| --- |:---:|:---:|:---:|:---:|:---:|:---:|:---:| -| `http://page.example.io` | no | no | no | no | +>**Requirements:** +- [Wildcard DNS setup](#dns-configuration) +- Wildcard TLS certificate +- Secondary IP +> +--- +> +URL scheme: `https://page.example.io` and `https://domain.com` -Pages enabled, daemon is enabled and NGINX will proxy all requests to the -daemon. Pages daemon doesn't listen to the outside world. +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: @@ -218,14 +258,10 @@ daemon. Pages daemon doesn't listen to the outside world. 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: +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 @@ -235,10 +271,25 @@ daemon. Pages daemon doesn't listen to the outside world. # path: shared/pages host: example.io - port: 80 - https: false + 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 @@ -248,9 +299,27 @@ daemon. Pages daemon doesn't listen to the outside world. 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] +## 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] + ## NGINX caveats >**Note:** |