diff options
author | Achilleas Pipinellis <axilleas@axilleas.me> | 2015-12-18 01:44:11 +0300 |
---|---|---|
committer | James Edwards-Jones <jedwardsjones@gitlab.com> | 2017-02-01 01:53:55 +0300 |
commit | 6f999703c1b9cc3dc8ecf50429a4bf896dda3b2f (patch) | |
tree | 3a77a6b4672dbbb7847371db2a4ba0ffda8d436d /doc/pages/README.md | |
parent | 4e03436befb2c912549440236456c063aa628e51 (diff) |
Finish GitLab Pages user documentation
Diffstat (limited to 'doc/pages/README.md')
-rw-r--r-- | doc/pages/README.md | 141 |
1 files changed, 100 insertions, 41 deletions
diff --git a/doc/pages/README.md b/doc/pages/README.md index ceda2a38915..1d6ea1991f8 100644 --- a/doc/pages/README.md +++ b/doc/pages/README.md @@ -1,60 +1,119 @@ # 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 |