GitLab behind an Apache reverse proxy

category: notez · date: 2018-01-01 · author: LALA

noteHistorical technical note from 2018. Environment-specific identifiers and credentials have been anonymized. Commands reflect the technology and operating-system generation used at the time and should be reviewed before reuse on a current system.

Historical note: The Unicorn-specific backend from 2018 is obsolete; this page is for historical understanding.

This note records an older Omnibus GitLab setup where GitLab bundled NGINX was disabled and Apache acted as the external reverse proxy. The historical backend was Unicorn; current GitLab architecture has changed, so the old backend-specific directives must not be copied to a modern installation.

Historical layout

output 7 lines

Client
  |
  v
Apache HTTPS virtual host
  |
  v
GitLab application backend on loopback

Conceptual Apache configuration:

apache

<VirtualHost *:443>
    ServerName gitlab.example.com
    ProxyPreserveHost On
    RequestHeader set X-Forwarded-Proto "https"
    ProxyPass        /gitlab/ http://127.0.0.1:8181/gitlab/
    ProxyPassReverse /gitlab/ http://127.0.0.1:8181/gitlab/
</VirtualHost>

The actual backend endpoint must come from the GitLab version being deployed.

Important modern caveat

Do not use old unicorn[...] configuration on current GitLab. GitLab moved from Unicorn to Puma, and modern Omnibus packages also use GitLab Workhorse in the request path.

For a current deployment, follow the GitLab documentation for external_url, relative URL support, bundled NGINX versus an external web server, trusted proxy/forwarded headers, WebSockets and large uploads. Validate redirects, clone URLs, artifact downloads and API endpoints after changing reverse-proxy behavior.

References

GitLab documentation: https://docs.gitlab.com/
GitLab Omnibus configuration: https://docs.gitlab.com/omnibus/settings/configuration.html
Apache mod_proxy: https://httpd.apache.org/docs/2.4/mod/mod_proxy.html