diff options
Diffstat (limited to 'doc/administration/pages')
| -rw-r--r-- | doc/administration/pages/index.md | 456 | ||||
| -rw-r--r-- | doc/administration/pages/source.md | 46 | ||||
| -rw-r--r-- | doc/administration/pages/troubleshooting.md | 304 |
3 files changed, 403 insertions, 403 deletions
diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index ed08b10fe97..1626a4fd41a 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -1,8 +1,7 @@ --- -stage: Create -group: Editor +stage: Plan +group: Knowledge info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -description: 'Learn how to administer GitLab Pages.' --- # GitLab Pages administration **(FREE SELF)** @@ -15,7 +14,7 @@ This guide is for Omnibus GitLab installations. If you have installed GitLab from source, see [GitLab Pages administration for source installations](source.md). -## Overview +## The GitLab Pages daemon GitLab Pages makes use of the [GitLab Pages daemon](https://gitlab.com/gitlab-org/gitlab-pages), a basic HTTP server written in Go that can listen on an external IP address and provide support for @@ -247,20 +246,20 @@ control over how the Pages daemon runs and serves content in your environment. | `enable` | Enable or disable GitLab Pages on the current system. | | `external_http` | Configure Pages to bind to one or more secondary IP addresses, serving HTTP requests. Multiple addresses can be given as an array, along with exact ports, for example `['1.2.3.4', '1.2.3.5:8063']`. Sets value for `listen_http`. | | `external_https` | Configure Pages to bind to one or more secondary IP addresses, serving HTTPS requests. Multiple addresses can be given as an array, along with exact ports, for example `['1.2.3.4', '1.2.3.5:8063']`. Sets value for `listen_https`. | -| `server_shutdown_timeout` | GitLab Pages server shutdown timeout in seconds (default: 30 s). | -| `gitlab_client_http_timeout` | GitLab API HTTP client connection timeout in seconds (default: 10 s). | -| `gitlab_client_jwt_expiry` | JWT Token expiry time in seconds (default: 30 s). | -| `gitlab_cache_expiry` | The maximum time a domain's configuration is stored in the cache (default: 600 s). | -| `gitlab_cache_refresh` | The interval at which a domain's configuration is set to be due to refresh (default: 60 s). | -| `gitlab_cache_cleanup` | The interval at which expired items are removed from the cache (default: 60 s). | -| `gitlab_retrieval_timeout` | The maximum time to wait for a response from the GitLab API per request (default: 30 s). | -| `gitlab_retrieval_interval` | The interval to wait before retrying to resolve a domain's configuration via the GitLab API (default: 1 s). | +| `server_shutdown_timeout` | GitLab Pages server shutdown timeout in seconds (default: `30s`). | +| `gitlab_client_http_timeout` | GitLab API HTTP client connection timeout in seconds (default: `10s`). | +| `gitlab_client_jwt_expiry` | JWT Token expiry time in seconds (default: `30s`). | +| `gitlab_cache_expiry` | The maximum time a domain's configuration is stored in the cache (default: `600s`). | +| `gitlab_cache_refresh` | The interval at which a domain's configuration is set to be due to refresh (default: `60s`). | +| `gitlab_cache_cleanup` | The interval at which expired items are removed from the cache (default: `60s`). | +| `gitlab_retrieval_timeout` | The maximum time to wait for a response from the GitLab API per request (default: `30s`). | +| `gitlab_retrieval_interval` | The interval to wait before retrying to resolve a domain's configuration via the GitLab API (default: `1s`). | | `gitlab_retrieval_retries` | The maximum number of times to retry to resolve a domain's configuration via the API (default: 3). | | `domain_config_source` | This parameter was removed in 14.0, on earlier versions it can be used to enable and test API domain configuration source | | `gitlab_id` | The OAuth application public ID. Leave blank to automatically fill when Pages authenticates with GitLab. | | `gitlab_secret` | The OAuth application secret. Leave blank to automatically fill when Pages authenticates with GitLab. | | `auth_scope` | The OAuth application scope to use for authentication. Must match GitLab Pages OAuth application settings. Leave blank to use `api` scope by default. | -| `auth_cookie_session_timeout` | Authentication cookie session timeout in seconds (default: 600 s). A value of `0` means the cookie is deleted after the browser session ends. | +| `auth_cookie_session_timeout` | Authentication cookie session timeout in seconds (default: `10m`). A value of `0` means the cookie is deleted after the browser session ends. | | `gitlab_server` | Server to use for authentication when access control is enabled; defaults to GitLab `external_url`. | | `headers` | Specify any additional http headers that should be sent to the client with each response. Multiple headers can be given as an array, header and value as one string, for example `['my-header: myvalue', 'my-other-header: my-other-value']` | | `enable_disk` | Allows the GitLab Pages daemon to serve content from disk. Shall be disabled if shared disk storage isn't available. | @@ -300,6 +299,10 @@ control over how the Pages daemon runs and serves content in your environment. | `rate_limit_source_ip_burst` | Rate limit per source IP maximum burst allowed per second. | | `rate_limit_domain` | Rate limit per domain in number of requests per second. Set to `0` to disable this feature. | | `rate_limit_domain_burst` | Rate limit per domain maximum burst allowed per second. | +| `rate_limit_tls_source_ip` | Rate limit per source IP in number of TLS connections per second. Set to `0` to disable this feature. | +| `rate_limit_tls_source_ip_burst` | Rate limit per source IP maximum TLS connections burst allowed per second. | +| `rate_limit_tls_domain` | Rate limit per domain in number of TLS connections per second. Set to `0` to disable this feature. | +| `rate_limit_tls_domain_burst` | Rate limit per domain maximum TLS connections burst allowed per second. | | `server_read_timeout` | Maximum duration to read the request headers and body. For no timeout, set to `0` or a negative value. Default: `5s` | | `server_read_header_timeout` | Maximum duration to read the request headers. For no timeout, set to `0` or a negative value. Default: `1s` | | `server_write_timeout` | Maximum duration to write all files in the response. Larger files require more time. For no timeout, set to `0` or a negative value. Default: `0` | @@ -514,7 +517,7 @@ internet connectivity is gated by a proxy. To use a proxy for GitLab Pages: ### Using a custom Certificate Authority (CA) When using certificates issued by a custom CA, [Access Control](../../user/project/pages/pages_access_control.md) and -the [online view of HTML job artifacts](../../ci/pipelines/job_artifacts.md#download-job-artifacts) +the [online view of HTML job artifacts](../../ci/jobs/job_artifacts.md#download-job-artifacts) fails to work if the custom CA is not recognized. This usually results in this error: @@ -523,7 +526,7 @@ This usually results in this error: For installation from source, this can be fixed by installing the custom Certificate Authority (CA) in the system certificate store. -For Omnibus, this is fixed by [installing a custom CA in Omnibus GitLab](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). +For Omnibus, this is fixed by [installing a custom CA in Omnibus GitLab](https://docs.gitlab.com/omnibus/settings/ssl/index.html#install-custom-public-certificates). ### ZIP serving and cache configuration @@ -540,22 +543,22 @@ archive. You can modify the cache behavior by changing the following configurati | Setting | Description | | ------- | ----------- | -| `zip_cache_expiration` | The cache expiration interval of ZIP archives. Must be greater than zero to avoid serving stale content. Default is 60 s. | -| `zip_cache_cleanup` | The interval at which archives are cleaned from memory if they have already expired. Default is 30 s. | -| `zip_cache_refresh` | The time interval in which an archive is extended in memory if accessed before `zip_cache_expiration`. This works together with `zip_cache_expiration` to determine if an archive is extended in memory. See the [example below](#zip-cache-refresh-example) for important details. Default is 30 s. | +| `zip_cache_expiration` | The cache expiration interval of ZIP archives. Must be greater than zero to avoid serving stale content. Default is `60s`. | +| `zip_cache_cleanup` | The interval at which archives are cleaned from memory if they have already expired. Default is `30s`. | +| `zip_cache_refresh` | The time interval in which an archive is extended in memory if accessed before `zip_cache_expiration`. This works together with `zip_cache_expiration` to determine if an archive is extended in memory. See the [example below](#zip-cache-refresh-example) for important details. Default is `30s`. | | `zip_open_timeout` | The maximum time allowed to open a ZIP archive. Increase this time for big archives or slow network connections, as doing so may affect the latency of serving Pages. Default is 30 s. | -| `zip_http_client_timeout` | The maximum time for the ZIP HTTP client. Default is 30 m. | +| `zip_http_client_timeout` | The maximum time for the ZIP HTTP client. Default is `30m`. | #### ZIP cache refresh example Archives are refreshed in the cache (extending the time they are held in memory) if they're accessed before `zip_cache_expiration`, and the time left before expiring is less than or equal to -`zip_cache_refresh`. For example, if `archive.zip` is accessed at time 0 s, it expires in 60 s (the -default for `zip_cache_expiration`). In the example below, if the archive is opened again after 15 s -it is **not** refreshed because the time left for expiry (45 s) is greater than `zip_cache_refresh` -(default 30 s). However, if the archive is accessed again after 45 s (from the first time it was +`zip_cache_refresh`. For example, if `archive.zip` is accessed at time `0s`, it expires in `60s` (the +default for `zip_cache_expiration`). In the example below, if the archive is opened again after `15s` +it is **not** refreshed because the time left for expiry (`45s`) is greater than `zip_cache_refresh` +(default `30s`). However, if the archive is accessed again after `45s` (from the first time it was opened) it's refreshed. This extends the time the archive remains in memory from -`45s + zip_cache_expiration (60s)`, for a total of 105 s. +`45s + zip_cache_expiration (60s)`, for a total of `105s`. After an archive reaches `zip_cache_expiration`, it's marked as expired and removed on the next `zip_cache_cleanup` interval. @@ -631,34 +634,6 @@ are stored. 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). -Alternatively, if you have existing Pages deployed you can follow -the below steps to do a no downtime transfer to a new storage location. - -1. Pause Pages deployments by setting the following in `/etc/gitlab/gitlab.rb`: - - ```ruby - sidekiq['queue_selector'] = true - sidekiq['queue_groups'] = [ - "feature_category!=pages" - ] - ``` - -1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). -1. `rsync` contents from the current storage location to the new storage location: `sudo rsync -avzh --progress /var/opt/gitlab/gitlab-rails/shared/pages/ /mnt/storage/pages` -1. Set the new storage location in `/etc/gitlab/gitlab.rb`: - - ```ruby - gitlab_rails['pages_path'] = "/mnt/storage/pages" - ``` - -1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). -1. Verify Pages are still being served up as expected. -1. Resume Pages deployments by removing from `/etc/gitlab/gitlab.rb` the `sidekiq` setting set above. -1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). -1. Trigger a new Pages deployment and verify it's working as expected. -1. Remove the old Pages storage location: `sudo rm -rf /var/opt/gitlab/gitlab-rails/shared/pages` -1. Verify Pages are still being served up as expected. - ## Configure listener for reverse proxy requests Follow the steps below to configure the proxy listener of GitLab Pages. @@ -683,23 +658,23 @@ Follow the steps below to configure the proxy listener of GitLab Pages. ## Set global maximum size of each GitLab Pages site **(FREE SELF)** -Prerequisites: +Prerequisite: -- Only GitLab administrators can edit this setting. +- You must have administrator access to the instance. To set the global maximum pages size for a project: 1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Preferences**. 1. Expand **Pages**. -1. Enter a value under **Maximum size of pages**. +1. In **Maximum size of pages**, enter a value. The default is `100`. 1. Select **Save changes**. ## Set maximum size of each GitLab Pages site in a group **(PREMIUM SELF)** -Prerequisites: +Prerequisite: -- You must have at least the Maintainer role for the group. +- You must have administrator access to the instance. To set the maximum size of each GitLab Pages site in a group, overriding the inherited setting: @@ -711,9 +686,9 @@ To set the maximum size of each GitLab Pages site in a group, overriding the inh ## Set maximum size of GitLab Pages site in a project **(PREMIUM SELF)** -Prerequisites: +Prerequisite: -- You must have at least the Maintainer role for the project. +- You must have administrator access to the instance. To set the maximum size of GitLab Pages site in a project, overriding the inherited setting: @@ -729,7 +704,7 @@ To set the maximum size of GitLab Pages site in a project, overriding the inheri Prerequisite: -- You must be an administrator of a self-managed GitLab instance. +- You must have administrator access to the instance. To set the maximum number of GitLab Pages custom domains for a project: @@ -738,6 +713,15 @@ To set the maximum number of GitLab Pages custom domains for a project: 1. Enter a value for **Maximum number of custom domains per project**. Use `0` for unlimited domains. 1. Select **Save changes**. +## Set maximum number of files per GitLab Pages website + +The total number of file entries (including directories and symlinks) is limited to `200,000` per GitLab Pages website. + +You can update the limit in your self-managed instance using the +[GitLab Rails console](../operations/rails_console.md#starting-a-rails-console-session). + +For more information, see [GitLab application limits](../instance_limits.md#number-of-files-per-gitlab-pages-website). + ## Running GitLab Pages on a separate server You can run the GitLab Pages daemon on a separate server to decrease the load on @@ -846,7 +830,7 @@ From [GitLab 13.3 to GitLab 13.12](#domain-source-configuration-before-140) GitL Starting from [GitLab 14.0](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5993) GitLab Pages uses API by default and fails to start if it can't connect to it. -For common issues, see the [troubleshooting section](#failed-to-connect-to-the-internal-gitlab-api). +For common issues, see [troubleshooting](troubleshooting.md#failed-to-connect-to-the-internal-gitlab-api). For more details see this [blog post](https://about.gitlab.com/blog/2020/08/03/how-gitlab-pages-uses-the-gitlab-api-to-serve-content/). @@ -891,7 +875,7 @@ Incorrect configuration of these values may result in intermittent or persistent errors, or the Pages Daemon serving old content. NOTE: -Expiry, interval and timeout flags use [Golang's duration formatting](https://pkg.go.dev/time#ParseDuration). +Expiry, interval and timeout flags use [Go duration formatting](https://pkg.go.dev/time#ParseDuration). A duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as `300ms`, `1.5h` or `2h45m`. Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. @@ -923,7 +907,7 @@ configuration is tried to be resolved automatically before reporting an error. > [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5577) in GitLab 13.6. -[Read more about using object storage with GitLab](../object_storage.md). +For more information, see [object storage](../object_storage.md). ### Object storage settings @@ -945,10 +929,10 @@ If you want to stop using and disconnect the NFS server, you need to #### S3-compatible connection settings In GitLab 13.2 and later, you should use the -[consolidated object storage settings](../object_storage.md#consolidated-object-storage-configuration). +[consolidated object storage settings](../object_storage.md#configure-a-single-storage-connection-for-all-object-types-consolidated-form). This section describes the earlier configuration format. -See [the available connection settings for different providers](../object_storage.md#connection-settings). +See [the available connection settings for different providers](../object_storage.md#configure-the-connection-settings). In Omnibus installations: @@ -1128,8 +1112,8 @@ In GitLab 14.0 a number of breaking changes were introduced which may require so The steps below describe the best way to migrate without causing any downtime for your GitLab instance. A GitLab instance running on a single server typically upgrades to 14.0 smoothly, and there should be minimal issues after the upgrade is complete. -Regardless, we recommend everyone follow the migration steps to ensure a successful upgrade. -If at any point you run into issues, consult the [troubleshooting section](#troubleshooting). +Regardless, you should follow the migration steps to ensure a successful upgrade. +For common issues, see [troubleshooting](troubleshooting.md). If your current GitLab version is lower than 13.12, then you must first update to 13.12. Updating directly to 14.0 is [not supported](../../update/index.md#upgrade-paths) @@ -1158,14 +1142,14 @@ than GitLab to prevent XSS attacks. You can enforce rate limits to help minimize the risk of a Denial of Service (DoS) attack. GitLab Pages uses a [token bucket algorithm](https://en.wikipedia.org/wiki/Token_bucket) to enforce rate limiting. By default, -requests that exceed the specified limits are reported but not rejected. +requests or TLS connections that exceed the specified limits are reported but not rejected. GitLab Pages supports the following types of rate limiting: -- Per `source_ip`. It limits how many requests are allowed from the single client IP address. -- Per `domain`. It limits how many requests are allowed per domain hosted on GitLab Pages. It can be a custom domain like `example.com`, or group domain like `group.gitlab.io`. +- Per `source_ip`. It limits how many requests or TLS connections are allowed from the single client IP address. +- Per `domain`. It limits how many requests or TLS connections are allowed per domain hosted on GitLab Pages. It can be a custom domain like `example.com`, or group domain like `group.gitlab.io`. -Rate limits are enforced using the following: +HTTP request-based rate limits are enforced using the following: - `rate_limit_source_ip`: Set the maximum threshold in number of requests per client IP per second. Set to 0 to disable this feature. - `rate_limit_source_ip_burst`: Sets the maximum threshold of number of requests allowed in an initial outburst of requests per client IP. @@ -1173,7 +1157,15 @@ Rate limits are enforced using the following: - `rate_limit_domain`: Set the maximum threshold in number of requests per hosted pages domain per second. Set to 0 to disable this feature. - `rate_limit_domain_burst`: Sets the maximum threshold of number of requests allowed in an initial outburst of requests per hosted pages domain. -#### Enable source-IP rate limits +TLS connection-based rate limits are enforced using the following: + +- `rate_limit_tls_source_ip`: Set the maximum threshold in number of TLS connections per client IP per second. Set to 0 to disable this feature. +- `rate_limit_tls_source_ip_burst`: Sets the maximum threshold of number of TLS connections allowed in an initial outburst of TLS connections per client IP. + For example, when you load a web page from different web browsers at the same time. +- `rate_limit_tls_domain`: Set the maximum threshold in number of TLS connections per hosted pages domain per second. Set to 0 to disable this feature. +- `rate_limit_tls_domain_burst`: Sets the maximum threshold of number of TLS connections allowed in an initial outburst of TLS connections per hosted pages domain. + +#### Enable HTTP requests rate limits by source-IP > [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/631) in GitLab 14.5. @@ -1184,16 +1176,9 @@ Rate limits are enforced using the following: gitlab_pages['rate_limit_source_ip_burst'] = 600 ``` -1. To reject requests that exceed the specified limits, enable the `FF_ENFORCE_IP_RATE_LIMITS` feature flag in - `/etc/gitlab/gitlab.rb`: - - ```ruby - gitlab_pages['env'] = {'FF_ENFORCE_IP_RATE_LIMITS' => 'true'} - ``` - 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). -#### Enable domain rate limits +#### Enable HTTP requests rate limits by domain > [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/630) in GitLab 14.7. @@ -1204,321 +1189,34 @@ Rate limits are enforced using the following: gitlab_pages['rate_limit_domain_burst'] = 5000 ``` -1. To reject requests that exceed the specified limits, enable the `FF_ENFORCE_DOMAIN_RATE_LIMITS` feature flag in - `/etc/gitlab/gitlab.rb`: - - ```ruby - gitlab_pages['env'] = {'FF_ENFORCE_DOMAIN_RATE_LIMITS' => 'true'} - ``` - 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them in -the section below. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, for example `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> - -## Troubleshooting - -### How to see GitLab Pages logs - -You can see Pages daemon logs by running: - -```shell -sudo gitlab-ctl tail gitlab-pages -``` - -You can also find the log file in `/var/log/gitlab/gitlab-pages/current`. - -### `unsupported protocol scheme \"\""` - -If you see the following error: - -```plaintext -{"error":"failed to connect to internal Pages API: Get \"/api/v4/internal/pages/status\": unsupported protocol scheme \"\"","level":"warning","msg":"attempted to connect to the API","time":"2021-06-23T20:03:30Z"} -``` - -It means you didn't set the HTTP(S) protocol scheme in the Pages server settings. -To fix it: - -1. Edit `/etc/gitlab/gitlab.rb`: - - ```ruby - gitlab_pages['gitlab_server'] = "https://<your_pages_domain_name>" - gitlab_pages['internal_gitlab_server'] = "https://<your_pages_domain_name>" - ``` - -1. Reconfigure GitLab: - - ```shell - sudo gitlab-ctl reconfigure - ``` - -### 502 error when connecting to GitLab Pages proxy when server does not listen over IPv6 - -In some cases, NGINX might default to using IPv6 to connect to the GitLab Pages -service even when the server does not listen over IPv6. You can identify when -this is happening if you see something similar to the log entry below in the -`gitlab_pages_error.log`: - -```plaintext -2020/02/24 16:32:05 [error] 112654#0: *4982804 connect() failed (111: Connection refused) while connecting to upstream, client: 123.123.123.123, server: ~^(?<group>.*)\.pages\.example\.com$, request: "GET /-/group/project/-/jobs/1234/artifacts/artifact.txt HTTP/1.1", upstream: "http://[::1]:8090//-/group/project/-/jobs/1234/artifacts/artifact.txt", host: "group.example.com" -``` - -To resolve this, set an explicit IP and port for the GitLab Pages `listen_proxy` setting -to define the explicit address that the GitLab Pages daemon should listen on: - -```ruby -gitlab_pages['listen_proxy'] = '127.0.0.1:8090' -``` - -### Intermittent 502 errors or after a few days - -If you run Pages on a system that uses `systemd` and -[`tmpfiles.d`](https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html), -you may encounter intermittent 502 errors trying to serve Pages with an error similar to: - -```plaintext -dial tcp: lookup gitlab.example.com on [::1]:53: dial udp [::1]:53: connect: no route to host" -``` - -GitLab Pages creates a [bind mount](https://man7.org/linux/man-pages/man8/mount.8.html) -inside `/tmp/gitlab-pages-*` that includes files like `/etc/hosts`. -However, `systemd` may clean the `/tmp/` directory on a regular basis so the DNS -configuration may be lost. - -To stop `systemd` from cleaning the Pages related content: - -1. Tell `tmpfiles.d` to not remove the Pages `/tmp` directory: - - ```shell - echo 'x /tmp/gitlab-pages-*' >> /etc/tmpfiles.d/gitlab-pages-jail.conf - ``` - -1. Restart GitLab Pages: - - ```shell - sudo gitlab-ctl restart gitlab-pages - ``` - -### Unable to access GitLab Pages - -If you can't access your GitLab Pages (such as receiving `502 Bad Gateway` errors, or a login loop) -and in your Pages log shows this error: - -```plaintext -"error":"retrieval context done: context deadline exceeded","host":"root.docs-cit.otenet.gr","level":"error","msg":"could not fetch domain information from a source" -``` - -1. Add the following to `/etc/gitlab/gitlab.rb`: - - ```ruby - gitlab_pages['internal_gitlab_server'] = 'http://localhost:8080' - ``` - -1. Restart GitLab Pages: - - ```shell - sudo gitlab-ctl restart gitlab-pages - ``` - -### Failed to connect to the internal GitLab API - -If you see the following error: +#### Enable TLS connections rate limits by source-IP -```plaintext -ERRO[0010] Failed to connect to the internal GitLab API after 0.50s error="failed to connect to internal Pages API: HTTP status: 401" -``` - -If you are [Running GitLab Pages on a separate server](#running-gitlab-pages-on-a-separate-server) -you must copy the `/etc/gitlab/gitlab-secrets.json` file -from the **GitLab server** to the **Pages server** after upgrading to GitLab 13.3, -as described in that section. - -Other reasons may include network connectivity issues between your -**GitLab server** and your **Pages server** such as firewall configurations or closed ports. -For example, if there is a connection timeout: - -```plaintext -error="failed to connect to internal Pages API: Get \"https://gitlab.example.com:3000/api/v4/internal/pages/status\": net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)" -``` - -### Pages cannot communicate with an instance of the GitLab API - -If you use the default value for `domain_config_source=auto` and run multiple instances of GitLab -Pages, you may see intermittent 502 error responses while serving Pages content. You may also see -the following warning in the Pages logs: - -```plaintext -WARN[0010] Pages cannot communicate with an instance of the GitLab API. Please sync your gitlab-secrets.json file https://gitlab.com/gitlab-org/gitlab-pages/-/issues/535#workaround. error="pages endpoint unauthorized" -``` - -This can happen if your `gitlab-secrets.json` file is out of date between GitLab Rails and GitLab -Pages. Follow steps 8-10 of [Running GitLab Pages on a separate server](#running-gitlab-pages-on-a-separate-server), -in all of your GitLab Pages instances. - -### Intermittent 502 errors when using an AWS Network Load Balancer and GitLab Pages - -Connections will time out when using a Network Load Balancer with client IP preservation enabled and [the request is looped back to the source server](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-troubleshooting.html#loopback-timeout). -This can happen to GitLab instances with multiple servers -running both the core GitLab application and GitLab Pages. This can also happen when a single -container is running both the core GitLab application and GitLab Pages. - -AWS [recommends using an IP target type](https://aws.amazon.com/premiumsupport/knowledge-center/target-connection-fails-load-balancer/) -to resolve this issue. - -Turning off [client IP preservation](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-target-groups.html#client-ip-preservation) -may resolve this issue when the core GitLab application and GitLab Pages run on the same host or -container. - -### 500 error with `securecookie: failed to generate random iv` and `Failed to save the session` - -This problem most likely results from an [out-dated operating system](../package_information/supported_os.md#os-versions-that-are-no-longer-supported). -The [Pages daemon uses the `securecookie` library](https://gitlab.com/search?group_id=9970&project_id=734943&repository_ref=master&scope=blobs&search=securecookie&snippets=false) to get random strings via [`crypto/rand` in Go](https://pkg.go.dev/crypto/rand#pkg-variables). -This requires the `getrandom` system call or `/dev/urandom` to be available on the host OS. -Upgrading to an [officially supported operating system](https://about.gitlab.com/install/) is recommended. - -### The requested scope is invalid, malformed, or unknown - -This problem comes from the permissions of the GitLab Pages OAuth application. To fix it: - -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Applications > GitLab Pages**. -1. Edit the application. -1. Under **Scopes**, ensure that the `api` scope is selected. -1. Save your changes. - -When running a [separate Pages server](#running-gitlab-pages-on-a-separate-server), -this setting needs to be configured on the main GitLab server. - -### Workaround in case no wildcard DNS entry can be set - -If the wildcard DNS [prerequisite](#prerequisites) can't be met, you can still use GitLab Pages in a limited fashion: - -1. [Move](../../user/project/settings/index.md#transfer-a-project-to-another-namespace) - all projects you need to use Pages with into a single group namespace, for example `pages`. -1. Configure a [DNS entry](#dns-configuration) without the `*.`-wildcard, for example `pages.example.io`. -1. Configure `pages_external_url http://example.io/` in your `gitlab.rb` file. - Omit the group namespace here, because it automatically is prepended by GitLab. - -### Pages daemon fails with permission denied errors - -If `/tmp` is mounted with `noexec`, the Pages daemon fails to start with an error like: - -```plaintext -{"error":"fork/exec /gitlab-pages: permission denied","level":"fatal","msg":"could not create pages daemon","time":"2021-02-02T21:54:34Z"} -``` +> [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/632) in GitLab 14.9. -In this case, change `TMPDIR` to a location that is not mounted with `noexec`. Add the following to -`/etc/gitlab/gitlab.rb`: - -```ruby -gitlab_pages['env'] = {'TMPDIR' => '<new_tmp_path>'} -``` - -Once added, reconfigure with `sudo gitlab-ctl reconfigure` and restart GitLab with -`sudo gitlab-ctl restart`. - -### `The redirect URI included is not valid.` when using Pages Access Control - -You may see this error if `pages_external_url` was updated at some point of time. Verify the following: - -1. The **Callback URL**/Redirect URI in the GitLab Pages [System OAuth application](../../integration/oauth_provider.md#create-an-instance-wide-application) -is using the protocol (HTTP or HTTPS) that `pages_external_url` is configured to use. -1. The domain and path components of `Redirect URI` are valid: they should look like `projects.<pages_external_url>/auth`. - -### 500 error `cannot serve from disk` - -If you get a 500 response from Pages and encounter an error similar to: - -```plaintext -ERRO[0145] cannot serve from disk error="gitlab: disk access is disabled via enable-disk=false" project_id=27 source_path="file:///shared/pages/@hashed/67/06/670671cd97404156226e507973f2ab8330d3022ca96e0c93bdbdb320c41adcaf/pages_deployments/14/artifacts.zip" source_type=zip -``` - -It means that GitLab Rails is telling GitLab Pages to serve content from a location on disk, -however, GitLab Pages was configured to disable disk access. - -To enable disk access: - -1. Enable disk access for GitLab Pages in `/etc/gitlab/gitlab.rb`: +1. Set rate limits in `/etc/gitlab/gitlab.rb`: ```ruby - gitlab_pages['enable_disk'] = true + gitlab_pages['rate_limit_tls_source_ip'] = 20.0 + gitlab_pages['rate_limit_tls_source_ip_burst'] = 600 ``` 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). -### `httprange: new resource 403` - -If you see an error similar to: - -```plaintext -{"error":"httprange: new resource 403: \"403 Forbidden\"","host":"root.pages.example.com","level":"error","msg":"vfs.Root","path":"/pages1/","time":"2021-06-10T08:45:19Z"} -``` - -And you run pages on the separate server syncing files via NFS, it may mean that -the shared pages directory is mounted on a different path on the main GitLab server and the -GitLab Pages server. +#### Enable TLS connections rate limits by domain -In that case, it's highly recommended you to configure -[object storage and migrate any existing pages data to it](#using-object-storage). +> [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/632) in GitLab 14.9. -Alternatively, you can mount the GitLab Pages shared directory to the same path on -both servers. - -### GitLab Pages doesn't work after upgrading to GitLab 14.0 or above - -GitLab 14.0 introduces a number of changes to GitLab Pages which may require manual intervention. - -1. Firstly [follow the migration guide](#prepare-gitlab-pages-for-140). -1. Try to upgrade to GitLab 14.3 or above. Some of the issues were fixed in GitLab 14.1, 14.2 and 14.3. -1. If it doesn't work, see [GitLab Pages logs](#how-to-see-gitlab-pages-logs), and if you see any errors there then search them on this page. - -WARNING: -In GitLab 14.0-14.2 you can temporarily enable legacy storage and configuration mechanisms. - -To do that: - -1. Describe the issue you're seeing in the [migration feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/331699). - -1. Edit `/etc/gitlab/gitlab.rb`: +1. Set rate limits in `/etc/gitlab/gitlab.rb`: ```ruby - gitlab_pages['use_legacy_storage'] = true + gitlab_pages['rate_limit_tls_domain'] = 1000 + gitlab_pages['rate_limit_tls_domain_burst'] = 5000 ``` 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). -### GitLab Pages deploy job fails with error "is not a recognized provider" - -If the **pages** job succeeds but the **deploy** job gives the error "is not a recognized provider": - - - -The error message `is not a recognized provider` could be coming from the `fog` gem that GitLab uses to connect to cloud providers for object storage. - -To fix that: - -1. Check your `gitlab.rb` file. If you have `gitlab_rails['pages_object_store_enabled']` enabled, but no bucket details have been configured, either: - - - Configure object storage for your Pages deployments, following the [S3-compatible connection settings](#s3-compatible-connection-settings) guide. - - Store your deployments locally, by commenting out that line. - -1. Save the changes you made to your `gitlab.rb` file, then [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). - -### 404 error `The page you're looking for could not be found` - -If you get a `404 Page Not Found` response from GitLab Pages: - -1. Check `.gitlab-ci.yml` contains the job `pages:`. -1. Check the current project's pipeline to confirm the job `pages:deploy` is being run. +## Related topics -Without the `pages:deploy` job, the updates to your GitLab Pages site are never published. +- [Troubleshooting GitLab Pages administration](troubleshooting.md) diff --git a/doc/administration/pages/source.md b/doc/administration/pages/source.md index db76d15ec58..b36b87f3b1d 100644 --- a/doc/administration/pages/source.md +++ b/doc/administration/pages/source.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Editor +stage: Plan +group: Knowledge info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -10,8 +10,8 @@ NOTE: Before attempting to enable GitLab Pages, first make sure you have [installed GitLab](../../install/installation.md) successfully. -This is the documentation for configuring a GitLab Pages when you have installed -GitLab from source and not using the Omnibus packages. +This document explains how to configure GitLab Pages when you have installed +GitLab from source and not the Omnibus packages. You are encouraged to read the [Omnibus documentation](index.md) as it provides invaluable information about the configuration of GitLab Pages. @@ -20,12 +20,11 @@ We also highly recommend that you use the Omnibus GitLab packages. We optimize them specifically for GitLab, and we take care of upgrading GitLab Pages to the latest supported version. -## Overview +## How GitLab Pages works -GitLab Pages makes use of the [GitLab Pages daemon](https://gitlab.com/gitlab-org/gitlab-pages), a simple HTTP server -written in Go that can listen on an external IP address and provide support for -custom domains and custom certificates. It supports dynamic certificates through -SNI and exposes pages using HTTP2 by default. +GitLab Pages makes use of the [GitLab Pages daemon](https://gitlab.com/gitlab-org/gitlab-pages), a lightweight HTTP server that listens on an external IP address and provides support for +custom domains and certificates. It supports dynamic certificates through +`SNI` and exposes pages using HTTP2 by default. You are encouraged to read its [README](https://gitlab.com/gitlab-org/gitlab-pages/blob/master/README.md) to fully understand how it works. @@ -57,7 +56,7 @@ Before proceeding with the Pages configuration, make sure that: assume that to be `example.io`. - You have configured a **wildcard DNS record** for that domain. - You have installed the `zip` and `unzip` packages in the same server that - GitLab is installed since they are needed to compress and decompress the + GitLab is installed because they are needed to compress and decompress the Pages artifacts. - Optional. You have a **wildcard certificate** for the Pages domain if you decide to serve Pages (`*.example.io`) under HTTPS. @@ -86,7 +85,7 @@ see the [security section](#security). Depending on your needs, you can set up GitLab Pages in 4 different ways. The following options are listed from the easiest setup to the most advanced one. The absolute minimum requirement is to set up the wildcard DNS -since that is needed in all configurations. +because that is needed in all configurations. ### Wildcard domains @@ -96,7 +95,7 @@ since that is needed in all configurations. URL scheme: `http://<namespace>.example.io/<project_slug>` -This is the minimum setup that you can use Pages with. It is the base for all +This setup is the minimum you can use Pages with. It is the base for all other setups as described below. NGINX proxies all requests to the daemon. The Pages daemon doesn't listen to the outside world. @@ -150,8 +149,8 @@ The Pages daemon doesn't listen to the outside world. You may use an `http` address, when running GitLab Pages and GitLab on the same host. If you use `https` and use a self-signed certificate, be sure to - make your custom CA available to GitLab Pages, for example by setting the - `SSL_CERT_DIR` environment variable. + make your custom CA available to GitLab Pages. For example, you can do this + by setting the `SSL_CERT_DIR` environment variable. 1. Add the secret API key: @@ -264,8 +263,8 @@ that without TLS certificates. URL scheme: `http://<namespace>.example.io/<project_slug>` and `http://custom-domain.com` -In that case, the pages daemon is running, NGINX still proxies requests to -the daemon but the daemon is also able to receive requests from the outside +In that case, the pages daemon is running. NGINX still proxies requests to +the daemon, but the daemon is also able to receive requests from the outside world. Custom domains are supported, but no TLS. 1. Install the Pages daemon: @@ -296,10 +295,9 @@ world. Custom domains are supported, but no TLS. external_http: 192.0.2.2:80 ``` -1. Edit `/etc/default/gitlab` and set `gitlab_pages_enabled` to `true` in - order to enable the pages daemon. In `gitlab_pages_options` the - `-pages-domain` and `-listen-http` must match the `host` and `external_http` - settings that you set above respectively: +1. To enable the daemon, edit `/etc/default/gitlab` and set `gitlab_pages_enabled` to `true`. + In `gitlab_pages_options`, the value for `-pages-domain` must match the `host` and `-listen-http` must match + the `external_http`: ```ini gitlab_pages_enabled=true @@ -329,8 +327,8 @@ world. Custom domains are supported, but no TLS. URL scheme: `https://<namespace>.example.io/<project_slug>` and `https://custom-domain.com` -In that case, the pages daemon is running, NGINX still proxies requests to -the daemon but the daemon is also able to receive requests from the outside +In that case, the pages daemon is running. NGINX still proxies requests to +the daemon, but the daemon is also able to receive requests from the outside world. Custom domains and TLS are supported. 1. Install the Pages daemon: @@ -416,8 +414,8 @@ server_name ~^.*\.pages\.example\.io$; ## Access control -GitLab Pages access control can be configured per-project, and allows access to a Pages -site to be controlled based on a user's membership to that project. +GitLab Pages access control can be configured per project. Access to a Pages +site can be controlled based on a user's membership to that project. Access control works by registering the Pages daemon as an OAuth application with GitLab. Whenever a request to access a private Pages site is made by an diff --git a/doc/administration/pages/troubleshooting.md b/doc/administration/pages/troubleshooting.md new file mode 100644 index 00000000000..6f00ae074f5 --- /dev/null +++ b/doc/administration/pages/troubleshooting.md @@ -0,0 +1,304 @@ +--- +stage: Plan +group: Knowledge +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Troubleshooting GitLab Pages administration **(FREE SELF)** + +This page contains a list of issues you might encounter when administering GitLab Pages. + +## How to see GitLab Pages logs + +You can see Pages daemon logs by running: + +```shell +sudo gitlab-ctl tail gitlab-pages +``` + +You can also find the log file in `/var/log/gitlab/gitlab-pages/current`. + +## `unsupported protocol scheme \"\""` + +If you see the following error: + +```plaintext +{"error":"failed to connect to internal Pages API: Get \"/api/v4/internal/pages/status\": unsupported protocol scheme \"\"","level":"warning","msg":"attempted to connect to the API","time":"2021-06-23T20:03:30Z"} +``` + +It means you didn't set the HTTP(S) protocol scheme in the Pages server settings. +To fix it: + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_pages['gitlab_server'] = "https://<your_gitlab_server_public_host_and_port>" + gitlab_pages['internal_gitlab_server'] = "https://<your_gitlab_server_private_host_and_port>" # optional, gitlab_pages['gitlab_server'] is used as default + ``` + +1. Reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +## 502 error when connecting to GitLab Pages proxy when server does not listen over IPv6 + +In some cases, NGINX might default to using IPv6 to connect to the GitLab Pages +service even when the server does not listen over IPv6. You can identify when +this is happening if you see something similar to the log entry below in the +`gitlab_pages_error.log`: + +```plaintext +2020/02/24 16:32:05 [error] 112654#0: *4982804 connect() failed (111: Connection refused) while connecting to upstream, client: 123.123.123.123, server: ~^(?<group>.*)\.pages\.example\.com$, request: "GET /-/group/project/-/jobs/1234/artifacts/artifact.txt HTTP/1.1", upstream: "http://[::1]:8090//-/group/project/-/jobs/1234/artifacts/artifact.txt", host: "group.example.com" +``` + +To resolve this, set an explicit IP and port for the GitLab Pages `listen_proxy` setting +to define the explicit address that the GitLab Pages daemon should listen on: + +```ruby +gitlab_pages['listen_proxy'] = '127.0.0.1:8090' +``` + +## Intermittent 502 errors or after a few days + +If you run Pages on a system that uses `systemd` and +[`tmpfiles.d`](https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html), +you may encounter intermittent 502 errors trying to serve Pages with an error similar to: + +```plaintext +dial tcp: lookup gitlab.example.com on [::1]:53: dial udp [::1]:53: connect: no route to host" +``` + +GitLab Pages creates a [bind mount](https://man7.org/linux/man-pages/man8/mount.8.html) +inside `/tmp/gitlab-pages-*` that includes files like `/etc/hosts`. +However, `systemd` may clean the `/tmp/` directory on a regular basis so the DNS +configuration may be lost. + +To stop `systemd` from cleaning the Pages related content: + +1. Tell `tmpfiles.d` to not remove the Pages `/tmp` directory: + + ```shell + echo 'x /tmp/gitlab-pages-*' >> /etc/tmpfiles.d/gitlab-pages-jail.conf + ``` + +1. Restart GitLab Pages: + + ```shell + sudo gitlab-ctl restart gitlab-pages + ``` + +## Unable to access GitLab Pages + +If you can't access your GitLab Pages (such as receiving `502 Bad Gateway` errors, or a login loop) +and in your Pages log shows this error: + +```plaintext +"error":"retrieval context done: context deadline exceeded","host":"root.docs-cit.otenet.gr","level":"error","msg":"could not fetch domain information from a source" +``` + +1. Add the following to `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_pages['internal_gitlab_server'] = 'http://localhost:8080' + ``` + +1. Restart GitLab Pages: + + ```shell + sudo gitlab-ctl restart gitlab-pages + ``` + +## Failed to connect to the internal GitLab API + +If you see the following error: + +```plaintext +ERRO[0010] Failed to connect to the internal GitLab API after 0.50s error="failed to connect to internal Pages API: HTTP status: 401" +``` + +If you are [Running GitLab Pages on a separate server](index.md#running-gitlab-pages-on-a-separate-server) +you must copy the `/etc/gitlab/gitlab-secrets.json` file +from the **GitLab server** to the **Pages server** after upgrading to GitLab 13.3, +as described in that section. + +Other reasons may include network connectivity issues between your +**GitLab server** and your **Pages server** such as firewall configurations or closed ports. +For example, if there is a connection timeout: + +```plaintext +error="failed to connect to internal Pages API: Get \"https://gitlab.example.com:3000/api/v4/internal/pages/status\": net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)" +``` + +## Pages cannot communicate with an instance of the GitLab API + +If you use the default value for `domain_config_source=auto` and run multiple instances of GitLab +Pages, you may see intermittent 502 error responses while serving Pages content. You may also see +the following warning in the Pages logs: + +```plaintext +WARN[0010] Pages cannot communicate with an instance of the GitLab API. Please sync your gitlab-secrets.json file https://gitlab.com/gitlab-org/gitlab-pages/-/issues/535#workaround. error="pages endpoint unauthorized" +``` + +This can happen if your `gitlab-secrets.json` file is out of date between GitLab Rails and GitLab +Pages. Follow steps 8-10 of [Running GitLab Pages on a separate server](index.md#running-gitlab-pages-on-a-separate-server), +in all of your GitLab Pages instances. + +## Intermittent 502 errors when using an AWS Network Load Balancer and GitLab Pages + +Connections will time out when using a Network Load Balancer with client IP preservation enabled and [the request is looped back to the source server](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-troubleshooting.html#loopback-timeout). +This can happen to GitLab instances with multiple servers +running both the core GitLab application and GitLab Pages. This can also happen when a single +container is running both the core GitLab application and GitLab Pages. + +AWS [recommends using an IP target type](https://aws.amazon.com/premiumsupport/knowledge-center/target-connection-fails-load-balancer/) +to resolve this issue. + +Turning off [client IP preservation](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-target-groups.html#client-ip-preservation) +may resolve this issue when the core GitLab application and GitLab Pages run on the same host or +container. + +## 500 error with `securecookie: failed to generate random iv` and `Failed to save the session` + +This problem most likely results from an [out-dated operating system](../package_information/supported_os.md#os-versions-that-are-no-longer-supported). +The [Pages daemon uses the `securecookie` library](https://gitlab.com/search?group_id=9970&project_id=734943&repository_ref=master&scope=blobs&search=securecookie&snippets=false) to get random strings via [`crypto/rand` in Go](https://pkg.go.dev/crypto/rand#pkg-variables). +This requires the `getrandom` system call or `/dev/urandom` to be available on the host OS. +Upgrading to an [officially supported operating system](https://about.gitlab.com/install/) is recommended. + +## The requested scope is invalid, malformed, or unknown + +This problem comes from the permissions of the GitLab Pages OAuth application. To fix it: + +1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, select **Applications > GitLab Pages**. +1. Edit the application. +1. Under **Scopes**, ensure that the `api` scope is selected. +1. Save your changes. + +When running a [separate Pages server](index.md#running-gitlab-pages-on-a-separate-server), +this setting needs to be configured on the main GitLab server. + +## Workaround in case no wildcard DNS entry can be set + +If the wildcard DNS [prerequisite](index.md#prerequisites) can't be met, you can still use GitLab Pages in a limited fashion: + +1. [Move](../../user/project/settings/index.md#transfer-a-project-to-another-namespace) + all projects you need to use Pages with into a single group namespace, for example `pages`. +1. Configure a [DNS entry](index.md#dns-configuration) without the `*.`-wildcard, for example `pages.example.io`. +1. Configure `pages_external_url http://example.io/` in your `gitlab.rb` file. + Omit the group namespace here, because it automatically is prepended by GitLab. + +## Pages daemon fails with permission denied errors + +If `/tmp` is mounted with `noexec`, the Pages daemon fails to start with an error like: + +```plaintext +{"error":"fork/exec /gitlab-pages: permission denied","level":"fatal","msg":"could not create pages daemon","time":"2021-02-02T21:54:34Z"} +``` + +In this case, change `TMPDIR` to a location that is not mounted with `noexec`. Add the following to +`/etc/gitlab/gitlab.rb`: + +```ruby +gitlab_pages['env'] = {'TMPDIR' => '<new_tmp_path>'} +``` + +Once added, reconfigure with `sudo gitlab-ctl reconfigure` and restart GitLab with +`sudo gitlab-ctl restart`. + +## `The redirect URI included is not valid.` when using Pages Access Control + +You may see this error if `pages_external_url` was updated at some point of time. Verify the following: + +1. The **Callback URL**/Redirect URI in the GitLab Pages [System OAuth application](../../integration/oauth_provider.md#create-an-instance-wide-application) +is using the protocol (HTTP or HTTPS) that `pages_external_url` is configured to use. +1. The domain and path components of `Redirect URI` are valid: they should look like `projects.<pages_external_url>/auth`. + +## 500 error `cannot serve from disk` + +If you get a 500 response from Pages and encounter an error similar to: + +```plaintext +ERRO[0145] cannot serve from disk error="gitlab: disk access is disabled via enable-disk=false" project_id=27 source_path="file:///shared/pages/@hashed/67/06/670671cd97404156226e507973f2ab8330d3022ca96e0c93bdbdb320c41adcaf/pages_deployments/14/artifacts.zip" source_type=zip +``` + +It means that GitLab Rails is telling GitLab Pages to serve content from a location on disk, +however, GitLab Pages was configured to disable disk access. + +To enable disk access: + +1. Enable disk access for GitLab Pages in `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_pages['enable_disk'] = true + ``` + +1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). + +## `httprange: new resource 403` + +If you see an error similar to: + +```plaintext +{"error":"httprange: new resource 403: \"403 Forbidden\"","host":"root.pages.example.com","level":"error","msg":"vfs.Root","path":"/pages1/","time":"2021-06-10T08:45:19Z"} +``` + +And you run pages on the separate server syncing files via NFS, it may mean that +the shared pages directory is mounted on a different path on the main GitLab server and the +GitLab Pages server. + +In that case, it's highly recommended you to configure +[object storage and migrate any existing pages data to it](index.md#using-object-storage). + +Alternatively, you can mount the GitLab Pages shared directory to the same path on +both servers. + +## GitLab Pages doesn't work after upgrading to GitLab 14.0 or above + +GitLab 14.0 introduces a number of changes to GitLab Pages which may require manual intervention. + +1. Firstly [follow the migration guide](index.md#prepare-gitlab-pages-for-140). +1. Try to upgrade to GitLab 14.3 or above. Some of the issues were fixed in GitLab 14.1, 14.2 and 14.3. +1. If it doesn't work, see [GitLab Pages logs](#how-to-see-gitlab-pages-logs), and if you see any errors there then search them on this page. + +WARNING: +In GitLab 14.0-14.2 you can temporarily enable legacy storage and configuration mechanisms. + +To do that: + +1. Describe the issue you're seeing in the [migration feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/331699). + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_pages['use_legacy_storage'] = true + ``` + +1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). + +## GitLab Pages deploy job fails with error "is not a recognized provider" + +If the **pages** job succeeds but the **deploy** job gives the error "is not a recognized provider": + + + +The error message `is not a recognized provider` could be coming from the `fog` gem that GitLab uses to connect to cloud providers for object storage. + +To fix that: + +1. Check your `gitlab.rb` file. If you have `gitlab_rails['pages_object_store_enabled']` enabled, but no bucket details have been configured, either: + + - Configure object storage for your Pages deployments, following the [S3-compatible connection settings](index.md#s3-compatible-connection-settings) guide. + - Store your deployments locally, by commenting out that line. + +1. Save the changes you made to your `gitlab.rb` file, then [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). + +## 404 error `The page you're looking for could not be found` + +If you get a `404 Page Not Found` response from GitLab Pages: + +1. Check `.gitlab-ci.yml` contains the job `pages:`. +1. Check the current project's pipeline to confirm the job `pages:deploy` is being run. + +Without the `pages:deploy` job, the updates to your GitLab Pages site are never published. |