debian-mirror-gitlab/doc/user/project/pages/introduction.md

321 lines
12 KiB
Markdown
Raw Normal View History

2019-09-04 21:01:54 +05:30
---
2020-05-24 23:13:21 +05:30
stage: Release
2021-02-22 17:27:13 +05:30
group: Release
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2019-09-04 21:01:54 +05:30
---
2021-09-04 01:27:46 +05:30
# Exploring GitLab Pages **(FREE)**
2017-08-17 22:00:37 +05:30
2019-07-31 22:56:46 +05:30
This document is a user guide to explore the options and settings
GitLab Pages offers.
2017-08-17 22:00:37 +05:30
2019-07-31 22:56:46 +05:30
To familiarize yourself with GitLab Pages first:
2017-08-17 22:00:37 +05:30
2021-01-03 14:25:43 +05:30
- Read an [introduction to GitLab Pages](index.md).
2019-07-31 22:56:46 +05:30
- Learn [how to get started with Pages](index.md#getting-started).
- Learn how to enable GitLab Pages
2019-09-30 21:07:59 +05:30
across your GitLab instance on the [administrator documentation](../../../administration/pages/index.md).
2017-08-17 22:00:37 +05:30
2019-09-04 21:01:54 +05:30
## GitLab Pages requirements
2017-08-17 22:00:37 +05:30
In brief, this is what you need to upload your website in GitLab Pages:
2019-07-31 22:56:46 +05:30
1. Domain of the instance: domain name that is used for GitLab Pages
2019-09-30 21:07:59 +05:30
(ask your administrator).
2021-09-30 23:02:18 +05:30
1. GitLab CI/CD: a `.gitlab-ci.yml` file with a specific job named [`pages`](../../../ci/yaml/index.md#pages) in the root directory of your repository.
2020-06-23 00:09:42 +05:30
1. A directory called `public` in your site's repository containing the content
2019-09-30 21:07:59 +05:30
to be published.
2019-07-31 22:56:46 +05:30
1. GitLab Runner enabled for the project.
2017-08-17 22:00:37 +05:30
2019-07-31 22:56:46 +05:30
## GitLab Pages on GitLab.com
2017-08-17 22:00:37 +05:30
2019-07-31 22:56:46 +05:30
If you are using [GitLab Pages on GitLab.com](#gitlab-pages-on-gitlabcom) to host your website, then:
2017-08-17 22:00:37 +05:30
2019-07-31 22:56:46 +05:30
- The 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
2020-11-24 15:15:51 +05:30
build your website. If you want you can still bring your own runner.
2017-08-17 22:00:37 +05:30
2019-07-31 22:56:46 +05:30
## Example projects
2017-08-17 22:00:37 +05:30
2019-07-31 22:56:46 +05:30
Visit the [GitLab Pages group](https://gitlab.com/groups/pages) for a complete list of example projects. Contributions are very welcome.
2017-08-17 22:00:37 +05:30
2019-09-04 21:01:54 +05:30
## 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
2021-03-08 18:12:59 +05:30
that are included in the artifacts. Usually this is the root directory of
2019-09-04 21:01:54 +05:30
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
2021-03-08 18:12:59 +05:30
`/projectname/non/existing_file`, GitLab Pages tries to serve first
2019-09-04 21:01:54 +05:30
`/projectname/404.html`, and then `/404.html`.
- If you use user/group Pages (served under `/`) and try to access
2021-03-08 18:12:59 +05:30
`/non/existing_file` GitLab Pages tries to serve `/404.html`.
2019-09-04 21:01:54 +05:30
- If you use a custom domain and try to access `/non/existing_file`, GitLab
2021-03-08 18:12:59 +05:30
Pages tries to serve only `/404.html`.
2019-09-04 21:01:54 +05:30
## Redirects in GitLab Pages
2020-11-24 15:15:51 +05:30
You can configure redirects for your site using a `_redirects` file. To learn more, read
the [redirects documentation](redirects.md).
2019-09-04 21:01:54 +05:30
2021-03-11 19:13:27 +05:30
## GitLab Pages Access Control **(FREE)**
2019-09-04 21:01:54 +05:30
2019-12-26 22:10:19 +05:30
To restrict access to your website, enable [GitLab Pages Access Control](pages_access_control.md).
2019-09-04 21:01:54 +05:30
## Unpublishing 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
2021-03-08 18:12:59 +05:30
navigating to **Pages**. Click the **Remove pages** button to delete your Pages
website.
2019-09-04 21:01:54 +05:30
![Remove pages](img/remove_pages.png)
## 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
2020-06-23 00:09:42 +05:30
username or group name contains a dot, for example `foo.bar`, the domain
2021-03-08 18:12:59 +05:30
`https://foo.bar.example.io` does _not_ work. This is a limitation of the
[HTTP Over TLS protocol](https://tools.ietf.org/html/rfc2818#section-3.1).
HTTP pages continue to work provided you don't redirect HTTP to HTTPS.
2019-09-04 21:01:54 +05:30
GitLab Pages [does **not** support group websites for subgroups](../../group/subgroups/index.md#limitations).
You can only create the highest-level group website.
2019-07-31 22:56:46 +05:30
## Specific configuration options for Pages
2017-08-17 22:00:37 +05:30
2019-07-31 22:56:46 +05:30
Learn how to set up GitLab CI/CD for specific use cases.
2017-08-17 22:00:37 +05:30
2019-07-31 22:56:46 +05:30
### `.gitlab-ci.yml` for plain HTML websites
2017-08-17 22:00:37 +05:30
2018-03-17 18:26:18 +05:30
Supposed your repository contained the following files:
2017-08-17 22:00:37 +05:30
2020-03-13 15:44:24 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
├── index.html
├── css
2019-03-02 22:35:43 +05:30
│ └── main.css
2017-08-17 22:00:37 +05:30
└── 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:
2020-07-28 23:09:34 +05:30
- mkdir .public
- cp -r * .public
- mv .public public
2017-08-17 22:00:37 +05:30
artifacts:
paths:
2020-07-28 23:09:34 +05:30
- public
2017-08-17 22:00:37 +05:30
only:
2021-11-18 22:05:49 +05:30
- main
2017-08-17 22:00:37 +05:30
```
2019-07-31 22:56:46 +05:30
### `.gitlab-ci.yml` for a static site generator
2017-08-17 22:00:37 +05:30
2020-07-28 23:09:34 +05:30
See this document for a [step-by-step guide](getting_started/pages_from_scratch.md).
2017-08-17 22:00:37 +05:30
2019-07-31 22:56:46 +05:30
### `.gitlab-ci.yml` for a repository where there's also actual code
2017-08-17 22:00:37 +05:30
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
2021-09-30 23:02:18 +05:30
the `pages` job with the [`only` parameter](../../../ci/yaml/index.md#only--except),
2021-03-08 18:12:59 +05:30
whenever a new commit is pushed to a branch used specifically for your
pages.
2017-08-17 22:00:37 +05:30
2021-11-18 22:05:49 +05:30
That way, you can have your project's code in the `main` branch and use an
2021-03-08 18:12:59 +05:30
orphan branch (let's name it `pages`) to host your static generator site.
2017-08-17 22:00:37 +05:30
You can create a new empty branch like this:
2020-03-13 15:44:24 +05:30
```shell
2017-08-17 22:00:37 +05:30
git checkout --orphan pages
```
2021-03-08 18:12:59 +05:30
The first commit made on this new branch has no parents and is 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.
2017-08-17 22:00:37 +05:30
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:
2020-03-13 15:44:24 +05:30
```yaml
image: ruby:2.6
2017-08-17 22:00:37 +05:30
pages:
script:
2020-07-28 23:09:34 +05:30
- gem install jekyll
- jekyll build -d public/
2017-08-17 22:00:37 +05:30
artifacts:
paths:
2020-07-28 23:09:34 +05:30
- public
2017-08-17 22:00:37 +05:30
only:
2020-07-28 23:09:34 +05:30
- pages
2017-08-17 22:00:37 +05:30
```
2021-11-18 22:05:49 +05:30
See an example that has different files in the [`main` branch](https://gitlab.com/pages/jekyll-branched/tree/main)
2020-05-24 23:13:21 +05:30
and the source files for Jekyll are in a [`pages` branch](https://gitlab.com/pages/jekyll-branched/tree/pages) which
2017-08-17 22:00:37 +05:30
also includes `.gitlab-ci.yml`.
2018-03-17 18:26:18 +05:30
### Serving compressed assets
Most modern browsers support downloading files in a compressed format. This
speeds up downloads by reducing the size of files.
2021-03-08 18:12:59 +05:30
Before serving an uncompressed file, Pages checks if the same file exists with
a `.br` or `.gz` extension. If it does, and the browser supports receiving
compressed files, it serves that version instead of the uncompressed one.
2018-03-17 18:26:18 +05:30
To take advantage of this feature, the artifact you upload to the Pages should
have this structure:
2020-03-13 15:44:24 +05:30
```plaintext
2018-03-17 18:26:18 +05:30
public/
├─┬ index.html
2021-01-03 14:25:43 +05:30
│ | index.html.br
2018-03-17 18:26:18 +05:30
│ └ index.html.gz
├── css/
2019-03-02 22:35:43 +05:30
│ └─┬ main.css
2021-01-03 14:25:43 +05:30
│ | main.css.br
2018-03-17 18:26:18 +05:30
│ └ main.css.gz
└── js/
└─┬ main.js
2021-01-03 14:25:43 +05:30
| main.js.br
2018-03-17 18:26:18 +05:30
└ main.js.gz
```
This can be achieved by including a `script:` command like this in your
`.gitlab-ci.yml` pages job:
```yaml
pages:
# Other directives
script:
2019-07-07 11:18:12 +05:30
# Build the public/ directory first
- find public -type f -regex '.*\.\(htm\|html\|txt\|text\|js\|css\)$' -exec gzip -f -k {} \;
2021-01-03 14:25:43 +05:30
- find public -type f -regex '.*\.\(htm\|html\|txt\|text\|js\|css\)$' -exec brotli -f -k {} \;
2018-03-17 18:26:18 +05:30
```
By pre-compressing the files and including both versions in the artifact, Pages
can serve requests for both compressed and uncompressed content without
needing to compress files on-demand.
2019-03-02 22:35:43 +05:30
### Resolving ambiguous URLs
2020-06-23 00:09:42 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/95) in GitLab 11.8
2019-03-02 22:35:43 +05:30
GitLab Pages makes assumptions about which files to serve when receiving a
request for a URL that does not include an extension.
Consider a Pages site deployed with the following files:
2020-03-13 15:44:24 +05:30
```plaintext
2019-03-02 22:35:43 +05:30
public/
2021-12-11 22:18:48 +05:30
├── index.html
├── data.html
├── info.html
2019-03-02 22:35:43 +05:30
├── data/
│ └── index.html
2021-12-11 22:18:48 +05:30
└── info/
└── details.html
2019-03-02 22:35:43 +05:30
```
Pages supports reaching each of these files through several different URLs. In
2021-03-08 18:12:59 +05:30
particular, it always looks for an `index.html` file if the URL only
2019-03-02 22:35:43 +05:30
specifies the directory. If the URL references a file that doesn't exist, but
2021-03-08 18:12:59 +05:30
adding `.html` to the URL leads to a file that *does* exist, it's served
instead. Here are some examples of what happens given the above Pages site:
2019-03-02 22:35:43 +05:30
2021-12-11 22:18:48 +05:30
| URL path | HTTP response |
| -------------------- | ------------- |
| `/` | `200 OK`: `public/index.html` |
| `/index.html` | `200 OK`: `public/index.html` |
| `/index` | `200 OK`: `public/index.html` |
| `/data` | `302 Found`: redirecting to `/data/` |
| `/data/` | `200 OK`: `public/data/index.html` |
| `/data.html` | `200 OK`: `public/data.html` |
| `/info` | `302 Found`: redirecting to `/info/` |
| `/info/` | `404 Not Found` Error Page |
| `/info.html` | `200 OK`: `public/info.html` |
| `/info/details` | `200 OK`: `public/info/details.html` |
| `/info/details.html` | `200 OK`: `public/info/details.html` |
2019-03-02 22:35:43 +05:30
2021-01-03 14:25:43 +05:30
Note that when `public/data/index.html` exists, it takes priority over the `public/data.html` file
for both the `/data` and `/data/` URL paths.
2019-03-02 22:35:43 +05:30
2017-08-17 22:00:37 +05:30
## Frequently Asked Questions
### Can I download my generated pages?
Sure. All you need to do is download the artifacts archive from the job page.
### Can I use GitLab Pages if my project is private?
2018-03-17 18:26:18 +05:30
Yes. GitLab Pages doesn't care whether you set your project's visibility level
2017-08-17 22:00:37 +05:30
to private, internal or public.
2021-06-08 01:23:25 +05:30
### Can I create a personal or a group website
Yes. See the documentation about [GitLab Pages domain names, URLs, and base URLs](getting_started_part_one.md).
2017-08-17 22:00:37 +05:30
### Do I need to create a user/group website before creating a project website?
2021-03-08 18:12:59 +05:30
No, you don't. You can create your project first and access it under
2017-08-17 22:00:37 +05:30
`http(s)://namespace.example.io/projectname`.
## Known issues
2021-02-22 17:27:13 +05:30
For a list of known issues, visit the GitLab [public issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues?label_name[]=Category%3APages).
2021-04-29 21:17:54 +05:30
## Troubleshooting
### 404 error when accessing a GitLab Pages site URL
This problem most likely results from a missing `index.html` file in the public directory. If after deploying a Pages site
a 404 is encountered, confirm that the public directory contains an `index.html` file. If the file contains a different name
such as `test.html`, the Pages site can still be accessed, but the full path would be needed. For example: `https//group-name.pages.example.com/project-name/test.html`.
The contents of the public directory can be confirmed by [browsing the artifacts](../../../ci/pipelines/job_artifacts.md#download-job-artifacts) from the latest pipeline.
Files listed under the public directory can be accessed through the Pages URL for the project.
A 404 can also be related to incorrect permissions. If [Pages Access Control](pages_access_control.md) is enabled, and a user
navigates to the Pages URL and receives a 404 response, it is possible that the user does not have permission to view the site.
To fix this, verify that the user is a member of the project.
2021-06-08 01:23:25 +05:30
For Geo instances, 404 errors on Pages occur after promoting a secondary to a primary.
Find more details in the [Pages administration documentation](../../../administration/pages/index.md#404-error-after-promoting-a-geo-secondary-to-a-primary-node)
### Cannot play media content on Safari
Safari requires the web server to support the [Range request header](https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/CreatingVideoforSafarioniPhone/CreatingVideoforSafarioniPhone.html#//apple_ref/doc/uid/TP40006514-SW6)
in order to play your media content. For GitLab Pages to serve
HTTP Range requests, you should use the following two variables in your `.gitlab-ci.yaml` file:
```yaml
pages:
stage: deploy
variables:
FF_USE_FASTZIP: "true"
ARTIFACT_COMPRESSION_LEVEL: "fastest"
script:
- echo "Deploying pages"
artifacts:
paths:
- public
```
2021-09-04 01:27:46 +05:30
The `FF_USE_FASTZIP` variable enables the [feature flag](https://docs.gitlab.com/runner/configuration/feature-flags.html#available-feature-flags) which is needed for [`ARTIFACT_COMPRESSION_LEVEL`](../../../ci/runners/configure_runners.md#artifact-and-cache-settings).