# HG changeset patch
# User Marcin Sedlak-Jakubowski <msedlakjakubowski@gitlab.com>
# Date 1724680725 0
#      Mon Aug 26 13:58:45 2024 +0000
# Node ID ba1f69c9ddc1815a1f1418f6b7239f5f0578a03c
# Parent  7ba9cbe0100f1c6e47097a887adeb44d6ae23ab1
OKR: CTRT edits to NGINX doc, part 1

diff --git a/README.md b/README.md
--- a/README.md
+++ b/README.md
@@ -74,7 +74,7 @@
 
 #### Use non-packaged web-server
 
-For using an existing Nginx, Passenger, or Apache webserver see [doc/settings/nginx.md](doc/settings/nginx.md#using-a-non-bundled-web-server).
+For using an existing Nginx, Passenger, or Apache webserver see [doc/settings/nginx.md](doc/settings/nginx.md#use-a-non-bundled-web-server).
 
 #### Using a non-packaged PostgreSQL database management server
 
diff --git a/doc/settings/configuration.md b/doc/settings/configuration.md
--- a/doc/settings/configuration.md
+++ b/doc/settings/configuration.md
@@ -980,7 +980,7 @@
   - Insert custom NGINX settings into the GitLab server block
   - Insert custom settings into the NGINX configuration
   - Enable `nginx_status`
-- [Use a non-packaged web-server](nginx.md#using-a-non-bundled-web-server)
+- [Use a non-packaged web-server](nginx.md#use-a-non-bundled-web-server)
 - [Use a non-packaged PostgreSQL database management server](database.md)
 - [Use a non-packaged Redis instance](redis.md)
 - [Add `ENV` vars to the GitLab runtime environment](environment-variables.md)
diff --git a/doc/settings/nginx.md b/doc/settings/nginx.md
--- a/doc/settings/nginx.md
+++ b/doc/settings/nginx.md
@@ -10,6 +10,9 @@
 **Tier:** Free, Premium, Ultimate
 **Offering:** Self-managed
 
+This page provides configuration information for administrators and DevOps engineers configuring NGINX for GitLab installations.
+It includes essential instructions for optimizing performance and security specific to bundled NGINX (Linux package), Helm charts, or custom setups.
+
 ## Service-specific NGINX settings
 
 Users can configure NGINX settings differently for different services via
@@ -85,7 +88,7 @@
 
 This way you can specify any header supported by NGINX you require.
 
-## Configuring GitLab `trusted_proxies` and the NGINX `real_ip` module
+## Configure GitLab trusted proxies and NGINX `real_ip` module
 
 By default, NGINX and GitLab will log the IP address of the connected client.
 
@@ -114,7 +117,7 @@
 Save the file and [reconfigure GitLab](https://docs.gitlab.com/ee/administration/restart_gitlab.html#omnibus-gitlab-reconfigure)
 for the changes to take effect.
 
-## Configuring the PROXY protocol
+## Configure the PROXY protocol
 
 If you want to use a proxy like HAProxy in front of GitLab using the [PROXY protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt),
 you need to enable this setting. Do not forget to set the `real_ip_trusted_addresses` also as needed:
@@ -135,7 +138,7 @@
 Once enabled, NGINX only accepts PROXY protocol traffic on these listeners.
 Ensure to also adjust any other environments you might have, like monitoring checks.
 
-## Using a non-bundled web-server
+## Use a non-bundled web server
 
 By default, the Linux package installs GitLab with bundled NGINX.
 Linux package installations allow webserver access through the `gitlab-www` user, which resides
@@ -214,7 +217,12 @@
    - If you use SSL, the location of your SSL keys.
    - The location of your log files.
 
-## Setting the NGINX listen address or addresses
+## NGINX configuration options
+
+GitLab provides various configuration options to customize NGINX behavior for your specific needs.
+Use these reference items to fine-tune your NGINX setup and optimize GitLab performance and security.
+
+### Setting the NGINX listen addresses
 
 By default NGINX will accept incoming connections on all local IPv4 addresses.
 You can change the list of addresses in `/etc/gitlab/gitlab.rb`.
@@ -227,7 +235,7 @@
 pages_nginx['listen_addresses'] = ['*', '[::]']
 ```
 
-## Setting the NGINX listen port
+### Setting the NGINX listen port
 
 By default NGINX will listen on the port specified in `external_url` or
 implicitly use the right port (80 for HTTP, 443 for HTTPS). If you are running
@@ -238,7 +246,7 @@
 nginx['listen_port'] = 8081
 ```
 
-## Verbosity level of NGINX logs
+### Verbosity level of NGINX logs
 
 By default NGINX will log at the `error` verbosity level. You may log at a different level
 by changing the log level. For example, to enable `debug` logging:
@@ -249,7 +257,7 @@
 
 Valid values can be found from the [NGINX documentation](https://nginx.org/en/docs/ngx_core_module.html#error_log).
 
-## Setting the Referrer-Policy header
+### Setting the Referrer-Policy header
 
 By default, GitLab sets the `Referrer-Policy` header to `strict-origin-when-cross-origin` on all responses.
 
@@ -272,7 +280,7 @@
 
 - <https://www.w3.org/TR/referrer-policy/>
 
-## Disabling Gzip compression
+### Disabling Gzip compression
 
 By default, GitLab enables Gzip compression for text data over 10240 bytes. To
 disable this behavior:
@@ -284,7 +292,7 @@
 NOTE:
 The `gzip` setting only works for the main GitLab application and not for the other services.
 
-## Disabling proxy request buffering
+### Disabling proxy request buffering
 
 Request buffering can be disabled selectively on specific locations by changing `request_buffering_off_path_regex`.
 
@@ -302,7 +310,7 @@
    sudo gitlab-ctl hup nginx
    ```
 
-## Configure `robots.txt`
+### Configure `robots.txt`
 
 To configure [`robots.txt`](https://www.robotstxt.org/robotstxt.html) for your instance, specify a custom `robots.txt` file by adding a [custom NGINX configuration](#inserting-custom-nginx-settings-into-the-gitlab-server-block):
 
@@ -318,7 +326,7 @@
    sudo gitlab-ctl reconfigure
    ```
 
-## Inserting custom NGINX settings into the GitLab server block
+### Inserting custom NGINX settings into the GitLab server block
 
 Please keep in mind that these custom settings may create conflicts if the
 same settings are defined in your `gitlab.rb` file.
@@ -337,7 +345,7 @@
 This inserts the defined string into the end of the `server` block of
 `/var/opt/gitlab/nginx/conf/gitlab-http.conf`.
 
-### Notes
+#### Notes
 
 - If you're adding a new location, you might need to include
 
@@ -353,7 +361,7 @@
 - You cannot add the root `/` location or the `/assets` location as those already
   exist in `gitlab-http.conf`.
 
-## Inserting custom settings into the NGINX configuration
+### Inserting custom settings into the NGINX configuration
 
 If you need to add custom settings into the NGINX configuration, for example to include
 existing server blocks, you can use the following setting.
@@ -385,7 +393,7 @@
 Custom NGINX settings inside the `/etc/gitlab/` directory are backed up to `/etc/gitlab/config_backup/`
 during an upgrade and when `sudo gitlab-ctl backup-etc` is manually executed.
 
-## Custom error pages
+### Custom error pages
 
 You can use `custom_error_pages` to modify text on the default GitLab error page.
 This can be used for any valid HTTP error code; e.g 404, 502.
@@ -409,9 +417,9 @@
 Run `gitlab-ctl reconfigure` to rewrite the NGINX configuration and restart
 NGINX.
 
-## Using an existing Passenger/NGINX installation
+### Using an existing Passenger and NGINX installation
 
-In some cases you may want to host GitLab using an existing Passenger/NGINX
+In some cases you may want to host GitLab using an existing Passenger and NGINX
 installation but still have the convenience of updating and installing using
 the Linux packages.
 
@@ -419,7 +427,7 @@
 When disabling NGINX, you won't be able to access other services included in a Linux package installation such as
 Mattermost unless you manually add them in `nginx.conf`.
 
-### Configuration
+#### Configuration
 
 First, you'll need to set up your `/etc/gitlab/gitlab.rb` to disable the built-in
 NGINX and Puma:
@@ -443,7 +451,7 @@
 
 Make sure you run `sudo gitlab-ctl reconfigure` for the changes to take effect.
 
-### Vhost (server block)
+#### Vhost (server block)
 
 In your custom Passenger/NGINX installation, create the following site configuration file:
 
@@ -584,11 +592,11 @@
 
 Then run `sudo service nginx reload`.
 
-## Enabling/Disabling `nginx_status`
+### Enabling and disabling `nginx_status`
 
 By default you will have an NGINX health-check endpoint configured at `127.0.0.1:8060/nginx_status` to monitor your NGINX server status.
 
-### The following information will be displayed
+The following information is displayed:
 
 ```plaintext
 Active connections: 1
@@ -606,7 +614,7 @@
 - Writing: NGINX reads request bodies, processes requests, or writes responses to a client
 - Waiting: Keep-alive connections. This number depends on the keepalive-timeout.
 
-### Configuration options
+#### Configuration options
 
 Edit `/etc/gitlab/gitlab.rb`:
 
@@ -633,7 +641,7 @@
 
 Make sure you run `sudo gitlab-ctl reconfigure` for the changes to take effect.
 
-#### Warning
+##### Configuring user permissions for uploads
 
 To ensure that user uploads are accessible your NGINX user (usually `www-data`)
 should be added to the `gitlab-www` group. This can be done using the following command:
@@ -642,7 +650,7 @@
 sudo usermod -aG gitlab-www www-data
 ```
 
-## Templates
+### Templates
 
 Other than the Passenger configuration in place of Puma and the lack of HTTPS
 (although this could be enabled) these files are mostly identical to: