diff options
Diffstat (limited to 'doc/administration/pages/index.md')
| -rw-r--r-- | doc/administration/pages/index.md | 88 |
1 files changed, 77 insertions, 11 deletions
diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 21d13be47bd..a7a3a86de8e 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -1,4 +1,7 @@ --- +stage: Release +group: Release Management +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/#designated-technical-writers description: 'Learn how to administer GitLab Pages.' --- @@ -6,9 +9,9 @@ description: 'Learn how to administer GitLab Pages.' > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80) in GitLab EE 8.3. > - Custom CNAMEs with TLS support were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/173) in GitLab EE 8.5. -> - GitLab Pages [was ported](https://gitlab.com/gitlab-org/gitlab-foss/issues/14605) to Community Edition in GitLab 8.17. +> - GitLab Pages [was ported](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/14605) to Community Edition in GitLab 8.17. > - Support for subgroup project's websites was -> [introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/30548) in GitLab 11.8. +> [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/30548) in GitLab 11.8. GitLab Pages allows for hosting of static sites. It must be configured by an administrator. Separate [user documentation](../../user/project/pages/index.md) is available. @@ -75,7 +78,7 @@ among other things. Follow [these instructions](https://publicsuffix.org/submit/) to submit your GitLab Pages subdomain. For instance, if your domain is `example.io`, you should request that `example.io` is added to the Public Suffix List. GitLab.com -added `gitlab.io` [in 2016](https://gitlab.com/gitlab-com/infrastructure/issues/230). +added `gitlab.io` [in 2016](https://gitlab.com/gitlab-com/infrastructure/-/issues/230). ### DNS configuration @@ -98,7 +101,8 @@ You should not use the GitLab domain to serve user pages. For more information s ## Configuration 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 + +The following examples 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. @@ -175,6 +179,64 @@ NOTE: **Note:** `inplace_chroot` option might not work with the other features, such as [Pages Access Control](#access-control). The [GitLab Pages README](https://gitlab.com/gitlab-org/gitlab-pages#caveats) has more information about caveats and workarounds. +### Global settings + +Below is a table of all configuration settings known to Pages in Omnibus GitLab, +and what they do. These options can be adjusted in `/etc/gitlab/gitlab.rb`, +and will take effect after you [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). +Most of these settings don't need to be configured manually unless you need more granular +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']`. +| **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`. +| `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 config and secrets files. +| `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`. +| `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_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. +| `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. +| `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 will bind to these addresses' network socket and receives incoming requests from it. Sets the value of `proxy_pass` in `$nginx-dir/conf/gitlab-pages.conf`. +| `log_directory` | Absolute path to a log directory. +| `log_format` | The log output format: 'text' or 'json'. +| `log_verbose` | Verbose logging, true/false. +| `max_connections` | Limit on the number of concurrent connections to the HTTP, HTTPS or proxy listeners. +| `metrics_address` | The address to listen on for metrics requests. +| `redirect_http` | Redirect pages from HTTP to HTTPS, true/false. +| `sentry_dsn` | The address for sending Sentry crash reporting to. +| `sentry_enabled` | Enable reporting and logging with Sentry, true/false. +| `sentry_environment` | The environment for Sentry crash reporting. +| `status_uri` | The URL path for a status page, for example, `/@status`. +| `tls_max_version` | Specifies the maximum SSL/TLS version ("ssl3", "tls1.0", "tls1.1" or "tls1.2"). +| `tls_min_version` | Specifies the minimum SSL/TLS version ("ssl3", "tls1.0", "tls1.1" or "tls1.2"). +| `use_http2` | Enable HTTP2 support. +| **gitlab_pages['env'][]** | | +| `http_proxy` | Configure GitLab Pages to use an HTTP Proxy to mediate traffic between Pages and GitLab. Sets an environment variable `http_proxy` when starting Pages daemon. +| **gitlab_rails[]** | | +| `pages_domain_verification_cron_worker` | Schedule for verifying custom GitLab Pages domains. +| `pages_domain_ssl_renewal_cron_worker` | Schedule for obtaining and renewing SSL certificates through Let's Encrypt for GitLab Pages domains. +| `pages_domain_removal_cron_worker` | Schedule for removing unverified custom GitLab Pages domains. +| `pages_path` | The directory on disk where pages are stored, defaults to `GITLAB-RAILS/shared/pages`. +| **pages_nginx[]** | | +| `enable` | Include a virtual host `server{}` block for Pages inside NGINX. Needed for NGINX to proxy traffic back to the Pages daemon. Set to `false` if the Pages daemon should directly receive all requests, for example, when using [custom domains](index.md#custom-domains). + +--- + ## Advanced configuration In addition to the wildcard domains, you can also have the option to configure @@ -261,7 +323,7 @@ This setting is enabled by default. ### Let's Encrypt integration -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/28996) in GitLab 12.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28996) in GitLab 12.1. [GitLab Pages' Let's Encrypt integration](../../user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md) allows users to add Let's Encrypt SSL certificates for GitLab Pages @@ -278,7 +340,7 @@ To enable it, you'll need to: ### Access control -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/33422) in GitLab 11.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/33422) in GitLab 11.5. 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. @@ -305,9 +367,13 @@ Pages access control is disabled by default. To enable it: 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). 1. Users can now configure it in their [projects' settings](../../user/project/pages/pages_access_control.md). +NOTE: **Important:** +For multi-node setups, in order for this setting to be effective, it has to be applied +to all the App nodes as well as the Sidekiq nodes. + #### Disabling public access to all Pages websites -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/32095) in GitLab 12.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32095) in GitLab 12.7. You can enforce [Access Control](#access-control) for all GitLab Pages websites hosted on your GitLab instance. By doing so, only logged-in users will have access to them. @@ -324,7 +390,7 @@ To do that: CAUTION: **Warning:** This action will not make all currently public web-sites private until they redeployed. This issue among others will be resolved by -[changing GitLab Pages configuration mechanism](https://gitlab.com/gitlab-org/gitlab-pages/issues/282). +[changing GitLab Pages configuration mechanism](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/282). ### Running behind a proxy @@ -335,7 +401,7 @@ pages: 1. Configure in `/etc/gitlab/gitlab.rb`: ```ruby - gitlab_pages['http_proxy'] = 'http://example:8080' + gitlab_pages['env']['http_proxy'] = 'http://example:8080' ``` 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. @@ -353,7 +419,7 @@ For installation from source this can be fixed by installing the custom Certific Authority (CA) in the system certificate store. For Omnibus, normally this would be fixed by [installing a custom CA in Omnibus GitLab](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates) -but a [bug](https://gitlab.com/gitlab-org/gitlab/issues/25411) is currently preventing +but a [bug](https://gitlab.com/gitlab-org/gitlab/-/issues/25411) is currently preventing that method from working. Use the following workaround: 1. Append your GitLab server TLS/SSL certificate to `/opt/gitlab/embedded/ssl/certs/cacert.pem` where `gitlab-domain-example.com` is your GitLab application URL @@ -435,7 +501,7 @@ The default is 100MB. ### Override maximum pages size per project or group **(PREMIUM ONLY)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/16610) in GitLab 12.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16610) in GitLab 12.7. To override the global maximum pages size for a specific project: |