Commit b9111d8b authored by Achilleas Pipinellis's avatar Achilleas Pipinellis Committed by Kamil Trzcinski

Finish GitLab Pages user documentation

parent c2ed906b
# GitLab Pages
_**Note:** This feature was introduced in GitLab EE 8.3_
_**Note:** This feature was [introduced][ee-80] in GitLab EE 8.3_
To start using GitLab Pages add to your project `.gitlab-ci.yml` the special
`pages` job. The example below is using [jekyll][] and assumes the created
HTML files are generated under the `public/` directory.
GitLab Pages allow you to host static content
## 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:
1. Create project (its name could be specific according to the case)
1. Enable the GitLab Pages feature under the project's settings
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.
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 `gitlab.io`. 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`.
The following table depicts what the project's name should be and under which
URL it will be accessible.
| Pages type | Repository name | URL schema |
| ---------- | --------------- | ---------- |
| User page | `walter/walter.gitlab.io` | `https://walter.gitlab.io` |
| Group page | `therug/therug.gitlab.io` | `https://therug.gitlab.io` |
| Specific project under a user's page | `walter/area51` | `https://walter.gitlab.io/area51` |
| Specific project under a group's page | `therug/welovecats` | `https://therug.gitlab.io/welovecats` |
## Enable the pages feature in your project
The GitLab Pages feature needs to be explicitly enabled for each project
under its **Settings**.
## Remove the contents of your pages
Pages can be explicitly removed from a project by clicking **Remove Pages**
in a project's **Settings**.
## Explore the contents of .gitlab-ci.yml
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 your `.gitlab-ci.yml` must follow the rules below:
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 pages are created after the build completes successfully and the artifacts
for the `pages` job are uploaded to GitLab.
The example below is using [Jekyll][] and assumes that the created HTML files
are generated under the `public/` directory.
```yaml
image: ruby:2.1
pages:
image: jekyll
script: jekyll build
script:
- gem install jekyll
- jekyll build -d public/
artifacts:
paths:
- public
```
- The pages are created when build artifacts for `pages` job are uploaded
- Pages serve the content under: http://group.pages.domain.com/project
- Pages can be used to serve the group page, special project named as host: group.pages.domain.com
- User can provide own 403 and 404 error pages by creating 403.html and 404.html in group page project
- Pages can be explicitly removed from the project by clicking Remove Pages in Project Settings
- The size of pages is limited by Application Setting: max pages size, which limits the maximum size of unpacked archive (default: 100MB)
- The public/ is extracted from artifacts and content is served as static pages
- Pages asynchronous worker use `dd` to limit the unpacked tar size
- Pages needs to be explicitly enabled and domain needs to be specified in gitlab.yml
- Pages are part of backups
- Pages notify the deployment status using Commit Status API
- Pages use a new sidekiq queue: pages
- Pages use a separate nginx config which needs to be explicitly added
## Examples
- Add example with stages. `test` using a linter tool, `deploy` in `pages`
- Add examples of more static tool generators
## Example projects
```yaml
image: jekyll
Below is a list of example projects that make use of static generators.
Contributions are very welcome.
stages:
- test
- deploy
* [Jekyll](https://gitlab.com/gitlab-examples/pages-jekyll)
lint:
script: jekyll build
stage: test
## Custom error codes pages
pages:
script: jekyll build
stage: deploy
artifacts:
paths:
- public
```
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.
## Frequently Asked Questions
**Q:** Where are my generated pages stored?
**A:** All content is located by default under `shared/pages/` in the root
directory of the GitLab installation. To be exact, all specific projects under
a namespace are stored ind `shared/pages/${namespace}/${project}/public/` and
all user/group pages in `shared/pages/${namespace}/${namespace}/public/`.
---
**Q:** Can I download my generated pages?
## Current limitations
**A:** Sure. All you need is to download the artifacts archive from the build
page.
- We currently support only http and port 80. It will be extended in the future.
---
[jekyll]: http://jekyllrb.com/
[ee-80]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/80
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