-
Marcin Sedlak-Jakubowski authoredMarcin Sedlak-Jakubowski authored
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: