diff --git a/doc/pages/README.md b/doc/pages/README.md index d6f8d28fa7cc35bbaa9e2504a7fe6466feaf318f..8ca80b2f0bc1847cc0b7fc1d454a5be418ef9fbe 100644 --- a/doc/pages/README.md +++ b/doc/pages/README.md @@ -12,12 +12,6 @@ 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. -The key thing about GitLab Pages is the [`.gitlab-ci.yml`](../ci/yaml/README.md) -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. - -GitLab Pages support any kind of [static site generator][staticgen]. - --- @@ -28,15 +22,22 @@ GitLab Pages support any kind of [static site generator][staticgen]. - [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-ci-yml) + - [Explore the contents of `.gitlab-ci.yml`](#explore-the-contents-of-gitlab-ciyml) + - [How `.gitlab-ci.yml` looks like when using plain HTML files](#how-gitlab-ciyml-looks-like-when-using-plain-html-files) + - [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-there-s-also-actual-code) - [Next steps](#next-steps) - - [Adding a custom domain to your Pages website](#adding-a-custom-domain-to-your-pages-website) - - [Securing your custom domain website with TLS](#securing-your-custom-domain-website-with-tls) - - [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) + - [Use a static generator to develop your website](#use-a-static-generator-to-develop-your-website) + - [Example projects](#example-projects) - [Custom error codes pages](#custom-error-codes-pages) - [Remove the contents of your pages](#remove-the-contents-of-your-pages) - [Limitations](#limitations) - [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) + - [Q: Do I have to create a project named `username.example.io` in order to host a project website?](#q-do-i-have-to-create-a-project-named-username-example-io-in-order-to-host-a-project-website) @@ -49,13 +50,16 @@ GitLab Pages support any kind of [static site generator][staticgen]. In general there are two types of pages one might create: -- Pages per user/group (`username.example.io`) -- Pages per project (`username.example.io/projectname`) +- 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. +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 | Project name created in GitLab | Website URL | +| 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` | @@ -74,9 +78,9 @@ In brief, this is what you need to upload your website in 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`](../ci/yaml/README.md) file in your repository with - a specific job named [`pages`][pages] -1. A GitLab Runner to build GitLab Pages +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 @@ -84,63 +88,91 @@ In brief, this is what you need to upload your website in GitLab Pages: ### 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. -![Create a user-based pages repository](img/create_user_page.png) - ---- - 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 -> **Note:** -> You do _not_ have to create a project named `username.example.io` in order to -> serve a project's page. +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` -### 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, your `.gitlab-ci.yml` must follow the rules below: +To make use of GitLab Pages, the contents of `.gitlab-ci.yml` must follow the +rules below: -1. A special [`pages`][pages] job must be defined -1. Any static content must be placed under a `public/` directory +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 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 @@ -148,14 +180,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 @@ -167,27 +213,84 @@ pages: - master ``` -### Remove the contents of your pages +### How `.gitlab-ci.yml` looks like when using a static generator -Pages can be explicitly removed from a project by clicking **Remove Pages** -in your project's **Settings > Pages**. +In general, GitLab Pages support any kind of [static site generator][staticgen], +since the Runner can be configured to run any possible command. -![Remove pages](img/pages_remove.png) +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 +pages: + images: jekyll/jekyll:latest + script: + - jekyll build -d public/ + artifacts: + paths: + - public + only: + - master +``` + +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. + +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 [example projects](#example-projects) to get +you started. + +#### How to set up GitLab Pages in a repository where there's also actual code + +You can have your project's code in the `master` branch and use an orphan +`pages` branch that will host your static generator site. ## Next steps -### Adding a custom domain to your Pages website +### 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**. -### Securing your custom domain website with TLS +![New domain button](img/pages_new_domain_button.png) -### Example projects +--- + +You are not limited to one domain per can add multiple domains pointing to your +website hosted under GitLab. + +### Secure your custom domain website with TLS + +### Use a static generator to develop your website + +#### 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) +- [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) ### Custom error codes pages @@ -216,16 +319,21 @@ don't redirect HTTP to HTTPS. ## 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? -**Q: Can I use GitLab Pages if my project is private?** - -Yes. GitLab Pages doesn't care whether you set your project's visibility level +Yes. GitLab Pages don't care whether you set your project's visibility level to private, internal or public. +### Q: Do I have to create a project named `username.example.io` in order to host a project website? + +No. You can create a new project named `foo` and have it served under +`http(s)://username.example.io/foo` without having previously created a +user page. + --- [jekyll]: http://jekyllrb.com/ @@ -236,3 +344,4 @@ to private, internal or public. [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 diff --git a/doc/pages/img/create_user_page.png b/doc/pages/img/create_user_page.png deleted file mode 100644 index 8c2b67e233a3c0cc88488aeedcb3f0772d900bb8..0000000000000000000000000000000000000000 Binary files a/doc/pages/img/create_user_page.png and /dev/null differ diff --git a/doc/pages/img/pages_create_project.png b/doc/pages/img/pages_create_project.png new file mode 100644 index 0000000000000000000000000000000000000000..a936d8e5dbde3825a8898692944092c49de85733 Binary files /dev/null and b/doc/pages/img/pages_create_project.png differ diff --git a/doc/pages/img/pages_create_user_page.png b/doc/pages/img/pages_create_user_page.png new file mode 100644 index 0000000000000000000000000000000000000000..3f615d3757d2276e25268d9d2af8493d4c343946 Binary files /dev/null and b/doc/pages/img/pages_create_user_page.png differ diff --git a/doc/pages/img/pages_new_domain_button.png b/doc/pages/img/pages_new_domain_button.png new file mode 100644 index 0000000000000000000000000000000000000000..c3640133bb266a6eefbf9d491a8dd74e3a3000ac Binary files /dev/null and b/doc/pages/img/pages_new_domain_button.png differ diff --git a/doc/pages/img/pages_remove.png b/doc/pages/img/pages_remove.png index 36141bd4d12f518826ef330d234fc1dd55be7801..adbfb654877d8dede23e21405c3dfce87ed09e5e 100644 Binary files a/doc/pages/img/pages_remove.png and b/doc/pages/img/pages_remove.png differ