Skip to content
Snippets Groups Projects
nginx.md 24.32 KiB
stage: Systems
group: Distribution
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

NGINX settings

DETAILS: 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

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

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

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:

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: