Description

Gerrit can be configured to run behind a third-party web server. This allows the other web server to bind to the privileged port 80 (or 443 for SSL), as well as offloads the SSL processing overhead from Java to optimized native C code.

Gerrit Configuration

Ensure '$site_path'/etc/gerrit.config has the property httpd.listenUrl configured to use proxy-http:// or proxy-https:// and a free port number. This may have already been configured if proxy support was enabled during init.

  [httpd]
        listenUrl = proxy-http://127.0.0.1:8081/r/

Apache 2 Configuration

To run Gerrit behind an Apache server we cannot use mod_proxy directly, as Gerrit relies on getting unmodified escaped forward slashes. Depending on the setting of AllowEncodedSlashes, mod_proxy would either decode encoded slashes, or encode them once again. Hence, we resort to using mod_rewrite. To enable the necessary Apache2 modules:

  a2enmod rewrite
  a2enmod ssl          ; # optional, needed for HTTPS / SSL

Configure an Apache VirtualHost to proxy to the Gerrit daemon, setting the RewriteRule line to use the http:// URL configured above. Ensure the path of RewriteRule (the part before $1) and httpd.listenUrl match, or links will redirect to incorrect locations.

Note that this configuration allows to pass encoded characters to the virtual host, which is potentially dangerous. Be sure to read up on this topic and that you understand the risks.

        <VirtualHost *>
          ServerName review.example.com

          AllowEncodedSlashes NoDecode
          RewriteEngine On
          RewriteRule ^/r/(.*) http://localhost:8081/r/$1 [NE,P]
        </VirtualHost>

SSL

To enable Apache to perform the SSL processing, use proxy-https:// in httpd.listenUrl within Gerrit’s configuration file, and enable the SSL engine in the Apache VirtualHost block:

        <VirtualHost *:443>
          SSLEngine on
          SSLCertificateFile    conf/server.crt
          SSLCertificateKeyFile conf/server.key

          ... same as above ...
        </VirtualHost>

See the Apache mod_ssl documentation for more details on how to configure SSL within the server, like controlling how strong of an encryption algorithm is required.

Nginx Configuration

To run Gerrit behind an Nginx server, use a server statement such as this one:

        server {
          listen 80;
          server_name review.example.com;

          location /r/ {
            proxy_pass        http://127.0.0.1:8081;
            proxy_set_header  X-Forwarded-For $remote_addr;
            proxy_set_header  Host $host;
          }
        }

SSL

To enable Nginx to perform the SSL processing, use proxy-https:// in httpd.listenUrl within Gerrit’s configuration file, and enable the SSL engine in the Nginx server statement:

        server {
          listen 443;
          server_name review.example.com;

          ssl  on;
          ssl_certificate      conf/server.crt;
          ssl_certificate_key  conf/server.key;

          ... same as above ...
        }

See the Nginx http ssl module documentation for more details on how to configure SSL within the server, like controlling how strong of an encryption algorithm is required.

Part of Gerrit Code Review