diff options
author | Felipe Artur <felipefac@gmail.com> | 2017-02-17 22:05:52 +0300 |
---|---|---|
committer | Felipe Artur <felipefac@gmail.com> | 2017-02-17 22:05:52 +0300 |
commit | a7b32ded035e6d37adb149579a62837f7ed1b66f (patch) | |
tree | ff888aab8b4cdfc858c15b1d367f4144f254ddd2 /doc | |
parent | 3990ee4f9cd0793b55b26115c768275a57824997 (diff) |
Revert "Merge branch 'docs/pages-admin' into 'master'
"
This reverts commit c824e37f8cc507bb48578c363876de69869cf85a.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/administration/pages/index.md | 153 | ||||
-rw-r--r-- | doc/administration/pages/source.md | 251 |
2 files changed, 156 insertions, 248 deletions
diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 1fe68986876..c352caf1115 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,7 +6,6 @@ - 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]. --- @@ -15,6 +14,9 @@ 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 @@ -30,7 +32,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. @@ -62,11 +64,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.1.1.1 +*.example.io. 1800 IN A 1.2.3.4 ``` 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.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 @@ -76,81 +78,46 @@ see the [security section](#security). ## Configuration -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. - -### Wildcard domains - ->**Requirements:** -- [Wildcard DNS setup](#dns-configuration) -> ->--- -> -URL scheme: `http://page.example.io` - -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. Set the external URL for GitLab Pages in `/etc/gitlab/gitlab.rb`: - - ```ruby - pages_external_url 'http://example.io' - ``` - -1. [Reconfigure GitLab][reconfigure] +Depending on your needs, you can install GitLab Pages in four different ways. -### Wildcard domains with TLS support +### Option 1. Custom domains with HTTPS support ->**Requirements:** -- [Wildcard DNS setup](#dns-configuration) -- Wildcard TLS certificate -> ->--- -> -URL scheme: `https://page.example.io` +| 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 | -Nginx will proxy all requests to the daemon. Pages daemon doesn't listen to the -outside world. +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. Place the certificate and key inside `/etc/gitlab/ssl` -1. In `/etc/gitlab/gitlab.rb` specify the following configuration: +1. Edit `/etc/gitlab/gitlab.rb`: ```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" + 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 `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] -## 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 +### Option 2. Custom domains without HTTPS support ->**Requirements:** -- [Wildcard DNS setup](#dns-configuration) -- Secondary IP -> ---- -> -URL scheme: `http://page.example.io` and `http://domain.com` +| 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 | -In that case, the pages daemon is running, Nginx still proxies requests to +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 are supported, but no TLS. +world. Custom domains and TLS are supported. 1. Edit `/etc/gitlab/gitlab.rb`: @@ -166,35 +133,45 @@ world. Custom domains are supported, but no TLS. 1. [Reconfigure GitLab][reconfigure] -### Custom domains with TLS support +### Option 3. Wildcard HTTPS domain without custom domains ->**Requirements:** -- [Wildcard DNS setup](#dns-configuration) -- Wildcard TLS certificate -- Secondary IP -> ---- -> -URL scheme: `https://page.example.io` and `https://domain.com` +| 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 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. +Pages enabled, daemon is enabled and 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 "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 '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 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] diff --git a/doc/administration/pages/source.md b/doc/administration/pages/source.md index 83efe54c88d..d4468b99992 100644 --- a/doc/administration/pages/source.md +++ b/doc/administration/pages/source.md @@ -17,54 +17,22 @@ Pages to the latest supported version. ## 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 +[Read the Omnibus prerequisites section.](index.md#prerequisites) ## Configuration -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. +Depending on your needs, you can install GitLab Pages in four different ways. -### Wildcard domains +### Option 1. Custom domains with HTTPS support ->**Requirements:** -- [Wildcard DNS setup](#dns-configuration) -> ->--- -> -URL scheme: `http://page.example.io` +| 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 | -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. +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: @@ -76,14 +44,10 @@ The 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 @@ -93,59 +57,25 @@ The Pages daemon doesn't listen to the outside world. # 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] - -### Wildcard domains with TLS support - ->**Requirements:** -- [Wildcard DNS setup](#dns-configuration) -- Wildcard TLS certificate -> ->--- -> -URL scheme: `https://page.example.io` + port: 443 + https: true -Nginx will proxy all requests to the daemon. Pages daemon doesn't listen to the -outside world. + external_http: 1.1.1.2:80 + external_https: 1.1.1.2:443 + ``` -1. Install the Pages daemon: +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: ``` - 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 + 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. 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 @@ -155,30 +85,22 @@ 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 2. Custom domains without HTTPS support -## Advanced configuration +| 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 | -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 - ->**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 +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 are supported, but no TLS. +world. Custom domains and TLS are supported. 1. Install the Pages daemon: @@ -233,20 +155,14 @@ world. Custom domains are supported, but no TLS. 1. Restart NGINX 1. [Restart GitLab][restart] -### Custom domains with TLS support +### Option 3. Wildcard HTTPS domain without custom domains ->**Requirements:** -- [Wildcard DNS setup](#dns-configuration) -- Wildcard TLS certificate -- Secondary IP -> ---- -> -URL scheme: `https://page.example.io` and `https://domain.com` +| 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 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. +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: @@ -257,13 +173,9 @@ world. Custom domains and TLS are supported. 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`: -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 + ```bash ## GitLab Pages pages: enabled: true @@ -273,23 +185,8 @@ world. Custom domains and TLS are supported. 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 @@ -299,26 +196,60 @@ 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] -## Change storage path +### Option 4. Wildcard HTTP domain without custom domains -Follow the steps below to change the default path where GitLab Pages' contents -are stored. +| URL scheme | Wildcard certificate | Custom domain with HTTP support | Custom domain with HTTPS support | Secondary IP | +| --- |:---:|:---:|:---:|:---:|:---:|:---:|:---:| +| `http://page.example.io` | no | no | no | no | -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`: +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: - ```ruby - gitlab_rails['pages_path'] = "/mnt/storage/pages" + ``` + 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. [Reconfigure GitLab][reconfigure] +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 |