Gerrit2 - Installation Guide

Building Gerrit From Source

Alternatively, you can build the application distribution using Maven from a source download obtained directly from Git:

git clone git://android.git.kernel.org/tools/gerrit.git
cd gerrit
mvn clean package
cp target/gerrit-*.war ...YOUR.DEST.../gerrit.war

The first build may take a while as dependencies are searched for and downloaded from Maven distribution repositories.

Apache Maven:

Setting up the Database

PostgreSQL

Create a Gerrit specific user as a normal user (no superuser access) and assign it an encrypted password:

createuser -A -D -P -E gerrit2

Create the database to store the Gerrit metadata, and set the user you just created as the owner of that database:

createdb -E UTF-8 -O gerrit2 reviewdb

MySQL

Create a Gerrit specific user within the database and assign it a password, create a database, and give the user full rights:

CREATE USER 'gerrit2'@'localhost' IDENTIFIED BY 'secret';
CREATE DATABASE reviewdb;
ALTER DATABASE reviewdb charset=latin1;
GRANT ALL ON reviewdb.* TO 'gerrit2'@'localhost';
FLUSH PRIVILEGES;

Initialize the Schema

Create the Gerrit 2 Tables

Either run CreateSchema from the command line:

java -jar gerrit.war --cat extra/GerritServer.properties_example >GerritServer.properties
edit GerritServer.properties

java -jar gerrit.war CreateSchema

Or, run the application once in a container to force it to initialize the database schema before accessing it. (See below for deployment setup documentation.) If you use this approach, it is recommended that you stop the application before continuing with the setup.

Add Indexes

A script should be run to create the query indexes, so Gerrit can avoid table scans when looking up information. Run the index script through your database's query tool.

PostgreSQL:

java -jar gerrit.war --cat sql/index_postgres.sql | psql reviewdb -U gerrit2 -W

MySQL:

java -jar gerrit.war --cat sql/index_generic.sql | mysql reviewdb -u gerrit2 -p
java -jar gerrit.war --cat sql/mysql_nextval.sql | mysql reviewdb -u gerrit2 -p

Configure site_path

This directory holds server-specific configuration files and assets used to customize the deployment. Gerrit needs read access (but not write access) to the directory. The path is stored in system_config.site_path, so you will need to update the database with this value.

mkdir /home/gerrit2/cfg
cd /home/gerrit2/cfg

UPDATE system_config SET site_path='/home/gerrit2/cfg'

When $site_path is referenced below, it refers to the path set in the SQL above.

SSH Host Keys

If you choose to install the Bouncy Castle Crypto APIs (see below) you must create an RSA, DSA, or both, host keys for the daemon:

ssh-keygen -t rsa -P '' -f ssh_host_rsa_key
ssh-keygen -t dsa -P '' -f ssh_host_dsa_key

These keys are used as the host keys for the internal SSH daemon run by Gerrit. You may wish to backup these key files to ensure they can be restored in the event of a disaster.

The private key files (ssh_host_rsa_key, ssh_host_dsa_key) should be readable only by the account that is executing Gerrit2's web application container. It is a security risk to make these files readable by anyone else.

If you don't install Bouncy Castle, Gerrit will automatically create a host key and save a copy to $site_path/ssh_host_key during first startup. For this to work correctly, Gerrit will require write access to the directory.

Create Git Repository Base

This directory holds the Git repositories that Gerrit knows about and can service. Gerrit needs write access to this directory and any Git repository stored within it.

mkdir /srv/git
git config --file '$site_path'/gerrit.config gerrit.basePath /srv/git

You may wish to consider also exporting this directory over the anonymous git:// protocol, as it is more efficient than Gerrit's internal ssh daemon. See the git-daemon documentation for details on how to configure this if anonymous access is desired.

man git-daemon

Futher Configuration

Gerrit2 supports some site-specific customizations. These are optional and are not required to run a server, but may be desired.

Application Deployment

Jetty

Note	The instructions listed here were tested with Jetty 6.1.14 or later. These are known to not work on much older versions, such as 6.1.3.

These directions will configure Gerrit as the default web application, allowing URLs like http://example.com/4543 to jump directly to change 4543.

Download and unzip a release version of Jetty. From here on we call the unpacked directory $JETTY_HOME.

Jetty Downloads

Install the required JDBC drivers by copying them into the $JETTY_HOME/lib/ext directory. Drivers can be obtained from their source projects:

Consider installing Bouncy Castle Cypto APIs into the $JETTY_HOME/lib/ext directory. Some of the Bouncy Castle implementations are faster than then ones that come in the JRE, and they may support additional encryption algorithms:

Bouncy Castle Crypto API

Copy Gerrit into the deployment:

cd $JETTY_HOME
cp ~/gerrit.war webapps/gerrit.war
java -jar webapps/gerrit.war --cat extra/jetty7/gerrit.xml >contexts/gerrit.xml
rm -f contexts/test.xml

