kotovalexarian-likes-gitlab
/
gitlab-org--gitlab-foss
1
0
Fork 0
Code Releases Activity

Add the four scenarios and NGINX caveats

This commit is contained in:
Achilleas Pipinellis 2016-02-22 01:22:28 +02:00 committed by James Edwards-Jones
parent fed8b62c3d
commit d24763fa16
1 changed files with 148 additions and 99 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

247
doc/pages/administration.md
View File

@ -28,11 +28,12 @@ probably want to read the [user documentation](README.md).
- [Configuration](#configuration) - [Configuration](#configuration)
- [Configuration scenarios](#configuration-scenarios) - [Configuration scenarios](#configuration-scenarios)
- [DNS configuration](#dns-configuration) - [DNS configuration](#dns-configuration)
- [Custom domains without TLS](#custom-domains-without-tls) - [Setting up GitLab Pages](#setting-up-gitlab-pages)
- [Custom domains with TLS](#custom-domains-with-tls) - [Custom domains with HTTPS support](#custom-domains-with-https-support)
- [Wildcard HTTPS domain without custom domains](#wildcard-https-domain-without-custom-domains) - [Custom domains without HTTPS support](#custom-domains-without-https-support)
- [Wildcard HTTP domain without custom domains](#wildcard-http-domain-without-custom-domains) - [Wildcard HTTP domain without custom domains](#wildcard-http-domain-without-custom-domains)
- [Omnibus package installations](#omnibus-package-installations) - [Wildcard HTTPS domain without custom domains](#wildcard-https-domain-without-custom-domains)
- [NGINX caveats](#nginx-caveats)
- [Set maximum pages size](#set-maximum-pages-size) - [Set maximum pages size](#set-maximum-pages-size)
- [Change storage path](#change-storage-path) - [Change storage path](#change-storage-path)
- [Backup](#backup) - [Backup](#backup)
@ -145,62 +146,25 @@ 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: host that GitLab runs. For example, an entry would look like this:
``` ```
*.gitlab.io. 60 IN A 1.2.3.4 *.example.io. 1800 IN A 1.2.3.4
``` ```
where `gitlab.io` is the domain under which GitLab Pages will be served 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.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 You should not use the GitLab domain to serve user pages. For more information
see the [security section](#security). see the [security section](#security).
### Omnibus package installations [wiki-wildcard-dns]: https://en.wikipedia.org/wiki/Wildcard_DNS_record
## Custom domains without TLS ## Setting up GitLab Pages
1. [Install the pages daemon](#install-the-pages-daemon) Below are the four scenarios that are described in
1. Edit `gitlab.yml` to look like the example below. You need to change the [#configuration-scenarios](#configuration-scenarios).
`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 ### Custom domains with HTTPS support
pages:
enabled: true
# The location where pages are stored (default: shared/pages).
# path: shared/pages
host: example.io **Source installations:**
port: 80
https: false
external_http: 1.1.1.1: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.1:80"
```
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
```
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.
1. [Restart GitLab](../../administration/restart_gitlab.md)
## Custom domains with TLS
1. [Install the pages daemon](#install-the-pages-daemon) 1. [Install the pages daemon](#install-the-pages-daemon)
1. Edit `gitlab.yml` to look like the example below. You need to change the 1. Edit `gitlab.yml` to look like the example below. You need to change the
@ -242,14 +206,70 @@ see the [security section](#security).
sudo ln -sf /etc/nginx/sites-{available,enabled}/gitlab-pages-ssl.conf sudo ln -sf /etc/nginx/sites-{available,enabled}/gitlab-pages-ssl.conf
``` ```
Make sure to edit the config to add your domain as well as correctly point Make sure to [properly edit the config](#nginx-caveats) to add your domain
to the right location of the SSL certificate files. Restart Nginx for the as well as correctly point to the right location of the SSL certificate
changes to take effect. files. Restart Nginx for the changes to take effect.
1. [Restart GitLab](../../administration/restart_gitlab.md) 1. [Restart GitLab][restart]
## Wildcard HTTPS domain without custom domains ---
**Omnibus installations:**
### Custom domains without HTTPS support
**Source installations:**
1. [Install the pages daemon](#install-the-pages-daemon)
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: 80
https: false
external_http: 1.1.1.1: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.1:80"
```
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
```
Make sure to [properly edit the config](#nginx-caveats) to add your domain.
Restart Nginx for the changes to take effect.
1. [Restart GitLab][restart]
---
**Omnibus installations:**
### Wildcard HTTP domain without custom domains
**Source installations:**
1. [Install the pages daemon](#install-the-pages-daemon)
1. Go to the GitLab installation directory: 1. Go to the GitLab installation directory:
```bash ```bash
@ -266,12 +286,9 @@ see the [security section](#security).
# The location where pages are stored (default: shared/pages). # The location where pages are stored (default: shared/pages).
# path: shared/pages # path: shared/pages
# The domain under which the pages are served: host: example.io
# http://group.example.com/project port: 80
# or project path can be a group page: group.example.com https: false
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: 1. Make sure you have copied the new `gitlab-pages` Nginx configuration file:
@ -281,39 +298,27 @@ see the [security section](#security).
sudo ln -sf /etc/nginx/sites-{available,enabled}/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 Make sure to [properly edit the config](#nginx-caveats) to add your domain.
your GitLab pages domain is `gitlab.io`, replace Restart Nginx for the changes to take effect.
```bash 1. [Restart GitLab][restart]
server_name ~^(?<group>.*)\.YOUR_GITLAB_PAGES\.DOMAIN$;
---
**Omnibus installations:**
1. Set the external URL for GitLab Pages in `/etc/gitlab/gitlab.rb`:
```ruby
pages_external_url 'http://example.io'
``` ```
1. [Reconfigure GitLab][reconfigure]
with ### Wildcard HTTPS domain without custom domains
``` **Source installations:**
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. [Install the pages daemon](#install-the-pages-daemon)
1. In `gitlab.yml`, set the port to `443` and https to `true`: 1. In `gitlab.yml`, set the port to `443` and https to `true`:
```bash ```bash
@ -323,24 +328,65 @@ required.
# The location where pages are stored (default: shared/pages). # The location where pages are stored (default: shared/pages).
# path: shared/pages # path: shared/pages
# The domain under which the pages are served: host: example.io
# http://group.example.com/project port: 443
# or project path can be a group page: group.example.com https: true
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: 1. Copy the `gitlab-pages-ssl` Nginx configuration file:
```bash ```bash
sudo cp lib/support/nginx/gitlab-pages-ssl /etc/nginx/sites-available/gitlab-pages-ssl.conf 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 sudo ln -sf /etc/nginx/sites-{available,enabled}/gitlab-pages-ssl.conf
``` ```
Make sure to edit the config to add your domain as well as correctly point Make sure to [properly edit the config](#nginx-caveats) to add your domain
to the right location of the SSL certificate files. Restart Nginx for the as well as correctly point to the right location of the SSL certificate
changes to take effect. files. Restart Nginx for the changes to take effect.
---
**Omnibus installations:**
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'
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 `pages-nginx.crt` and `pages-nginx.key` are the SSL cert and key,
respectively.
1. [Reconfigure GitLab][reconfigure]
## NGINX caveats
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 ~^(?<group>.*)\.YOUR_GITLAB_PAGES\.DOMAIN$;
```
with:
```
server_name ~^(?<group>.*)\.example\.io$;
```
If you are using a subdomain, make sure to escape all dots (`.`) with a
backslash (\). For example `pages.example.io` would be:
```
server_name ~^(?<group>.*)\.pages\.example\.io$;
```
## Set maximum pages size ## Set maximum pages size
@ -413,3 +459,6 @@ No new changes.
[8-3-docs]: https://gitlab.com/gitlab-org/gitlab-ee/blob/8-3-stable-ee/doc/pages/administration.md [8-3-docs]: https://gitlab.com/gitlab-org/gitlab-ee/blob/8-3-stable-ee/doc/pages/administration.md
--- ---
[reconfigure]: ../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure
[restart]: ../../administration/restart_gitlab.md#installations-from-source