Documentation/config-reverseproxy.txt

Gerrit Code Review - Reverse Proxy
==================================

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
link:config-gerrit.html#httpd.listenUrl[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.

GERRIT
------
Part of link:index.html[Gerrit Code Review]