Edit $JETTY_HOME/contexts/gerrit.xml to correctly configure the database and outgoing SMTP connections, especially the user and password fields.

If OpenID authentication (or certain enterprise single-sign-on solutions) is being used, you may need to increase the header buffer size parameter, due to very long header lines. Add the following to $JETTY_HOME/etc/jetty.xml under org.eclipse.jetty.server.nio.SelectChannelConnector:

<Set name="headerBufferSize">16384</Set>

To start automatically when the system boots, create a start script and modify it for your configuration:

java -jar gerrit.war --cat extra/jetty7/gerrit-jetty.sh >/etc/init.d/gerrit-jetty.sh
vi /etc/init.d/gerrit-jetty.sh

Tip	Under Jetty, restarting the web application (e.g. after modifying `system_config`) is as simple as touching the context config file: `$JETTY_HOME/contexts/gerrit.xml`

Port 80

To deploy on port 80, you should configure Jetty to listen on another port, such as 127.0.0.1:8081 (like the start script above does) and then follow the reverse proxy section below.

Port 443 (HTTPS / SSL)

To deploy on port 443 with SSL enabled, unpack the SSL proxy handling rule into $JETTY_HOME/etc:

cd $JETTY_HOME
java -jar webapps/gerrit.war --cat extra/jetty7/jetty_sslproxy.xml >etc/jetty_sslproxy.xml

Create a start script like the one above, configuring Jetty to listen on another port, such as 127.0.0.1:8081.

Set gerrit.canonicalWebUrl in $site_path/gerrit.config to an https:// style URL for your application, so that non-SSL connections are automatically upgraded to SSL by issuing a redirect. Gerrit does not currently support a dual http/https usage on the same site as it doesn't know when to upgrade a non-secure connection to a secure one if data needs to be protected.

Follow the reverse proxy section below to setup an Apache2 server to handle SSL for Jetty.

Other Servlet Containers

Deploy the gerrit-*.war file to your application server as gerrit.war.

Configure the JNDI DataSource jdbc/ReviewDb for the Gerrit web application context to point to the database you just created. Don't forget to ensure your JNDI configuration can load the necessary JDBC drivers.

(Optional) Add Bouncy Castle Crypto API to the web application's classpath. Usually its best to load this library from the servlet container's extensions directory, but gerrit.war could also be manually repacked to include it.

Apache2 Reverse Proxy

Enable the necessary Apache2 modules:

a2enmod proxy_http
a2enmod disk_cache   ; # optional, but helps performance

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

then setup a VirtualHost to proxy to Gerrit's servlet container, setting the ProxyPass line to use the port number you configured in your servlet container's configuration:

<VirtualHost *>
  ServerName review.example.com
#
  ProxyRequests Off
  ProxyVia Off
  ProxyPreserveHost On
#
  <Proxy *>
        Order deny,allow
        Allow from all
  </Proxy>
  ProxyPass / http://127.0.0.1:8081/
#
  <IfModule mod_disk_cache.c>
        CacheEnable disk /
        CacheIgnoreHeaders Set-Cookie
  </IfModule>
</VirtualHost>

if you are using SSL with a Jetty container:

<VirtualHost *:443>
  ServerName review.example.com
#
  SSLEngine on
  SSLCertificateFile    conf/server.crt
  SSLCertificateKeyFile conf/server.key
#
  ProxyRequests Off
  ProxyVia Off
  ProxyPreserveHost On
  ProxyPass / http://127.0.0.1:8081/
  RequestHeader set X-Forwarded-Scheme https
#
  <IfModule mod_disk_cache.c>
        CacheEnable disk /
        CacheIgnoreHeaders Set-Cookie
  </IfModule>
</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.

For Gerrit, the only difference between plain HTTP and HTTPS is adding the "RequestHeader set X-Forwarded-Scheme https" line within the SSL enabled virtual host.

Administrator Setup

Add your newly created account to the "Administrators" group, so that you can manage the site through the web interface:

INSERT INTO account_group_members
  (account_id, group_id)
VALUES (
  (SELECT account_id FROM accounts
   WHERE preferred_email='you@example.com'),
  (SELECT admin_group_id FROM system_config)
);

You can also get your account_id from the web UI, under Settings, if you don't want to use a SELECT subquery above, or your email address wasn't prefilled automatically.

Group memberships are cached, so you need to either restart Gerrit, or try flushing the caches over SSH.

Since SSH cache flushing requires being in the "Administrators" group you may run into a chicken-and-egg problem, where you cannot flush the cache to make yourself an administrator because you are not yet an administrator. Therefore, restarting the application is the recommended bootstrap technique.

To flush the server's caches over SSH, ensure you have an SSH key (you can add one through the web UI under Settings, SSH Keys), and then run:

ssh -p 29418 you@example.com gerrit flush-caches