From 37a78091711e977370822af6206706c7d7731a43 Mon Sep 17 00:00:00 2001 From: ngala Date: Fri, 17 Nov 2023 23:12:36 +0530 Subject: [PATCH 01/12] Docs: Support for namespace in path for pages Related to: https://gitlab.com/gitlab-org/gitlab/-/issues/17584 Changelog: other --- doc/administration/pages/index.md | 92 ++++++++++++++++++++++++++++++- 1 file changed, 91 insertions(+), 1 deletion(-) diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 3e81d8219c1b8b..d5ac96c627cc67 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -93,6 +93,26 @@ Where `example.io` is the domain GitLab Pages is served from, `192.0.2.1` is the IPv4 address of your GitLab instance, and `2001:db8::1` is the IPv6 address. If you don't have IPv6, you can omit the `AAAA` record. +#### (Experimental) DNS configuration for namespace in URL path (without wildcard DNS) + +If support for namespace in the URL path is needed to remove the requirement for wildcard DNS, +in your DNS server/provider add `[DNS]` and `projects.[DNS]` pointing to the host that GitLab runs. +For example, an entry would look like this: + +```plaintext +example.io 1800 IN A 192.0.2.1 +projects.example.io 1800 IN A 192.0.2.1 +example.io 1800 IN AAAA 2001:db8::1 +projects.example.io 1800 IN AAAA 2001:db8::1 +``` + +Where `example.io` is the domain GitLab Pages is served from, +`192.0.2.1` is the IPv4 address of your GitLab instance, and `2001:db8::1` is the +IPv6 address. If you don't have IPv6, you can omit the `AAAA` record. + +NOTE: +This will be disabled in GitLab SaaS. + #### DNS configuration for custom domains If support for custom domains is needed, all subdomains of the Pages root domain should point to the @@ -149,6 +169,31 @@ The Pages daemon doesn't listen to the outside world. Watch the [video tutorial](https://youtu.be/dD8c7WNcc6s) for this configuration. +### (Experimental) Pages domain (Without wildcard DNS) + +**Requirements:** + +- [Without Wildcard DNS setup](#experimental-dns-configuration-for-namespace-in-url-path-without-wildcard-dns) + +--- + +URL scheme: `http://example.io//` + +The following is the minimum setup that 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. + +1. Set the external URL for GitLab Pages in `/etc/gitlab/gitlab.rb`: + + ```ruby + external_url "http://example.com" # external_url here is only for reference + pages_external_url 'http://example.io' # Important: not a subdomain of external_url, so cannot be http://pages.example.com + + gitlab_pages["namespace_in_path"] = true + ``` + +1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation). + ### Wildcard domains with TLS support **Requirements:** @@ -195,6 +240,50 @@ Before you reconfigure, remove the `gitlab_pages` section from `/etc/gitlab/gitl then run `gitlab-ctl reconfigure`. For more information, read [GitLab Pages does not regenerate OAuth](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/3947). +### (Experimental) Pages domain with TLS support (Without wildcard DNS) + +**Requirements:** + +- [Without wildcard DNS setup](#experimental-dns-configuration-for-namespace-in-url-path-without-wildcard-dns) +- Single TLS certificate for `[DNS]` and `projects.[DNS]`. For example, TLS certificate for `example.io` and `projects.example.io` + +--- + +URL scheme: `https://example.io//` + +NGINX proxies all requests to the daemon. Pages daemon doesn't listen to the +outside world. + +1. Place the wildcard LTS certificate for `*.example.io` and the key inside `/etc/gitlab/ssl`. +1. In `/etc/gitlab/gitlab.rb` specify the following configuration: + + ```ruby + external_url "https://example.com" # external_url here is only for reference + pages_external_url 'https://example.io' # Important: not a subdomain of external_url, so cannot be https://pages.example.com + + pages_nginx['redirect_http_to_https'] = true + gitlab_pages["namespace_in_path"] = true + ``` + +1. If you haven't named your certificate and key `example.io.crt` and `example.io.key`, + you must also add the full paths as shown below: + + ```ruby + pages_nginx['ssl_certificate'] = "/etc/gitlab/ssl/pages-nginx.crt" + pages_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/pages-nginx.key" + ``` + +1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation). +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#create-an-instance-wide-application) + to use the HTTPS protocol. + +WARNING: +GitLab Pages does not update the OAuth application if changes are made to the redirect URI. +Before you reconfigure, remove the `gitlab_pages` section from `/etc/gitlab/gitlab-secrets.json`, +then run `gitlab-ctl reconfigure`. For more information, read +[GitLab Pages does not regenerate OAuth](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/3947). + ### Wildcard domains with TLS-terminating Load Balancer **Requirements:** @@ -292,7 +381,7 @@ control over how the Pages daemon runs and serves content in your environment. | `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). | -| `FF_CONFIGURABLE_ROOT_DIR` | Feature flag to [customize the default folder](../../user/project/pages/introduction.md#customize-the-default-folder) (enabled by default). | +| `FF_CONFIGURABLE_ROOT_DIR` | Feature flag to [customize the default folder](../../user/project/pages/introduction.md#customize-the-default-folder) (enabled by default). | | `FF_ENABLE_PLACEHOLDERS` | Feature flag for rewrites (enabled by default). See [Rewrites](../../user/project/pages/redirects.md#rewrites) for more information. | | `use_legacy_storage` | Temporarily-introduced parameter allowing to use legacy domain configuration source and storage. [Removed in 14.3](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/6166). | | `rate_limit_source_ip` | Rate limit per source IP in number of requests per second. Set to `0` to disable this feature. | @@ -307,6 +396,7 @@ control over how the Pages daemon runs and serves content in your environment. | `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` | | `server_keep_alive` | The `Keep-Alive` period for network connections accepted by this listener. If `0`, `Keep-Alive` is enabled if supported by the protocol and operating system. If negative, `Keep-Alive` is disabled. Default: `15s` | +| `namespace_in_path` | (Experimental) Enable or disable namespace in the URL path. This requires `pages_nginx[enable] = true`. Sets `rewrite` configuration in NGINX to support [without wildcard DNS setup](#experimental-dns-configuration-for-namespace-in-url-path-without-wildcard-dns). Default: `false` | ## Advanced configuration -- GitLab From 1ac1a0c8a56496ea9286409a20fc993a5d8d37ca Mon Sep 17 00:00:00 2001 From: ngala Date: Wed, 22 Nov 2023 21:56:43 +0530 Subject: [PATCH 02/12] Address review comment --- doc/administration/pages/index.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index d5ac96c627cc67..c4b84ab41e6e51 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -96,7 +96,7 @@ IPv6 address. If you don't have IPv6, you can omit the `AAAA` record. #### (Experimental) DNS configuration for namespace in URL path (without wildcard DNS) If support for namespace in the URL path is needed to remove the requirement for wildcard DNS, -in your DNS server/provider add `[DNS]` and `projects.[DNS]` pointing to the host that GitLab runs. +in your DNS server/provider add `[DNS]` and `projects.[DNS]` pointing to the host that GitLab Pages runs. For example, an entry would look like this: ```plaintext @@ -111,7 +111,7 @@ Where `example.io` is the domain GitLab Pages is served from, IPv6 address. If you don't have IPv6, you can omit the `AAAA` record. NOTE: -This will be disabled in GitLab SaaS. +This is not supported in GitLab SaaS. #### DNS configuration for custom domains @@ -187,8 +187,9 @@ The Pages daemon doesn't listen to the outside world. ```ruby external_url "http://example.com" # external_url here is only for reference - pages_external_url 'http://example.io' # Important: not a subdomain of external_url, so cannot be http://pages.example.com + pages_external_url 'http://example.io' + pages_nginx['enable'] = true gitlab_pages["namespace_in_path"] = true ``` @@ -259,8 +260,9 @@ outside world. ```ruby external_url "https://example.com" # external_url here is only for reference - pages_external_url 'https://example.io' # Important: not a subdomain of external_url, so cannot be https://pages.example.com + pages_external_url 'https://example.io' + pages_nginx['enable'] = true pages_nginx['redirect_http_to_https'] = true gitlab_pages["namespace_in_path"] = true ``` -- GitLab From 4b3a68e00ad3bf28ee04e4342b64ada123931a59 Mon Sep 17 00:00:00 2001 From: ngala Date: Fri, 24 Nov 2023 12:38:54 +0530 Subject: [PATCH 03/12] Add warning for Linux package installation feature only --- doc/administration/pages/index.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index c4b84ab41e6e51..6fd989de8111cb 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -110,8 +110,12 @@ Where `example.io` is the domain GitLab Pages is served from, `192.0.2.1` is the IPv4 address of your GitLab instance, and `2001:db8::1` is the IPv6 address. If you don't have IPv6, you can omit the `AAAA` record. +WARNING: +Namespace in the URL path feature is in experiment and not Generally Available (GA). +Also the feature only works in a Linux package installation for now. + NOTE: -This is not supported in GitLab SaaS. +Namespace in the URL path is not supported in GitLab SaaS. #### DNS configuration for custom domains @@ -195,6 +199,10 @@ The Pages daemon doesn't listen to the outside world. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation). +WARNING: +Without wildcard DNS feature is in experiment and not Generally Available (GA). +Also the feature only works in a Linux package installation for now. + ### Wildcard domains with TLS support **Requirements:** @@ -280,6 +288,10 @@ outside world. [System OAuth application](../../integration/oauth_provider.md#create-an-instance-wide-application) to use the HTTPS protocol. +WARNING: +Without wildcard DNS feature is in experiment and not Generally Available (GA). +Also the feature only works in a Linux package installation for now. + WARNING: GitLab Pages does not update the OAuth application if changes are made to the redirect URI. Before you reconfigure, remove the `gitlab_pages` section from `/etc/gitlab/gitlab-secrets.json`, -- GitLab From d53f313e1c2d81a502c4bff2c205f4e5786bbbbf Mon Sep 17 00:00:00 2001 From: ngala Date: Thu, 30 Nov 2023 22:51:50 +0530 Subject: [PATCH 04/12] Add a note for custom proxy header --- doc/administration/pages/index.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 6fd989de8111cb..bf4e8566d5e3db 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -199,6 +199,10 @@ The Pages daemon doesn't listen to the outside world. 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation). +NOTE: +Without wildcard DNS feature, use the custom proxy header `X-Gitlab-Namespace-In-Path` +at the NGINX level to send the namespace to the Pages daemon. + WARNING: Without wildcard DNS feature is in experiment and not Generally Available (GA). Also the feature only works in a Linux package installation for now. @@ -288,6 +292,10 @@ outside world. [System OAuth application](../../integration/oauth_provider.md#create-an-instance-wide-application) to use the HTTPS protocol. +NOTE: +Without wildcard DNS feature, use the custom proxy header `X-Gitlab-Namespace-In-Path` +at the NGINX level to send the namespace to the Pages daemon. + WARNING: Without wildcard DNS feature is in experiment and not Generally Available (GA). Also the feature only works in a Linux package installation for now. -- GitLab From 0c93592111a2dfc2cd1e29bc99c9a6026687583e Mon Sep 17 00:00:00 2001 From: Amy Qualls Date: Fri, 1 Dec 2023 11:56:42 -0800 Subject: [PATCH 05/12] Polish first section to meet standards Rewrite to bring up to GitLab style standards. Declare the experiment status, add a version-history line, change to ordered-list format, add prerequisite, explain examples more fully. --- doc/administration/pages/index.md | 45 ++++++++++++++++++------------- 1 file changed, 27 insertions(+), 18 deletions(-) diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index bf4e8566d5e3db..5025e3e9e7ae9d 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -93,29 +93,38 @@ Where `example.io` is the domain GitLab Pages is served from, `192.0.2.1` is the IPv4 address of your GitLab instance, and `2001:db8::1` is the IPv6 address. If you don't have IPv6, you can omit the `AAAA` record. -#### (Experimental) DNS configuration for namespace in URL path (without wildcard DNS) +#### For namespace in URL path, without wildcard DNS **(EXPERIMENT)** -If support for namespace in the URL path is needed to remove the requirement for wildcard DNS, -in your DNS server/provider add `[DNS]` and `projects.[DNS]` pointing to the host that GitLab Pages runs. -For example, an entry would look like this: +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17584) in GitLab 16.7. This feature is an [Experiment](../../policy/experiment-beta-support.md). -```plaintext -example.io 1800 IN A 192.0.2.1 -projects.example.io 1800 IN A 192.0.2.1 -example.io 1800 IN AAAA 2001:db8::1 -projects.example.io 1800 IN AAAA 2001:db8::1 -``` +FLAG: +On self-managed GitLab, by default this feature is available. +On GitLab.com, this feature is not available. +This feature is not ready for production use. -Where `example.io` is the domain GitLab Pages is served from, -`192.0.2.1` is the IPv4 address of your GitLab instance, and `2001:db8::1` is the -IPv6 address. If you don't have IPv6, you can omit the `AAAA` record. +Prerequisites: -WARNING: -Namespace in the URL path feature is in experiment and not Generally Available (GA). -Also the feature only works in a Linux package installation for now. +- Your instance must use the Linux package installation method. -NOTE: -Namespace in the URL path is not supported in GitLab SaaS. +If you need support for namespace in the URL path to remove the requirement for wildcard DNS: + +1. In your DNS provider, add entries for `example.com` and `projects.example.com`. + In both lines, replace `example.com` with your domain name, and `192.0.0.0` with + the IPv4 version of your IP address. The entries look like this: + + ```plaintext + example.com 1800 IN A 192.0.0.0 + projects.example.com 1800 IN A 192.0.0.0 + ``` + +1. Optional. If your GitLab instance has an IPv6 address, add entries for it. + In both lines, replace `example.com` with your domain name, and `2001:db8::1` with + the IPv6 version of your IP address. The entries look like this: + + ```plaintext + example.com 1800 IN AAAA 2001:db8::1 + projects.example.com 1800 IN AAAA 2001:db8::1 + ``` #### DNS configuration for custom domains -- GitLab From fd27a1e2e0fd88a15b01545d563304c866dc2909 Mon Sep 17 00:00:00 2001 From: Amy Qualls Date: Fri, 1 Dec 2023 12:18:12 -0800 Subject: [PATCH 06/12] Update second section for GitLab style Bring this second section in line with GitLab style. Essentially a full rewrite to use proper version history, availability flagging, prerequisites, and steps. --- doc/administration/pages/index.md | 36 ++++++++++++++++--------------- 1 file changed, 19 insertions(+), 17 deletions(-) diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 5025e3e9e7ae9d..10e039ecdf7b10 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -182,24 +182,30 @@ The Pages daemon doesn't listen to the outside world. Watch the [video tutorial](https://youtu.be/dD8c7WNcc6s) for this configuration. -### (Experimental) Pages domain (Without wildcard DNS) +### Pages domain without wildcard DNS **(EXPERIMENT)** -**Requirements:** +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17584) in GitLab 16.7. This feature is an [Experiment](../../policy/experiment-beta-support.md). -- [Without Wildcard DNS setup](#experimental-dns-configuration-for-namespace-in-url-path-without-wildcard-dns) +FLAG: +On self-managed GitLab, by default this feature is available. +On GitLab.com, this feature is not available. +This feature is not ready for production use. ---- +This configuration is the minimum setup for GitLab Pages. It is the base for all +other configurations. In this configuration, NGINX proxies all requests to the daemon, +because the GitLab Pages daemon doesn't listen to the outside world. -URL scheme: `http://example.io//` +Prerequisites: -The following is the minimum setup that 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. +- Your instance must use the Linux package installation method. +- You have configured DNS setup + [without a wildcard](#for-namespace-in-url-path-without-wildcard-dns). -1. Set the external URL for GitLab Pages in `/etc/gitlab/gitlab.rb`: +1. In `/etc/gitlab/gitlab.rb`, set the external URL for GitLab Pages: ```ruby - external_url "http://example.com" # external_url here is only for reference + # External_url here is only for reference + external_url "http://example.com" pages_external_url 'http://example.io' pages_nginx['enable'] = true @@ -207,14 +213,10 @@ The Pages daemon doesn't listen to the outside world. ``` 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation). +1. Use the custom proxy header `X-Gitlab-Namespace-In-Path` in NGINX + to send the namespace to the Pages daemon. -NOTE: -Without wildcard DNS feature, use the custom proxy header `X-Gitlab-Namespace-In-Path` -at the NGINX level to send the namespace to the Pages daemon. - -WARNING: -Without wildcard DNS feature is in experiment and not Generally Available (GA). -Also the feature only works in a Linux package installation for now. +The resulting URL scheme is `http://example.io//`. ### Wildcard domains with TLS support -- GitLab From fa5efced696486e2f8f563b5bef4b14e50dc2974 Mon Sep 17 00:00:00 2001 From: Amy Qualls Date: Fri, 1 Dec 2023 13:10:08 -0800 Subject: [PATCH 07/12] Polish last section Bring the last new section up to spec. Version history, prerequisites, flag, ordered list items, lots of rewriting. Here's hoping all the links work. --- doc/administration/pages/index.md | 57 +++++++++++++++++-------------- 1 file changed, 32 insertions(+), 25 deletions(-) diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 10e039ecdf7b10..d8305cc5d5ff46 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -264,25 +264,32 @@ Before you reconfigure, remove the `gitlab_pages` section from `/etc/gitlab/gitl then run `gitlab-ctl reconfigure`. For more information, read [GitLab Pages does not regenerate OAuth](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/3947). -### (Experimental) Pages domain with TLS support (Without wildcard DNS) +### Pages domain with TLS support, without wildcard DNS **(EXPERIMENT)** -**Requirements:** +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17584) in GitLab 16.7. This feature is an [Experiment](../../policy/experiment-beta-support.md). -- [Without wildcard DNS setup](#experimental-dns-configuration-for-namespace-in-url-path-without-wildcard-dns) -- Single TLS certificate for `[DNS]` and `projects.[DNS]`. For example, TLS certificate for `example.io` and `projects.example.io` +FLAG: +On self-managed GitLab, by default this feature is available. +On GitLab.com, this feature is not available. +This feature is not ready for production use. ---- +Prerequisites: -URL scheme: `https://example.io//` +- Your instance must use the Linux package installation method. +- You have configured DNS setup + [without a wildcard](#for-namespace-in-url-path-without-wildcard-dns). +- You have a single TLS certificate that covers your domain (like `example.com`) + and the `projects.*` version of your domain, like `projects.example.com`. -NGINX proxies all requests to the daemon. Pages daemon doesn't listen to the -outside world. +In this configuration, NGINX proxies all requests to the daemon. The GitLab Pages +daemon doesn't listen to the outside world: -1. Place the wildcard LTS certificate for `*.example.io` and the key inside `/etc/gitlab/ssl`. -1. In `/etc/gitlab/gitlab.rb` specify the following configuration: +1. Add your wildcard LTS certificate and key for `*.example.io` into `/etc/gitlab/ssl`. +1. In `/etc/gitlab/gitlab.rb`, specify the following configuration: ```ruby - external_url "https://example.com" # external_url here is only for reference + # The external_url field is here only for reference. + external_url "https://example.com" pages_external_url 'https://example.io' pages_nginx['enable'] = true @@ -290,8 +297,9 @@ outside world. gitlab_pages["namespace_in_path"] = true ``` -1. If you haven't named your certificate and key `example.io.crt` and `example.io.key`, - you must also add the full paths as shown below: +1. If your TLS certificate and key don't match the name of your domain, like + `example.io.crt` and `example.io.key`, + add the full paths for the certificate and key files to `/etc/gitlab/gitlab.rb`: ```ruby pages_nginx['ssl_certificate'] = "/etc/gitlab/ssl/pages-nginx.crt" @@ -299,23 +307,22 @@ outside world. ``` 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation). + + WARNING: + GitLab Pages does not update the OAuth application if changes are made to the redirect URI. + Before you reconfigure, remove the `gitlab_pages` section from `/etc/gitlab/gitlab-secrets.json`, + then run `gitlab-ctl reconfigure`. For more information, see + [GitLab Pages does not regenerate OAuth](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/3947). + 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#create-an-instance-wide-application) to use the HTTPS protocol. +1. Use the custom proxy header `X-Gitlab-Namespace-In-Path` in NGINX + to send the namespace to the Pages daemon. -NOTE: -Without wildcard DNS feature, use the custom proxy header `X-Gitlab-Namespace-In-Path` -at the NGINX level to send the namespace to the Pages daemon. +The resulting URL scheme is `https://example.io//`. -WARNING: -Without wildcard DNS feature is in experiment and not Generally Available (GA). -Also the feature only works in a Linux package installation for now. -WARNING: -GitLab Pages does not update the OAuth application if changes are made to the redirect URI. -Before you reconfigure, remove the `gitlab_pages` section from `/etc/gitlab/gitlab-secrets.json`, -then run `gitlab-ctl reconfigure`. For more information, read -[GitLab Pages does not regenerate OAuth](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/3947). ### Wildcard domains with TLS-terminating Load Balancer @@ -429,7 +436,7 @@ control over how the Pages daemon runs and serves content in your environment. | `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` | | `server_keep_alive` | The `Keep-Alive` period for network connections accepted by this listener. If `0`, `Keep-Alive` is enabled if supported by the protocol and operating system. If negative, `Keep-Alive` is disabled. Default: `15s` | -| `namespace_in_path` | (Experimental) Enable or disable namespace in the URL path. This requires `pages_nginx[enable] = true`. Sets `rewrite` configuration in NGINX to support [without wildcard DNS setup](#experimental-dns-configuration-for-namespace-in-url-path-without-wildcard-dns). Default: `false` | +| `namespace_in_path` | (Experimental) Enable or disable namespace in the URL path. This requires `pages_nginx[enable] = true`. Sets `rewrite` configuration in NGINX to support [without wildcard DNS setup](#for-namespace-in-url-path-without-wildcard-dns). Default: `false` | ## Advanced configuration -- GitLab From 24f004bd5f1092dafa99d53e8f4b1244d6ed2e06 Mon Sep 17 00:00:00 2001 From: Amy Qualls Date: Fri, 1 Dec 2023 13:11:36 -0800 Subject: [PATCH 08/12] Move table row to alphabetical order Now that the previous edit to the line has been committed, let's put this line in alphabetical orders with the others. Fix extra blank lines as well. --- doc/administration/pages/index.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index d8305cc5d5ff46..62c45f833fbef6 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -322,8 +322,6 @@ daemon doesn't listen to the outside world: The resulting URL scheme is `https://example.io//`. - - ### Wildcard domains with TLS-terminating Load Balancer **Requirements:** @@ -397,6 +395,7 @@ control over how the Pages daemon runs and serves content in your environment. | `log_directory` | Absolute path to a log directory. | | `log_format` | The log output format: `text` or `json`. | | `log_verbose` | Verbose logging, true/false. | +| `namespace_in_path` | (Experimental) Enable or disable namespace in the URL path. This requires `pages_nginx[enable] = true`. Sets `rewrite` configuration in NGINX to support [without wildcard DNS setup](#for-namespace-in-url-path-without-wildcard-dns). Default: `false` | | `propagate_correlation_id` | Set to true (false by default) to re-use existing Correlation ID from the incoming request header `X-Request-ID` if present. If a reverse proxy sets this header, the value is propagated in the request chain. | | `max_connections` | Limit on the number of concurrent connections to the HTTP, HTTPS or proxy listeners. | | `max_uri_length` | The maximum length of URIs accepted by GitLab Pages. Set to 0 for unlimited length. [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5729) in GitLab 14.5. @@ -436,7 +435,6 @@ control over how the Pages daemon runs and serves content in your environment. | `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` | | `server_keep_alive` | The `Keep-Alive` period for network connections accepted by this listener. If `0`, `Keep-Alive` is enabled if supported by the protocol and operating system. If negative, `Keep-Alive` is disabled. Default: `15s` | -| `namespace_in_path` | (Experimental) Enable or disable namespace in the URL path. This requires `pages_nginx[enable] = true`. Sets `rewrite` configuration in NGINX to support [without wildcard DNS setup](#for-namespace-in-url-path-without-wildcard-dns). Default: `false` | ## Advanced configuration -- GitLab From ce041ccca0fc63086fc9b7437ce625d5cbc66989 Mon Sep 17 00:00:00 2001 From: Amy Qualls Date: Wed, 6 Dec 2023 10:13:24 -0800 Subject: [PATCH 09/12] Take info about NGINX header out of steps This line is informational only, and not something that users must do, so it shouldn't be a numbered step. --- doc/administration/pages/index.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 62c45f833fbef6..8b165ecbc754ed 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -213,8 +213,9 @@ Prerequisites: ``` 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation). -1. Use the custom proxy header `X-Gitlab-Namespace-In-Path` in NGINX - to send the namespace to the Pages daemon. + +NGINX uses the custom proxy header `X-Gitlab-Namespace-In-Path` +to send the namespace to the GitLab Pages daemon. The resulting URL scheme is `http://example.io//`. @@ -317,8 +318,9 @@ daemon doesn't listen to the outside world: 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#create-an-instance-wide-application) to use the HTTPS protocol. -1. Use the custom proxy header `X-Gitlab-Namespace-In-Path` in NGINX - to send the namespace to the Pages daemon. + +NGINX uses the custom proxy header `X-Gitlab-Namespace-In-Path` +to send the namespace to the GitLab Pages daemon. The resulting URL scheme is `https://example.io//`. -- GitLab From 0b97d386208fe6818139acc1f92d989a120bbd8c Mon Sep 17 00:00:00 2001 From: Amy Qualls Date: Wed, 6 Dec 2023 10:44:52 -0800 Subject: [PATCH 10/12] Address the GitLab Pages flag problem These aren't standard feature flags, as GitLab knows them. They are configuration options, and they use the same name. I've built the line into the instructions; hopefully that will be enough? These instructions do not match our FLAG language. --- doc/administration/pages/index.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 8b165ecbc754ed..2cda56d91afd59 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -108,6 +108,9 @@ Prerequisites: If you need support for namespace in the URL path to remove the requirement for wildcard DNS: +1. Enable the GitLab Pages flag for this feature by adding + `gitlab_pages["namespace_in_path"] = true` to `gitlab.rb`. For more information, + see [Use environment variables](#use-environment-variables). 1. In your DNS provider, add entries for `example.com` and `projects.example.com`. In both lines, replace `example.com` with your domain name, and `192.0.0.0` with the IPv4 version of your IP address. The entries look like this: @@ -201,6 +204,9 @@ Prerequisites: - You have configured DNS setup [without a wildcard](#for-namespace-in-url-path-without-wildcard-dns). +1. Enable the GitLab Pages flag for this feature by adding + `gitlab_pages["namespace_in_path"] = true` to `gitlab.rb`. For more information, + see [Use environment variables](#use-environment-variables). 1. In `/etc/gitlab/gitlab.rb`, set the external URL for GitLab Pages: ```ruby @@ -285,6 +291,9 @@ Prerequisites: In this configuration, NGINX proxies all requests to the daemon. The GitLab Pages daemon doesn't listen to the outside world: +1. Enable the GitLab Pages flag for this feature by adding + `gitlab_pages["namespace_in_path"] = true` to `gitlab.rb`. For more information, + see [Use environment variables](#use-environment-variables). 1. Add your wildcard LTS certificate and key for `*.example.io` into `/etc/gitlab/ssl`. 1. In `/etc/gitlab/gitlab.rb`, specify the following configuration: -- GitLab From 95cce6b945d23b87c0d7395dc03e3b5a4848f753 Mon Sep 17 00:00:00 2001 From: ngala Date: Thu, 7 Dec 2023 12:52:36 +0530 Subject: [PATCH 11/12] Update wildcard with TLS certificate --- doc/administration/pages/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 2cda56d91afd59..7f956dbbcff115 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -239,7 +239,7 @@ URL scheme: `https://.example.io/` NGINX proxies all requests to the daemon. Pages daemon doesn't listen to the outside world. -1. Place the wildcard LTS certificate for `*.example.io` and the key inside `/etc/gitlab/ssl`. +1. Place the wildcard TLS certificate for `*.example.io` and the key inside `/etc/gitlab/ssl`. 1. In `/etc/gitlab/gitlab.rb` specify the following configuration: ```ruby @@ -294,7 +294,7 @@ daemon doesn't listen to the outside world: 1. Enable the GitLab Pages flag for this feature by adding `gitlab_pages["namespace_in_path"] = true` to `gitlab.rb`. For more information, see [Use environment variables](#use-environment-variables). -1. Add your wildcard LTS certificate and key for `*.example.io` into `/etc/gitlab/ssl`. +1. Add your TLS certificate and key as mentioned in the prerequisites into `/etc/gitlab/ssl`. 1. In `/etc/gitlab/gitlab.rb`, specify the following configuration: ```ruby -- GitLab From 0b5e8282845ad265e83481740415bd9ac873e1ba Mon Sep 17 00:00:00 2001 From: Amy Qualls Date: Thu, 7 Dec 2023 19:35:27 +0000 Subject: [PATCH 12/12] Improve two lists on the page Fix a redundant step in each list. Add comments to the code to make clearer what line enables the feature flag. --- doc/administration/pages/index.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 7f956dbbcff115..15f34416cb6413 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -204,10 +204,8 @@ Prerequisites: - You have configured DNS setup [without a wildcard](#for-namespace-in-url-path-without-wildcard-dns). -1. Enable the GitLab Pages flag for this feature by adding - `gitlab_pages["namespace_in_path"] = true` to `gitlab.rb`. For more information, - see [Use environment variables](#use-environment-variables). -1. In `/etc/gitlab/gitlab.rb`, set the external URL for GitLab Pages: +1. In `/etc/gitlab/gitlab.rb`, set the external URL for GitLab Pages, and enable + the feature flag: ```ruby # External_url here is only for reference @@ -215,6 +213,9 @@ Prerequisites: pages_external_url 'http://example.io' pages_nginx['enable'] = true + + # Set this feature flag to enable this feature + # For more information, see https://docs.gitlab.com/ee/administration/pages/index.html#use-environment-variables gitlab_pages["namespace_in_path"] = true ``` @@ -291,11 +292,9 @@ Prerequisites: In this configuration, NGINX proxies all requests to the daemon. The GitLab Pages daemon doesn't listen to the outside world: -1. Enable the GitLab Pages flag for this feature by adding - `gitlab_pages["namespace_in_path"] = true` to `gitlab.rb`. For more information, - see [Use environment variables](#use-environment-variables). 1. Add your TLS certificate and key as mentioned in the prerequisites into `/etc/gitlab/ssl`. -1. In `/etc/gitlab/gitlab.rb`, specify the following configuration: +1. In `/etc/gitlab/gitlab.rb`, set the external URL for GitLab Pages, and enable + the feature flag: ```ruby # The external_url field is here only for reference. @@ -304,6 +303,9 @@ daemon doesn't listen to the outside world: pages_nginx['enable'] = true pages_nginx['redirect_http_to_https'] = true + + # Set this feature flag to enable this feature + # For more information, see https://docs.gitlab.com/ee/administration/pages/index.html#use-environment-variables gitlab_pages["namespace_in_path"] = true ``` -- GitLab