Skip to content

G
gitlab-ce
Commit 579370be authored by Achilleas Pipinellis's avatar Achilleas Pipinellis
Browse files
Options

Merge branch 'pages_user_docs' into 'master' 

Pages user docs



See merge request !212
parents 808fba83 20f39b1f
Hide whitespace changes
Inline Side-by-side
Showing with 421 additions and 77 deletions
doc/ci/yaml/README.md
View file @ 579370be
......@@ -509,6 +509,35 @@ rspec:
The cache is provided on best effort basis, so don't expect that cache will be
always present. For implementation details please check GitLab Runner.
### pages
`pages` is a special job that is used to upload static content to GitLab that
can be used to serve your website. It has a special syntax, so the two
requirements below must be met:
1. Any static content must be placed under a `public/` directory
1. `artifacts` with a path to the `public/` directory must be defined
The example below simply moves all files from the root of the project to the
`public/` directory. The `.public` workaround is so `cp` doesn't also copy
`public/` to itself in an infinite loop:
```
pages:
stage: deploy
script:
- mkdir .public
- cp -r * .public
- mv .public public
artifacts:
paths:
- public
only:
- master
```
Read more on [GitLab Pages user documentation](../../pages/README.md).
## Validate the .gitlab-ci.yml
Each instance of GitLab CI has an embedded debug tool called Lint.
......
doc/pages/README.md
View file @ 579370be
# GitLab Pages
_**Note:** This feature was [introduced][ee-80] in GitLab EE 8.3_
> **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
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.
## Enable the pages feature in your GitLab EE instance
The administrator guide is located at [administration](administration.md).
## Understanding how GitLab Pages work
GitLab Pages rely heavily on GitLab CI and its ability to upload artifacts.
The steps that are performed from the initialization of a project to the
creation of the static content, can be summed up to:
Read [GitLab Pages on GitLab.com](#gitlab-pages-on-gitlabcom) for specific
information, if you are using GitLab.com to host your website.
1. Create project (its name could be specific according to the case)
1. Provide a specific job in `.gitlab-ci.yml`
1. GitLab Runner builds the project
1. GitLab CI uploads the artifacts
1. Nginx serves the content
---
As a user, you should normally be concerned only with the first three items.
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.
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
- [Getting started with GitLab Pages](#getting-started-with-gitlab-pages)
- [GitLab Pages requirements](#gitlab-pages-requirements)
- [User or group Pages](#user-or-group-pages)
- [Project Pages](#project-pages)
- [Explore the contents of `.gitlab-ci.yml`](#explore-the-contents-of-gitlab-ciyml)
- [How `.gitlab-ci.yml` looks like when the static content is in your repository](#how-gitlab-ciyml-looks-like-when-the-static-content-is-in-your-repository)
- [How `.gitlab-ci.yml` looks like when using a static generator](#how-gitlab-ciyml-looks-like-when-using-a-static-generator)
- [How to set up GitLab Pages in a repository where there's also actual code](#how-to-set-up-gitlab-pages-in-a-repository-where-theres-also-actual-code)
- [Next steps](#next-steps)
- [Example projects](#example-projects)
- [Add a custom domain to your Pages website](#add-a-custom-domain-to-your-pages-website)
- [Secure your custom domain website with TLS](#secure-your-custom-domain-website-with-tls)
- [Custom error codes pages](#custom-error-codes-pages)
- [Remove the contents of your pages](#remove-the-contents-of-your-pages)
- [GitLab Pages on GitLab.com](#gitlab-pages-on-gitlabcom)
- [Limitations](#limitations)
- [Redirects in GitLab Pages](#redirects-in-gitlab-pages)
- [Frequently Asked Questions](#frequently-asked-questions)
- [Can I download my generated pages?](#can-i-download-my-generated-pages)
- [Can I use GitLab Pages if my project is private?](#can-i-use-gitlab-pages-if-my-project-is-private)
- [Do I need to create a user/group website before creating a project website?](#do-i-need-to-create-a-usergroup-website-before-creating-a-project-website)
- [Known issues](#known-issues)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
## 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)
In general there are four kinds of pages one might create. This is better
explained with an example so let's make some assumptions.
---
The domain under which the pages are hosted is named `example.com`. There is a
user with the username `walter` and they are the owner of an organization named
`therug`. The personal project of `walter` is named `area51` and don't forget
that the organization has also a project under its namespace, called
`welovecats`.
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.
The following table depicts what the project's name should be and under which
URL it will be accessible.
>**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).
| Pages type | Repository name | URL schema |
| ---------- | --------------- | ---------- |
| User page | `walter/walter.example.com` | `https://walter.example.com` |
| Group page | `therug/therug.example.com` | `https://therug.example.com` |
| Specific project under a user's page | `walter/area51` | `https://walter.example.com/area51` |
| Specific project under a group's page | `therug/welovecats` | `https://therug.example.com/welovecats` |
### Project Pages
## Group 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:
To create a page for a group, add a new project to it. The project name must be lowercased.
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
For example, if you have a group called `TheRug` and pages are hosted under `Example.com`,
create a project named `therug.example.com`.
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`.
## Enable the pages feature in your project
### Explore the contents of `.gitlab-ci.yml`
The GitLab Pages feature needs to be explicitly enabled for each project
under its **Settings**.
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.
## Remove the contents of your pages
> **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).
Pages can be explicitly removed from a project by clicking **Remove Pages**
in a project's **Settings**.
To make use of GitLab Pages, the contents of `.gitlab-ci.yml` must follow the
rules below:
## Explore the contents of .gitlab-ci.yml
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
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).
In its simplest form, `.gitlab-ci.yml` looks like:
---
```yaml
pages:
script:
- my_commands
artifacts:
paths:
- public
```
To make use of GitLab Pages, your `.gitlab-ci.yml` must follow the rules below:
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.
1. A special `pages` job must be defined
1. Any static content must be placed under a `public/` directory
1. `artifacts` with a path to the `public/` directory must be defined
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 examples below, we limit the Pages to be deployed whenever
a commit is pushed only on the `master` branch, which is advisable to do so.
The pages are created after the build completes successfully and the artifacts
for the `pages` job are uploaded to GitLab.
The example below uses [Jekyll][] and generates the created HTML files
under the `public/` directory.
overwritten. In the example below, we limit the Pages to be deployed whenever
a commit is pushed only on the `master` branch:
```yaml
image: ruby:2.1
pages:
script:
- gem install jekyll
- jekyll build -d public/
- my_commands
artifacts:
paths:
- public
......@@ -103,14 +184,28 @@ pages:
- master
```
The example below doesn't use any static site generator, but simply moves all
files from the root of the project to the `public/` directory. The `.public`
workaround is so `cp` doesn’t also copy `public/` to itself in an infinite
loop.
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:
stage: deploy
script:
- mkdir .public
- cp -r * .public
......@@ -122,27 +217,247 @@ pages:
- master
```
## Example projects
#### 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/gitlab-examples/pages-jekyll-branched/tree/master
[jekyll-pages]: https://gitlab.com/gitlab-examples/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/gitlab-examples/pages-plain-html)
* [Jekyll](https://gitlab.com/gitlab-examples/pages-jekyll)
- [Plain HTML](https://gitlab.com/gitlab-examples/pages-plain-html)
- [Jekyll](https://gitlab.com/gitlab-examples/pages-jekyll)
- [Hugo](https://gitlab.com/gitlab-examples/pages-hugo)
- [Middleman](https://gitlab.com/gitlab-examples/pages-middleman)
- [Hexo](https://gitlab.com/gitlab-examples/pages-hexo)
- [Brunch](https://gitlab.com/gitlab-examples/pages-brunch)
- [Metalsmith](https://gitlab.com/gitlab-examples/pages-metalsmith)
- [Harp](https://gitlab.com/gitlab-examples/pages-harp)
Visit the gitlab-examples group for a full list of projects:
<https://gitlab.com/groups/gitlab-examples>.
### 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 > 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.
## Custom error codes pages
![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 `public/` directory that will be included
in the artifacts.
`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 server 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 > Pages** and hit **Remove pages**. 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
**Q: Can I download my generated pages?**
### 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/gitlab-examples/pages-jekyll
[metarefresh]: https://en.wikipedia.org/wiki/Meta_refresh
[public issue tracker]: https://gitlab.com/gitlab-org/gitlab-ee/issues?label_name=Pages
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7