nginx.md

stage: GitLab Delivery
group: Self Managed
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
title: NGINX settings

{{< details >}}

• Tier: Free, Premium, Ultimate
• Offering: GitLab Self-Managed

{{< /details >}}

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

To configure NGINX settings for different services, edit the gitlab.rb file.

{{< alert type="warning" >}}

Incorrect or incompatible configuration might cause the service to become unavailable.

{{< /alert >}}

Use nginx['<setting>'] keys to configure settings for the GitLab Rails application. GitLab provides similar keys for other services like pages_nginx, mattermost_nginx, and registry_nginx. Configurations for nginx are also available for these <service_nginx> settings, and share the same default values as GitLab NGINX.

To operate NGINX for isolated services like Mattermost, use gitlab_rails['enable'] = false instead of nginx['enable'] = false. For more information, see Running GitLab Mattermost on its own server.

When you modify the gitlab.rb file, configure NGINX settings for each service separately. Settings specified using nginx['foo'] are not replicated to service-specific NGINX configurations (such as registry_nginx['foo'] or mattermost_nginx['foo']). For example, to configure HTTP to HTTPS redirection for GitLab, Mattermost and Registry, add the following settings to gitlab.rb:

nginx['redirect_http_to_https'] = true
registry_nginx['redirect_http_to_https'] = true
mattermost_nginx['redirect_http_to_https'] = true

Enable HTTPS

By default, Linux package installations do not use HTTPS. To enable HTTPS for gitlab.example.com:

• Use Let's Encrypt for free, automated HTTPS.
• Manually configure HTTPS with your own certificates.

If you use a proxy, load balancer, or other external device to terminate SSL for the GitLab host name, see External, proxy, and load balancer SSL termination.

Change the default proxy headers

By default, when you specify external_url, a Linux package installation sets NGINX proxy headers that are suitable for most environments.

For example, if you specify the https schema in the external_url, a Linux package installation sets:

"X-Forwarded-Proto" => "https",
"X-Forwarded-Ssl" => "on"

If your GitLab instance is in a more complex setup, such as behind a reverse proxy, you might need to adjust the proxy headers to avoid errors like:

• The change you wanted was rejected
• Can't verify CSRF token authenticity Completed 422 Unprocessable

To override the default headers:

1. Edit /etc/gitlab/gitlab.rb:

   nginx['proxy_set_headers'] = {
     "X-Forwarded-Proto" => "http",
     "CUSTOM_HEADER" => "VALUE"
   }

2. Save the file and reconfigure GitLab for the changes to take effect.

You can specify any header supported by NGINX.

Configure GitLab trusted proxies and NGINX real_ip module

By default, NGINX and GitLab log the IP address of the connected client.

If GitLab is behind a reverse proxy, you might not want the IP address of the proxy to show as the client address.

To configure NGINX to use a different address, add your reverse proxy to the real_ip_trusted_addresses list:

# Each address is added to the NGINX config as 'set_real_ip_from <address>;'
nginx['real_ip_trusted_addresses'] = [ '192.168.1.0/24', '192.168.2.1', '2001:0db8::/32' ]
# Other real_ip config options
nginx['real_ip_header'] = 'X-Forwarded-For'
nginx['real_ip_recursive'] = 'on'

For a description of these options, see the NGINX realip module documentation.

By default, Linux package installations use the IP addresses in real_ip_trusted_addresses as GitLab trusted proxies. The trusted proxy configuration prevents users from being listed as signed in from those IP addresses.

Save the file and reconfigure GitLab for the changes to take effect.

Configure the PROXY protocol

To use a proxy like HAProxy in front of GitLab with the PROXY protocol:

1. Edit /etc/gitlab/gitlab.rb:

   # Enable termination of ProxyProtocol by NGINX
   nginx['proxy_protocol'] = true
   # Configure trusted upstream proxies. Required if `proxy_protocol` is enabled.
   nginx['real_ip_trusted_addresses'] = [ "127.0.0.0/8", "IP_OF_THE_PROXY/32"]

2. Save the file and reconfigure GitLab for the changes to take effect.

After you enable this setting, NGINX only accepts PROXY protocol traffic on these listeners. Adjust any other environments you might have, such as monitoring checks.

Use a non-bundled web server