diff options
Diffstat (limited to 'doc/pages')
-rw-r--r-- | doc/pages/README.md | 436 | ||||
-rw-r--r-- | doc/pages/administration.md | 497 | ||||
-rw-r--r-- | doc/pages/img/pages_create_project.png | bin | 33597 -> 0 bytes | |||
-rw-r--r-- | doc/pages/img/pages_create_user_page.png | bin | 87071 -> 0 bytes | |||
-rw-r--r-- | doc/pages/img/pages_dns_details.png | bin | 34686 -> 0 bytes | |||
-rw-r--r-- | doc/pages/img/pages_multiple_domains.png | bin | 63716 -> 0 bytes | |||
-rw-r--r-- | doc/pages/img/pages_new_domain_button.png | bin | 51136 -> 0 bytes | |||
-rw-r--r-- | doc/pages/img/pages_remove.png | bin | 27259 -> 0 bytes | |||
-rw-r--r-- | doc/pages/img/pages_upload_cert.png | bin | 103730 -> 0 bytes |
9 files changed, 2 insertions, 931 deletions
diff --git a/doc/pages/README.md b/doc/pages/README.md index e427d7f283d..44b74513fd9 100644 --- a/doc/pages/README.md +++ b/doc/pages/README.md @@ -1,435 +1 @@ -# GitLab Pages - -> **Note:** -> This feature was [introduced][ee-80] in GitLab EE 8.3. -> Custom CNAMEs with TLS support were [introduced][ee-173] in GitLab EE 8.5. - -> **Note:** -> This document is about the user guide. To learn how to enable GitLab Pages -> across your GitLab instance, visit the [administrator documentation](administration.md). - -With GitLab Pages you can host for free your static websites on GitLab. -Combined with the power of [GitLab CI] and the help of [GitLab Runner] you can -deploy static pages for your individual projects, your user or your group. - -Read [GitLab Pages on GitLab.com](#gitlab-pages-on-gitlab-com) for specific -information, if you are using GitLab.com to host your website. - -## Getting started with GitLab Pages - -> **Note:** -> In the rest of this document we will assume that the general domain name that -> is used for GitLab Pages is `example.io`. - -In general there are two types of pages one might create: - -- Pages per user (`username.example.io`) or per group (`groupname.example.io`) -- Pages per project (`username.example.io/projectname` or `groupname.example.io/projectname`) - -In GitLab, usernames and groupnames are unique and we often refer to them -as namespaces. There can be only one namespace in a GitLab instance. Below you -can see the connection between the type of GitLab Pages, what the project name -that is created on GitLab looks like and the website URL it will be ultimately -be served on. - -| Type of GitLab Pages | The name of the project created in GitLab | Website URL | -| -------------------- | ------------ | ----------- | -| User pages | `username.example.io` | `http(s)://username.example.io` | -| Group pages | `groupname.example.io` | `http(s)://groupname.example.io` | -| Project pages owned by a user | `projectname` | `http(s)://username.example.io/projectname` | -| Project pages owned by a group | `projectname` | `http(s)://groupname.example.io/projectname`| - -> **Warning:** -> There are some known [limitations](#limitations) regarding namespaces served -> under the general domain name and HTTPS. Make sure to read that section. - -### GitLab Pages requirements - -In brief, this is what you need to upload your website in GitLab Pages: - -1. Find out the general domain name that is used for GitLab Pages - (ask your administrator). This is very important, so you should first make - sure you get that right. -1. Create a project -1. Push a [`.gitlab-ci.yml` file](../ci/yaml/README.md) in the root directory - of your repository with a specific job named [`pages`][pages] -1. Set up a GitLab Runner to build your website - -> **Note:** -> If [shared runners](../ci/runners/README.md) are enabled by your GitLab -> administrator, you should be able to use them instead of bringing your own. - -### User or group Pages - -For user and group pages, the name of the project should be specific to the -username or groupname and the general domain name that is used for GitLab Pages. -Head over your GitLab instance that supports GitLab Pages and create a -repository named `username.example.io`, where `username` is your username on -GitLab. If the first part of the project name doesn't match exactly your -username, it won’t work, so make sure to get it right. - -To create a group page, the steps are the same like when creating a website for -users. Just make sure that you are creating the project within the group's -namespace. - -![Create a user-based pages project](img/pages_create_user_page.png) - ---- - -After you push some static content to your repository and GitLab Runner uploads -the artifacts to GitLab CI, you will be able to access your website under -`http(s)://username.example.io`. Keep reading to find out how. - ->**Note:** -If your username/groupname contains a dot, for example `foo.bar`, you will not -be able to use the wildcard domain HTTPS, read more at [limitations](#limitations). - -### Project Pages - -GitLab Pages for projects can be created by both user and group accounts. -The steps to create a project page for a user or a group are identical: - -1. Create a new project -1. Push a [`.gitlab-ci.yml` file](../ci/yaml/README.md) in the root directory - of your repository with a specific job named [`pages`][pages]. -1. Set up a GitLab Runner to build your website - -A user's project will be served under `http(s)://username.example.io/projectname` -whereas a group's project under `http(s)://groupname.example.io/projectname`. - -### Explore the contents of `.gitlab-ci.yml` - -The key thing about GitLab Pages is the `.gitlab-ci.yml` file, something that -gives you absolute control over the build process. You can actually watch your -website being built live by following the CI build traces. - -> **Note:** -> Before reading this section, make sure you familiarize yourself with GitLab CI -> and the specific syntax of[`.gitlab-ci.yml`](../ci/yaml/README.md) by -> following our [quick start guide](../ci/quick_start/README.md). - -To make use of GitLab Pages, the contents of `.gitlab-ci.yml` must follow the -rules below: - -1. A special job named [`pages`][pages] must be defined -1. Any static content which will be served by GitLab Pages must be placed under - a `public/` directory -1. `artifacts` with a path to the `public/` directory must be defined - -In its simplest form, `.gitlab-ci.yml` looks like: - -```yaml -pages: - script: - - my_commands - artifacts: - paths: - - public -``` - -When the Runner reaches to build the `pages` job, it executes whatever is -defined in the `script` parameter and if the build completes with a non-zero -exit status, it then uploads the `public/` directory to GitLab Pages. - -The `public/` directory should contain all the static content of your website. -Depending on how you plan to publish your website, the steps defined in the -[`script` parameter](../ci/yaml/README.md#script) may differ. - -Be aware that Pages are by default branch/tag agnostic and their deployment -relies solely on what you specify in `.gitlab-ci.yml`. If you don't limit the -`pages` job with the [`only` parameter](../ci/yaml/README.md#only-and-except), -whenever a new commit is pushed to whatever branch or tag, the Pages will be -overwritten. In the example below, we limit the Pages to be deployed whenever -a commit is pushed only on the `master` branch: - -```yaml -pages: - script: - - my_commands - artifacts: - paths: - - public - only: - - master -``` - -We then tell the Runner to treat the `public/` directory as `artifacts` and -upload it to GitLab. And since all these parameters were all under a `pages` -job, the contents of the `public` directory will be served by GitLab Pages. - -#### How `.gitlab-ci.yml` looks like when the static content is in your repository - -Supposedly your repository contained the following files: - -``` -├── index.html -├── css -│ └── main.css -└── js - └── main.js -``` - -Then the `.gitlab-ci.yml` example below simply moves all files from the root -directory of the project to the `public/` directory. The `.public` workaround -is so `cp` doesn't also copy `public/` to itself in an infinite loop: - -```yaml -pages: - script: - - mkdir .public - - cp -r * .public - - mv .public public - artifacts: - paths: - - public - only: - - master -``` - -#### How `.gitlab-ci.yml` looks like when using a static generator - -In general, GitLab Pages support any kind of [static site generator][staticgen], -since `.gitlab-ci.yml` can be configured to run any possible command. - -In the root directory of your Git repository, place the source files of your -favorite static generator. Then provide a `.gitlab-ci.yml` file which is -specific to your static generator. - -The example below, uses [Jekyll] to build the static site: - -```yaml -image: ruby:2.1 # the script will run in Ruby 2.1 using the Docker image ruby:2.1 - -pages: # the build job must be named pages - script: - - gem install jekyll # we install jekyll - - jekyll build -d public/ # we tell jekyll to build the site for us - artifacts: - paths: - - public # this is where the site will live and the Runner uploads it in GitLab - only: - - master # this script is only affecting the master branch -``` - -Here, we used the Docker executor and in the first line we specified the base -image against which our builds will run. - -You have to make sure that the generated static files are ultimately placed -under the `public` directory, that's why in the `script` section we run the -`jekyll` command that builds the website and puts all content in the `public/` -directory. Depending on the static generator of your choice, this command will -differ. Search in the documentation of the static generator you will use if -there is an option to explicitly set the output directory. If there is not -such an option, you can always add one more line under `script` to rename the -resulting directory in `public/`. - -We then tell the Runner to treat the `public/` directory as `artifacts` and -upload it to GitLab. - ---- - -See the [jekyll example project][pages-jekyll] to better understand how this -works. - -For a list of Pages projects, see the [example projects](#example-projects) to -get you started. - -#### How to set up GitLab Pages in a repository where there's also actual code - -Remember that GitLab Pages are by default branch/tag agnostic and their -deployment relies solely on what you specify in `.gitlab-ci.yml`. You can limit -the `pages` job with the [`only` parameter](../ci/yaml/README.md#only-and-except), -whenever a new commit is pushed to a branch that will be used specifically for -your pages. - -That way, you can have your project's code in the `master` branch and use an -orphan branch (let's name it `pages`) that will host your static generator site. - -You can create a new empty branch like this: - -```bash -git checkout --orphan pages -``` - -The first commit made on this new branch will have no parents and it will be -the root of a new history totally disconnected from all the other branches and -commits. Push the source files of your static generator in the `pages` branch. - -Below is a copy of `.gitlab-ci.yml` where the most significant line is the last -one, specifying to execute everything in the `pages` branch: - -``` -image: ruby:2.1 - -pages: - script: - - gem install jekyll - - jekyll build -d public/ - artifacts: - paths: - - public - only: - - pages -``` - -See an example that has different files in the [`master` branch][jekyll-master] -and the source files for Jekyll are in a [`pages` branch][jekyll-pages] which -also includes `.gitlab-ci.yml`. - -[jekyll-master]: https://gitlab.com/pages/jekyll-branched/tree/master -[jekyll-pages]: https://gitlab.com/pages/jekyll-branched/tree/pages - -## Next steps - -So you have successfully deployed your website, congratulations! Let's check -what more you can do with GitLab Pages. - -### Example projects - -Below is a list of example projects for GitLab Pages with a plain HTML website -or various static site generators. Contributions are very welcome. - -- [Plain HTML](https://gitlab.com/pages/plain-html) -- [Jekyll](https://gitlab.com/pages/jekyll) -- [Hugo](https://gitlab.com/pages/hugo) -- [Middleman](https://gitlab.com/pages/middleman) -- [Hexo](https://gitlab.com/pages/hexo) -- [Brunch](https://gitlab.com/pages/brunch) -- [Metalsmith](https://gitlab.com/pages/metalsmith) -- [Harp](https://gitlab.com/pages/harp) - -Visit the GitLab Pages group for a full list of example projects: -<https://gitlab.com/groups/pages>. - -### Add a custom domain to your Pages website - -If this setting is enabled by your GitLab administrator, you should be able to -see the **New Domain** button when visiting your project's settings through the -gear icon in the top right and then navigating to **Pages**. - -![New domain button](img/pages_new_domain_button.png) - ---- - -You can add multiple domains pointing to your website hosted under GitLab. -Once the domain is added, you can see it listed under the **Domains** section. - -![Pages multiple domains](img/pages_multiple_domains.png) - ---- - -As a last step, you need to configure your DNS and add a CNAME pointing to your -user/group page. Click on the **Details** button of a domain for further -instructions. - -![Pages DNS details](img/pages_dns_details.png) - ---- - ->**Note:** -Currently there is support only for custom domains on per-project basis. That -means that if you add a custom domain (`example.com`) for your user website -(`username.example.io`), a project that is served under `username.example.io/foo`, -will not be accessible under `example.com/foo`. - -### Secure your custom domain website with TLS - -When you add a new custom domain, you also have the chance to add a TLS -certificate. If this setting is enabled by your GitLab administrator, you -should be able to see the option to upload the public certificate and the -private key when adding a new domain. - -![Pages upload cert](img/pages_upload_cert.png) - -### Custom error codes pages - -You can provide your own 403 and 404 error pages by creating the `403.html` and -`404.html` files respectively in the root directory of the `public/` directory -that will be included in the artifacts. Usually this is the root directory of -your project, but that may differ depending on your static generator -configuration. - -If the case of `404.html`, there are different scenarios. For example: - -- If you use project Pages (served under `/projectname/`) and try to access - `/projectname/non/exsiting_file`, GitLab Pages will try to serve first - `/projectname/404.html`, and then `/404.html`. -- If you use user/group Pages (served under `/`) and try to access - `/non/existing_file` GitLab Pages will try to serve `/404.html`. -- If you use a custom domain and try to access `/non/existing_file`, GitLab - Pages will try to serve only `/404.html`. - -### Remove the contents of your pages - -If you ever feel the need to purge your Pages content, you can do so by going -to your project's settings through the gear icon in the top right, and then -navigating to **Pages**. Hit the **Remove pages** button and your Pages website -will be deleted. Simple as that. - -![Remove pages](img/pages_remove.png) - -## GitLab Pages on GitLab.com - -If you are using GitLab.com to host your website, then: - -- The general domain name for GitLab Pages on GitLab.com is `gitlab.io`. -- Custom domains and TLS support are enabled. -- Shared runners are enabled by default, provided for free and can be used to - build your website. If you want you can still bring your own Runner. - -The rest of the guide still applies. - -## Limitations - -When using Pages under the general domain of a GitLab instance (`*.example.io`), -you _cannot_ use HTTPS with sub-subdomains. That means that if your -username/groupname contains a dot, for example `foo.bar`, the domain -`https://foo.bar.example.io` will _not_ work. This is a limitation of the -[HTTP Over TLS protocol][rfc]. HTTP pages will continue to work provided you -don't redirect HTTP to HTTPS. - -[rfc]: https://tools.ietf.org/html/rfc2818#section-3.1 "HTTP Over TLS RFC" - -## Redirects in GitLab Pages - -Since you cannot use any custom server configuration files, like `.htaccess` or -any `.conf` file for that matter, if you want to redirect a web page to another -location, you can use the [HTTP meta refresh tag][metarefresh]. - -Some static site generators provide plugins for that functionality so that you -don't have to create and edit HTML files manually. For example, Jekyll has the -[redirect-from plugin](https://github.com/jekyll/jekyll-redirect-from). - -## Frequently Asked Questions - -### Can I download my generated pages? - -Sure. All you need to do is download the artifacts archive from the build page. - -### Can I use GitLab Pages if my project is private? - -Yes. GitLab Pages don't care whether you set your project's visibility level -to private, internal or public. - -### Do I need to create a user/group website before creating a project website? - -No, you don't. You can create your project first and it will be accessed under -`http(s)://namespace.example.io/projectname`. - -## Known issues - -For a list of known issues, visit GitLab's [public issue tracker]. - ---- - -[jekyll]: http://jekyllrb.com/ -[ee-80]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/80 -[ee-173]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/173 -[pages-daemon]: https://gitlab.com/gitlab-org/gitlab-pages -[gitlab ci]: https://about.gitlab.com/gitlab-ci -[gitlab runner]: https://gitlab.com/gitlab-org/gitlab-ci-multi-runner -[pages]: ../ci/yaml/README.md#pages -[staticgen]: https://www.staticgen.com/ -[pages-jekyll]: https://gitlab.com/pages/jekyll -[metarefresh]: https://en.wikipedia.org/wiki/Meta_refresh -[public issue tracker]: https://gitlab.com/gitlab-org/gitlab-ee/issues?label_name=Pages +This document was moved to [user/project/pages](../user/project/pages). diff --git a/doc/pages/administration.md b/doc/pages/administration.md index 9a94282a229..4eb3bb32c77 100644 --- a/doc/pages/administration.md +++ b/doc/pages/administration.md @@ -1,496 +1 @@ -# GitLab Pages Administration - -> **Notes:** -> - [Introduced][ee-80] in GitLab EE 8.3. -> - Custom CNAMEs with TLS support were [introduced][ee-173] in GitLab EE 8.5. -> - GitLab Pages were ported to Community Edition in GitLab 8.16. - ---- - -This document describes how to set up the _latest_ GitLab Pages feature. Make -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](README.md). - -## Overview - -GitLab Pages makes use of the [GitLab Pages daemon], a simple HTTP server -written in Go that can listen on an external IP address and provide support for -custom domains and custom certificates. It supports dynamic certificates through -SNI and exposes pages using HTTP2 by default. -You are encouraged to read its [README][pages-readme] to fully understand how -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: - -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 - 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. - -## Prerequisites - -Before proceeding with the Pages configuration, you will need to: - -1. Have a separate domain under which the GitLab Pages will be served -1. (Optional) Have a wildcard certificate for that domain if you decide to serve - Pages under HTTPS -1. Configure a wildcard DNS record -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.2.3.4 -``` - -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. - -> **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. - -### Option 1. Custom domains with HTTPS support - -| 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 | - -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. - -**Source installations:** - -1. Install the Pages daemon: - - ``` - 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.1 - 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: - - ```yaml - ## GitLab Pages - pages: - enabled: true - # The location where pages are stored (default: shared/pages). - # path: shared/pages - - host: example.io - port: 443 - https: true - - external_http: 1.1.1.1:80 - external_https: 1.1.1.1: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.1:80 -listen-https 1.1.1.1: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 - 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. 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] - ---- - -**Omnibus installations:** - -1. Edit `/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' - ``` - - 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 - -| 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 | - -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. - -**Source installations:** - -1. Install the Pages daemon: - - ``` - 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.1 - 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: - - ```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 - ``` - - 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] - ---- - -**Omnibus installations:** - -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 `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 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 | - -Pages enabled, daemon is enabled and NGINX will proxy all requests to the -daemon. Pages daemon doesn't listen to the outside world. - -**Source installations:** - -1. Install the Pages daemon: - - ``` - 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.1 - sudo -u git -H make - ``` -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 - 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. - ---- - -**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] - -### 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. - -**Source installations:** - -1. Install the Pages daemon: - - ``` - 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.1 - 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. 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] - ---- - -**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] - -## NGINX caveats - ->**Note:** -The following information applies only for installations from source. - -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 ~^.*\.YOUR_GITLAB_PAGES\.DOMAIN$; -``` - -with: - -``` -server_name ~^.*\.example\.io$; -``` - -If you are using a subdomain, make sure to escape all dots (`.`) except from -the first one with a backslash (\). For example `pages.example.io` would be: - -``` -server_name ~^.*\.pages\.example\.io$; -``` - -## Set maximum pages size - -The maximum size of the unpacked archive per project can be configured in the -Admin area under the Application settings in the **Maximum size of pages (MB)**. -The default is 100MB. - -## Change storage path - -**Source installations:** - -1. Pages are stored by default in `/home/git/gitlab/shared/pages`. - If you wish to store them in another location you must set it up in - `gitlab.yml` under the `pages` section: - - ```yaml - pages: - enabled: true - # The location where pages are stored (default: shared/pages). - path: /mnt/storage/pages - ``` - -1. [Restart GitLab][restart] - -**Omnibus installations:** - -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] - -## Backup - -Pages are part of the [regular backup][backup] so there is nothing to configure. - -## Security - -You should strongly consider running GitLab pages under a different hostname -than GitLab to prevent XSS attacks. - -## Changelog - -GitLab Pages were first introduced in GitLab EE 8.3. Since then, many features -where added, like custom CNAME and TLS support, and many more are likely to -come. Below is a brief changelog. If no changes were introduced or a version is -missing from the changelog, assume that the documentation is the same as the -latest previous version. - ---- - -**GitLab 8.16 ([documentation][8-16-docs])** - -- GitLab Pages were ported to Community Edition in GitLab 8.16. -- Documentation was refactored to be more modular and easy to follow. - -**GitLab 8.5 ([documentation][8-5-docs])** - -- In GitLab 8.5 we introduced the [gitlab-pages][] daemon which is now the - recommended way to set up GitLab Pages. -- The [NGINX configs][] have changed to reflect this change. So make sure to - update them. -- Custom CNAME and TLS certificates support. -- Documentation was moved to one place. - ---- - -**GitLab 8.3 ([documentation][8-3-docs])** - -- GitLab Pages feature was introduced. - -[8-3-docs]: https://gitlab.com/gitlab-org/gitlab-ee/blob/8-3-stable-ee/doc/pages/administration.md -[8-5-docs]: https://gitlab.com/gitlab-org/gitlab-ee/blob/8-5-stable-ee/doc/pages/administration.md -[8-16-docs]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-16-stable-ce/doc/pages/administration.md -[backup]: ../raketasks/backup_restore.md -[ee-80]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/80 -[ee-173]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/173 -[gitlab pages daemon]: https://gitlab.com/gitlab-org/gitlab-pages -[NGINX configs]: https://gitlab.com/gitlab-org/gitlab-ee/tree/8-5-stable-ee/lib/support/nginx -[pages-readme]: https://gitlab.com/gitlab-org/gitlab-pages/blob/master/README.md -[reconfigure]: ../administration/restart_gitlab.md#omnibus-gitlab-reconfigure -[restart]: ../administration/restart_gitlab.md#installations-from-source -[gitlab-pages]: https://gitlab.com/gitlab-org/gitlab-pages/tree/v0.2.1 +This document was moved to [administration/pages](../administration/pages/index.md). diff --git a/doc/pages/img/pages_create_project.png b/doc/pages/img/pages_create_project.png Binary files differdeleted file mode 100644 index a936d8e5dbd..00000000000 --- a/doc/pages/img/pages_create_project.png +++ /dev/null diff --git a/doc/pages/img/pages_create_user_page.png b/doc/pages/img/pages_create_user_page.png Binary files differdeleted file mode 100644 index 3f615d3757d..00000000000 --- a/doc/pages/img/pages_create_user_page.png +++ /dev/null diff --git a/doc/pages/img/pages_dns_details.png b/doc/pages/img/pages_dns_details.png Binary files differdeleted file mode 100644 index 8d34f3b7f38..00000000000 --- a/doc/pages/img/pages_dns_details.png +++ /dev/null diff --git a/doc/pages/img/pages_multiple_domains.png b/doc/pages/img/pages_multiple_domains.png Binary files differdeleted file mode 100644 index 2bc7cee07a6..00000000000 --- a/doc/pages/img/pages_multiple_domains.png +++ /dev/null diff --git a/doc/pages/img/pages_new_domain_button.png b/doc/pages/img/pages_new_domain_button.png Binary files differdeleted file mode 100644 index c3640133bb2..00000000000 --- a/doc/pages/img/pages_new_domain_button.png +++ /dev/null diff --git a/doc/pages/img/pages_remove.png b/doc/pages/img/pages_remove.png Binary files differdeleted file mode 100644 index adbfb654877..00000000000 --- a/doc/pages/img/pages_remove.png +++ /dev/null diff --git a/doc/pages/img/pages_upload_cert.png b/doc/pages/img/pages_upload_cert.png Binary files differdeleted file mode 100644 index 06d85ab1971..00000000000 --- a/doc/pages/img/pages_upload_cert.png +++ /dev/null |