diff options
Diffstat (limited to 'doc/administration/pages/index.md')
| -rw-r--r-- | doc/administration/pages/index.md | 71 |
1 files changed, 56 insertions, 15 deletions
diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 9e949468805..2b7a7300ad8 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -190,7 +190,7 @@ outside world. ### Additional configuration for Docker container The GitLab Pages daemon doesn't have permissions to bind mounts when it runs -in a Docker container. To overcome this issue, you must change the chroot +in a Docker container. To overcome this issue, you must change the `chroot` behavior: 1. Edit `/etc/gitlab/gitlab.rb`. @@ -222,7 +222,7 @@ control over how the Pages daemon runs and serves content in your environment. | `api_secret_key` | Full path to file with secret key used to authenticate with the GitLab API. Auto-generated when left unset. | `artifacts_server` | Enable viewing [artifacts](../job_artifacts.md) in GitLab Pages. | `artifacts_server_timeout` | Timeout (in seconds) for a proxied request to the artifacts server. -| `artifacts_server_url` | API URL to proxy artifact requests to. Defaults to GitLab `external URL` + `/api/v4`, for example `https://gitlab.com/api/v4`. +| `artifacts_server_url` | API URL to proxy artifact requests to. Defaults to GitLab `external URL` + `/api/v4`, for example `https://gitlab.com/api/v4`. When running a [separate Pages server](#running-gitlab-pages-on-a-separate-server), this URL must point to the main GitLab server's API. | `auth_redirect_uri` | Callback URL for authenticating with GitLab. Defaults to project's subdomain of `pages_external_url` + `/auth`. | `auth_secret` | Secret key for signing authentication requests. Leave blank to pull automatically from GitLab during OAuth registration. | `dir` | Working directory for configuration and secrets files. @@ -236,7 +236,7 @@ control over how the Pages daemon runs and serves content in your environment. | `gitlab_secret` | The OAuth application secret. Leave blank to automatically fill when Pages authenticates with GitLab. | `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. -| `inplace_chroot` | On [systems that don't support bind-mounts](index.md#additional-configuration-for-docker-container), this instructs GitLab Pages to chroot into its `pages_path` directory. Some caveats exist when using inplace chroot; refer to the GitLab Pages [README](https://gitlab.com/gitlab-org/gitlab-pages/blob/master/README.md#caveats) for more information. +| `inplace_chroot` | On [systems that don't support bind-mounts](index.md#additional-configuration-for-docker-container), this instructs GitLab Pages to `chroot` into its `pages_path` directory. Some caveats exist when using in-place `chroot`; refer to the GitLab Pages [README](https://gitlab.com/gitlab-org/gitlab-pages/blob/master/README.md#caveats) for more information. | `insecure_ciphers` | Use default list of cipher suites, may contain insecure ones like 3DES and RC4. | `internal_gitlab_server` | Internal GitLab server address used exclusively for API requests. Useful if you want to send that traffic over an internal load balancer. Defaults to GitLab `external_url`. | `listen_proxy` | The addresses to listen on for reverse-proxy requests. Pages binds to these addresses' network sockets and receives incoming requests from them. Sets the value of `proxy_pass` in `$nginx-dir/conf/gitlab-pages.conf`. @@ -538,7 +538,7 @@ the below steps to do a no downtime transfer to a new storage location. 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). 1. Verify Pages are still being served up as expected. -1. Unpause Pages deployments by removing from `/etc/gitlab/gitlab.rb` the `sidekiq` setting set above. +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` @@ -573,7 +573,7 @@ You can configure the maximum size of the unpacked archive per project in **Admin Area > Settings > Preferences > Pages**, in **Maximum size of pages (MB)**. The default is 100MB. -### Override maximum pages size per project or group **(PREMIUM ONLY)** +### Override maximum pages size per project or group **(PREMIUM SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16610) in GitLab 12.7. @@ -629,7 +629,7 @@ database encryption. Proceed with caution. on the **Pages server** and configure this share to allow access from your main **GitLab server**. Note that the example there is more general and - shares several sub-directories from `/home` to several `/nfs/home` mountpoints. + shares several sub-directories from `/home` to several `/nfs/home` mount points. For our Pages-specific example here, we instead share only the default GitLab Pages folder `/var/opt/gitlab/gitlab-rails/shared/pages` from the **Pages server** and we mount it to `/mnt/pages` @@ -730,6 +730,13 @@ or report an issue. ### Object storage settings +WARNING: +With the following settings, Pages uses both NFS and Object Storage locations when deploying the +site. **Do not remove the existing NFS mount used by Pages** when applying these settings. For more +information, see the epics +[3901](https://gitlab.com/groups/gitlab-org/-/epics/3901#how-to-test-object-storage-integration-in-beta) +and [3910](https://gitlab.com/groups/gitlab-org/-/epics/3910). + The following settings are: - Nested under `pages:` and then `object_store:` on source installations. @@ -818,7 +825,7 @@ but commented out to help encourage others to add to it in the future. --> ### `open /etc/ssl/ca-bundle.pem: permission denied` -GitLab Pages runs inside a chroot jail, usually in a uniquely numbered directory like +GitLab Pages runs inside a `chroot` jail, usually in a uniquely numbered directory like `/tmp/gitlab-pages-*`. Within the jail, a bundle of trusted certificates is @@ -828,7 +835,7 @@ from `/opt/gitlab/embedded/ssl/certs/cacert.pem` as part of starting up Pages. If the permissions on the source file are incorrect (they should be `0644`), then -the file inside the chroot jail is also wrong. +the file inside the `chroot` jail is also wrong. Pages logs errors in `/var/log/gitlab/gitlab-pages/current` like: @@ -837,8 +844,8 @@ x509: failed to load system roots and no roots provided open /etc/ssl/ca-bundle.pem: permission denied ``` -The use of a chroot jail makes this error misleading, as it is not -referring to `/etc/ssl` on the root filesystem. +The use of a `chroot` jail makes this error misleading, as it is not +referring to `/etc/ssl` on the root file system. The fix is to correct the source file permissions and restart Pages: @@ -862,8 +869,8 @@ open /opt/gitlab/embedded/ssl/certs/cacert.pem: no such file or directory x509: certificate signed by unknown authority ``` -The reason for those errors is that the files `resolv.conf` and `ca-bundle.pem` are missing inside the chroot. -The fix is to copy the host's `/etc/resolv.conf` and the GitLab certificate bundle inside the chroot: +The reason for those errors is that the files `resolv.conf` and `ca-bundle.pem` are missing inside the `chroot`. +The fix is to copy the host's `/etc/resolv.conf` and the GitLab certificate bundle inside the `chroot`: ```shell sudo mkdir -p /var/opt/gitlab/gitlab-rails/shared/pages/etc/ssl @@ -895,7 +902,7 @@ gitlab_pages['listen_proxy'] = '127.0.0.1:8090' ### 404 error after transferring project to a different group or user If you encounter a `404 Not Found` error a Pages site after transferring a project to -another group or user, you must trigger adomain configuration update for Pages. To do +another group or user, you must trigger a domain configuration update for Pages. To do so, write something in the `.update` file. The Pages daemon monitors for changes to this file, and reloads the configuration when changes occur. @@ -928,11 +935,25 @@ For example, if there is a connection timeout: 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. + ### 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](https://docs.gitlab.com/omnibus/package-information/deprecated_os.html). -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://golang.org/pkg/crypto/rand/#pkg-variables). -This requires the `getrandom` syscall or `/dev/urandom` to be available on the host OS. +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://golang.org/pkg/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 @@ -940,6 +961,8 @@ Upgrading to an [officially supported operating system](https://about.gitlab.com This problem comes from the permissions of the GitLab Pages OAuth application. To fix it, go to **Admin > Applications > GitLab Pages** and edit the application. Under **Scopes**, ensure that the `api` scope is selected and 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 @@ -948,3 +971,21 @@ If the wildcard DNS [prerequisite](#prerequisites) can't be met, you can still u 1. [Move](../../user/project/settings/index.md#transferring-an-existing-project-into-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`. + +### 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`. |