summaryrefslogtreecommitdiff
path: root/doc/administration/pages/index.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/administration/pages/index.md')
-rw-r--r--doc/administration/pages/index.md125
1 files changed, 108 insertions, 17 deletions
diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md
index 9e949468805..655e35c3e60 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`.
@@ -216,13 +216,13 @@ control over how the Pages daemon runs and serves content in your environment.
| Setting | Description |
| ------- | ----------- |
-| `pages_external_url` | The URL where GitLab Pages is accessible, including protocol (HTTP / HTTPS). If `https://` is used, you must also set `gitlab_pages['ssl_certificate']` and `gitlab_pages['ssl_certificate_key']`.
+| `pages_external_url` | The URL where GitLab Pages is accessible, including protocol (HTTP / HTTPS). If `https://` is used, additional configuration is required. See [Wildcard domains with TLS support](#wildcard-domains-with-tls-support) and [Custom domains with TLS support](#custom-domains-with-tls-support) for details.
| `gitlab_pages[]` | |
| `access_control` | Whether to enable [access control](index.md#access-control).
| `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.
@@ -234,9 +234,10 @@ control over how the Pages daemon runs and serves content in your environment.
| `domain_config_source` | Domain configuration source (default: `auto`)
| `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.
| `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`.
@@ -400,6 +401,25 @@ NOTE:
For this setting to be effective with multi-node setups, it has to be applied to
all the App nodes and Sidekiq nodes.
+#### Using Pages with reduced authentication scope
+
+By default, the Pages daemon uses the `api` scope to authenticate. You can configure this. For
+example, this reduces the scope to `read_api` in `/etc/gitlab/gitlab.rb`:
+
+```ruby
+gitlab_pages['auth_scope'] = 'read_api'
+```
+
+The scope to use for authentication must match the GitLab Pages OAuth application settings. Users of
+pre-existing applications must modify the GitLab Pages OAuth application. Follow these steps to do
+this:
+
+1. Navigate to your instance's **Admin Area > Settings > Applications** and expand **GitLab Pages**
+ settings.
+1. Clear the `api` scope's checkbox and select the desired scope's checkbox (for example,
+ `read_api`).
+1. Click **Save changes**.
+
#### Disabling public access to all Pages websites
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32095) in GitLab 12.7.
@@ -538,7 +558,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 +593,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 +649,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`
@@ -689,7 +709,7 @@ Pages server.
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217912) in GitLab 13.3.
GitLab Pages can use different sources to get domain configuration.
-The default value is `nil`. However, GitLab Pages defaults to `auto`.
+The default value for Omnibus installations is `nil`.
```ruby
gitlab_pages['domain_config_source'] = nil
@@ -700,8 +720,33 @@ preferred source is `gitlab`, which uses [API-based configuration](#gitlab-api-b
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/).
+### Deprecated domain_config_source
+
+WARNING:
+The flag `gitlab_pages['domain_config_source']` is deprecated for use in [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/issues/217913),
+and is planned for removal in GitLab 14.0.
+
+GitLab 13.0 introduced the special flag `domain_config_source` to support manual opt-in to
+[API-based configuration](#gitlab-api-based-configuration).
+GitLab 13.7 introduced the [`auto` value](https://gitlab.com/gitlab-org/gitlab/-/issues/218358)
+to support a smoother transition to API-based configuration.
+
+Starting with GitLab 14.0, GitLab Pages only supports API-based configuration, and
+[disk source configuration is removed](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/382).
+Therefore, GitLab 14.0 also removes `domain_config_source`.
+
+GitLab Pages fails to start if it can't connect to the GitLab API. For other common issues, see the
+[troubleshooting section](#failed-to-connect-to-the-internal-gitlab-api)
+or report an issue.
+
### GitLab API-based configuration
+WARNING:
+The flag `gitlab_pages['domain_config_source']` is deprecated for use in [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/issues/217913),
+and is planned for removal in GitLab 14.0. In GitLab 14.0 and later, GitLab Pages attempts to
+connect to the API automatically, without requiring the manual configuration steps shown here. Pages
+fails to start if this automatic connection fails.
+
GitLab Pages can use an API-based configuration. This replaces disk source configuration, which
was used prior to GitLab 13.0. Follow these steps to enable it:
@@ -730,6 +775,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 +870,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 +880,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 +889,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 +914,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 +947,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 +980,30 @@ 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
+
+WARNING:
+The flag `gitlab_pages['domain_config_source']` is [deprecated](#deprecated-domain_config_source)
+for use in [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/issues/217913),
+and is planned for removal in GitLab 14.0.
+
+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 +1011,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 +1021,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`.