diff options
Diffstat (limited to 'doc/administration/pages/index.md')
| -rw-r--r-- | doc/administration/pages/index.md | 131 |
1 files changed, 120 insertions, 11 deletions
diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 058445f00be..d04688dab7a 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -171,7 +171,7 @@ URL scheme: `https://<namespace>.example.io/<project_slug>` NGINX proxies all requests to the daemon. Pages daemon doesn't listen to the outside world. -1. Place the certificate and key inside `/etc/gitlab/ssl` +1. Place the `example.io` certificate and key inside `/etc/gitlab/ssl`. 1. In `/etc/gitlab/gitlab.rb` specify the following configuration: ```ruby @@ -180,7 +180,7 @@ outside world. pages_nginx['redirect_http_to_https'] = true ``` -1. If you haven’t named your certificate and key `example.io.crt` and `example.io.key` +1. If you haven't named your certificate and key `example.io.crt` and `example.io.key` then you'll need to also add the full paths as shown below: ```ruby @@ -189,6 +189,9 @@ then you'll need to also add the full paths as shown below: ``` 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). +1. If you're using [Pages Access Control](#access-control), update the redirect URI in the GitLab Pages +[System OAuth application](../../integration/oauth_provider.md#instance-wide-applications) +to use the HTTPS protocol. WARNING: Multiple wildcards for one instance is not supported. Only one wildcard per instance can be assigned. @@ -303,7 +306,7 @@ 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. Edit `/etc/gitlab/gitlab.rb`: +1. In `/etc/gitlab/gitlab.rb` specify the following configuration: ```ruby pages_external_url "http://example.io" @@ -334,23 +337,35 @@ 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. Edit `/etc/gitlab/gitlab.rb`: +1. Place the `example.io` certificate and key inside `/etc/gitlab/ssl`. +1. In `/etc/gitlab/gitlab.rb` specify the following configuration: ```ruby pages_external_url "https://example.io" nginx['listen_addresses'] = ['192.0.2.1'] pages_nginx['enable'] = false - gitlab_pages['cert'] = "/etc/gitlab/ssl/example.io.crt" - gitlab_pages['cert_key'] = "/etc/gitlab/ssl/example.io.key" gitlab_pages['external_http'] = ['192.0.2.2:80', '[2001:db8::2]:80'] gitlab_pages['external_https'] = ['192.0.2.2:443', '[2001:db8::2]:443'] + # Redirect pages from HTTP to HTTPS + gitlab_pages['redirect_http'] = true ``` where `192.0.2.1` is the primary IP address that GitLab is listening to and `192.0.2.2` and `2001:db8::2` are the secondary IPs where the GitLab Pages daemon listens on. If you don't have IPv6, you can omit the IPv6 address. +1. If you haven't named your certificate and key `example.io.crt` and `example.io.key` respectively, +then you'll need to also add the full paths as shown below: + + ```ruby + gitlab_pages['cert'] = "/etc/gitlab/ssl/example.io.crt" + gitlab_pages['cert_key'] = "/etc/gitlab/ssl/example.io.key" + ``` + 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). +1. If you're using [Pages Access Control](#access-control), update the redirect URI in the GitLab Pages +[System OAuth application](../../integration/oauth_provider.md#instance-wide-applications) +to use the HTTPS protocol. ### Custom domain verification @@ -472,7 +487,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#gitlab-pages-access-control) and -the [online view of HTML job artifacts](../../ci/pipelines/job_artifacts.md#browsing-artifacts) +the [online view of HTML job artifacts](../../ci/pipelines/job_artifacts.md#download-job-artifacts) fails to work if the custom CA is not recognized. This usually results in this error: @@ -600,8 +615,9 @@ the below steps to do a no downtime transfer to a new storage location. ## Configure listener for reverse proxy requests -Follow the steps below to configure the proxy listener of GitLab Pages. [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/2533) in -Omnibus GitLab 11.1. +> [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/2533) in Omnibus GitLab 11.1. + +Follow the steps below to configure the proxy listener of GitLab Pages. 1. By default the listener is configured to listen for requests on `localhost:8090`. @@ -631,6 +647,9 @@ The default is 100MB. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16610) in GitLab 12.7. +NOTE: +Only GitLab admin users will be able to view and override the **Maximum size of Pages** setting. + To override the global maximum pages size for a specific project: 1. Go to your project's **Settings > Pages** page. @@ -752,7 +771,7 @@ The default value for Omnibus installations is `nil`. If left unchanged, GitLab Pages tries to use any available source (either `gitlab` or `disk`). The preferred source is `gitlab`, which uses [API-based configuration](#gitlab-api-based-configuration). -On large GitLab instances, using the API-based configuration will significantly improve the pages daemon startup time, as there is no need to load all custom domains configuration into memory. +On large GitLab instances, using the API-based configuration will significantly improve the pages daemon startup time, as there is no need to load all custom domains configuration into memory. 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/). @@ -815,7 +834,7 @@ or persistent errors, or the Pages Daemon serving old content. NOTE: Expiry, interval and timeout flags use [Golang's duration formatting](https://golang.org/pkg/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". +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". Examples: @@ -919,6 +938,89 @@ In installations from source: 1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect. +## ZIP storage + +In GitLab 14.0 the underlaying storage format of GitLab Pages is changing from +files stored directly in disk to a single ZIP archive per project. + +These ZIP archives can be stored either locally on disk storage or on the [object storage](#using-object-storage) if it is configured. + +[Starting from GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/245308) ZIP archives are stored every time pages site is updated. + +### Migrate legacy storage to ZIP storage + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/59003) in GitLab 13.11. + +GitLab will [try to automatically migrate](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/54578) the old storage format to the new ZIP-based one when you upgrade to GitLab 13.11 or further. +However, some projects may fail to be migrated for different reasons. +To verify that all projects have been migrated successfully, you can manually run the migration: + +```shell +gitlab-rake gitlab:pages:migrate_legacy_storage +``` + +It's safe to interrupt this task and run it multiple times. + +There are two most common problems this task can report: + +- `Missing public directory` error: + + ```txt + E, [2021-04-09T13:11:52.534768 #911919] ERROR -- : project_id: 1 /home/vlad/gdk/gitlab/shared/pages/gitlab-org/gitlab-test failed to be migrated in 0.07 seconds: Archive not created. Missing public directory in /home/vlad/gdk/gitlab/shared/pages/gitlab-org/gitlab-test + ``` + + In this case, you should verify that these projects don't have pages deployed, and re-run the migration with an additional flag to mark those projects as not deployed with GitLab Pages: + + ```shell + sudo PAGES_MIGRATION_MARK_PROJECTS_AS_NOT_DEPLOYED=true gitlab-rake gitlab:pages:migrate_legacy_storage + ``` + +- File `is invalid` error: + + ```txt + E, [2021-04-09T14:43:05.821767 #923322] ERROR -- : project_id: 1 /home/vlad/gdk/gitlab/shared/pages/gitlab-org/gitlab-test failed to be migrated: /home/vlad/gdk/gitlab/shared/pages/gitlab-org/gitlab-test/public/link is invalid, input_dir: /home/vlad/gdk/gitlab/shared/pages/gitlab-org/gitlab-test + ``` + + This error indicates invalid files on disk storage, most commonly symlinks leading outside of the `public` directory. + You can manually remove these files, or just ignore them during migration: + + ```shell + sudo PAGES_MIGRATION_IGNORE_INVALID_ENTRIES=true gitlab-rake gitlab:pages:migrate_legacy_storage + ``` + +### Rolling back ZIP migration + +If you find that migrated data is invalid, you can remove all migrated data by running: + +```shell +sudo gitlab-rake gitlab:pages:clean_migrated_zip_storage +``` + +This will not remove any data from the legacy disk storage and the GitLab Pages daemon will automatically fallback +to using that. + +### Migrate Pages deployments to object storage + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325285) in GitLab 13.11 + +Existing Pages deployments objects (which store [ZIP archives](#zip-storage)) can similarly be +migrated to [object storage](#using-object-storage), if +you've been having them stored locally. + +Migrate your existing Pages deployments from local storage to object storage: + +```shell +sudo gitlab-rails gitlab:pages:deployments:migrate_to_object_storage +``` + +### Rolling Pages deployments back to local storage + +After the migration to object storage is performed, you can choose to revert your Pages deployments back to local storage: + +```shell +sudo gitlab-rails gitlab:pages:deployments:migrate_to_local +``` + ## Backup GitLab Pages are part of the [regular backup](../../raketasks/backup_restore.md), so there is no separate backup to configure. @@ -1096,6 +1198,8 @@ 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`. +1. Configure `pages_external_url http://example.io/` in your `gitlab.rb` file. + Omit the group namespace here, because it will automatically be prepended by GitLab. ### Pages daemon fails with permission denied errors @@ -1114,3 +1218,8 @@ 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 + +Verify that the **Callback URL**/Redirect URI in the GitLab Pages [System OAuth application](../../integration/oauth_provider.md#instance-wide-applications) +is using the protocol (HTTP or HTTPS) that `pages_external_url` is configured to use. |