summaryrefslogtreecommitdiff
path: root/doc/administration
diff options
context:
space:
mode:
authorAchilleas Pipinellis <axilleas@axilleas.me>2017-02-16 13:39:42 +0100
committerAchilleas Pipinellis <axilleas@axilleas.me>2017-02-16 13:39:53 +0100
commit97ece6ace27543ce408ca85740a2734c4902122d (patch)
tree402ca3df2c091119b2c36fb760416f10fcbca1ee /doc/administration
parent58cf7db157676d637f9baa3488b2893f2f49a3c5 (diff)
downloadgitlab-ce-97ece6ace27543ce408ca85740a2734c4902122d.tar.gz
Simplify Pages admin source docsdocs/pages-admin
[ci skip]
Diffstat (limited to 'doc/administration')
-rw-r--r--doc/administration/pages/source.md251
1 files changed, 160 insertions, 91 deletions
diff --git a/doc/administration/pages/source.md b/doc/administration/pages/source.md
index 0718c05a6f4..463715e48ca 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:**