To run the Gerrit service, the following requirements must be met on the host:
JDK, minimum version 1.7 Download
You’ll also need an SQL database to house the review metadata. You have the choice of either using the embedded H2 or to host your own MySQL or PostgreSQL.
Configure Java for Strong Cryptography
Support for extra strength cryptographic ciphers: AES128CTR, AES256CTR, ARCFOUR256, and ARCFOUR128 can be enabled by downloading the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files from Oracle and installing them into your JRE.
|Installing JCE extensions is optional and export restrictions may apply.|
Download the unlimited strength JCE policy files.
Uncompress and extract the downloaded file.
The downloaded file contains the following files:
Information about JCE and installation guide
Unlimited strength local policy file
Unlimited strength US export policy file
Install the unlimited strength policy JAR files by following instructions found in
Current and past binary releases of Gerrit can be obtained from the Gerrit Releases site.
Download any current
*.war package. The war will be referred to as
gerrit.war from this point forward, so you may find it easier to
rename the downloaded file.
If you would prefer to build Gerrit directly from source, review the notes under developer setup.
During the init phase of Gerrit you will need to specify which database to use.
If you choose H2, Gerrit will automatically set up the embedded H2 database as backend so no set up or configuration is necessary.
Using the embedded H2 database is the easiest way to get a Gerrit site up and running, making it ideal for proof of concepts or small team servers. On the flip side, H2 is not the recommended option for large corporate installations. This is because there is no easy way to interact with the database while Gerrit is offline, it’s not easy to backup the data, and it’s not possible to set up H2 in a load balanced/hotswap configuration.
If this option interests you, you might want to consider the quick guide.
If Derby is selected, Gerrit will automatically set up the embedded Derby database as backend so no set up or configuration is necessary.
Currently only support for embedded mode is added. There are two other deployment options for Apache Derby that can be added later:
This option is more complicated than the H2 option but is recommended for larger installations. It’s the database backend with the largest userbase in the Gerrit community.
Create a user for the web application within Postgres, assign it a password, create a database to store the metadata, and grant the user full rights on the newly created database:
$ createuser --username=postgres -RDIElPS gerrit2 $ createdb --username=postgres -E UTF-8 -O gerrit2 reviewdb
Visit PostgreSQL’s documentation for further information regarding using PostgreSQL.
This option is also more complicated than the H2 option. Just as with PostgreSQL it’s also recommended for larger installations.
Create a user for the web application within the database, assign it a password, create a database, and give the newly created user full rights on it:
mysql CREATE USER 'gerrit2'@'localhost' IDENTIFIED BY 'secret'; CREATE DATABASE reviewdb; GRANT ALL ON reviewdb.* TO 'gerrit2'@'localhost'; FLUSH PRIVILEGES;
Visit MySQL’s documentation for further information regarding using MySQL.
PostgreSQL or H2 is the recommended database for Gerrit Code Review. Oracle is supported for environments where running on an existing Oracle installation simplifies administrative overheads, such as database backups.
Create a user for the web application within sqlplus, assign it a password, and grant the user full rights on the newly created database:
SQL> create user gerrit2 identified by secret_password default tablespace users; SQL> grant connect, resources to gerrit2;
JDBC driver ojdbc6.jar must be obtained from your Oracle distribution. Gerrit initialization process tries to copy it from a known location:
If this file can not be located at this place, then the alternative location can be provided.
Instance name is the Oracle SID. Sample database section in $site_path/etc/gerrit.config:
[database] type = oracle instance = xe hostname = localhost username = gerrit2 port = 1521
Sample database section in $site_path/etc/secure.config:
[database] password = secret_pasword
SAP MaxDB is a supported database for running Gerrit Code Review. However it is recommended only for environments where you intend to run Gerrit on an existing MaxDB installation to reduce administrative overhead.
In the MaxDB studio or using the SQLCLI command line interface create a user 'gerrit2' with the user class 'RESOURCE' and a password <secret password>. This will also create an associated schema on the database.
To run Gerrit on MaxDB, you need to obtain the MaxDB JDBC driver. It can be found in your MaxDB installation at the following location:
on Windows 64bit at "C:\Program Files\sdb\MaxDB\runtime\jar\sapdbc.jar"
on Linux at "/opt/sdb/MaxDB/runtime/jar/sapdbc.jar"
It needs to be stored in the 'lib' folder of the review site.
In the following sample database section it is assumed that the database name is 'reviewdb' and the database is installed on localhost:
[database] type = maxdb database = reviewdb hostname = localhost username = gerrit2
[database] password = <secret password>
Visit SAP MaxDB’s documentation for further information regarding using SAP MaxDB.
IBM DB2 is a supported database for running Gerrit Code Review. However it is recommended only for environments where you intend to run Gerrit on an existing DB2 installation to reduce administrative overhead.
Create a system wide user for the Gerrit application, and grant the user full rights on the newly created database:
db2 => create database gerrit db2 => connect to gerrit db2 => grant connect,accessctrl,dataaccess,dbadm,secadm on database to gerrit2;
JDBC driver db2jcc4.jar and db2jcc_license_cu.jar must be obtained from your DB2 distribution. Gerrit initialization process tries to copy it from a known location:
If these files cannot be located at this place, then an alternative location can be provided during init step execution.
Sample database section in $site_path/etc/gerrit.config:
[database] type = db2 database = gerrit hostname = localhost username = gerrit2 port = 50001
Sample database section in $site_path/etc/secure.config:
[database] password = secret_pasword
Part of Gerrit Code Review
Initialize the Site
Gerrit stores configuration files, the server’s SSH keys, and the
managed Git repositories under a local directory, typically referred
'$site_path'. If the embedded H2 database is being used,
its data files will also be stored under this directory.
You also have to decide where to store your server side git repositories. This
can either be a relative path under
'$site_path' or an absolute path
anywhere on your server system. You have to choose a place before commencing
your init phase.
Initialize a new site directory by running the init command, passing the path of the site directory to be created as an argument to the '-d' option. Its recommended that Gerrit Code Review be given its own user account on the host system:
sudo adduser gerrit2 sudo su gerrit2 java -jar gerrit.war init -d /path/to/your/gerrit_application_directory
'Please note:' If you choose a location where your new user doesn’t
have any privileges, you may have to manually create the directory first and
then give ownership of that location to the
If run from an interactive terminal, the init command will prompt through a
series of configuration questions, including gathering information
about the database created above. If the terminal is not interactive,
running the init command will choose some reasonable default selections,
and will use the embedded H2 database. Once the init phase is complete,
you can review your settings in the file
When running the init command, additional JARs might be downloaded to support optional selected functionality. If a download fails a URL will be displayed and init will wait for the user to manually download the JAR and store it in the target location.
When the init phase is complete, the daemon will be automatically started in the background and your web browser will open to the site:
Initialized /home/gerrit2/review_site Executing /home/gerrit2/review_site/bin/gerrit.sh start Starting Gerrit Code Review: OK Waiting for server to start ... OK Opening browser ...
When the browser opens, sign in to Gerrit through the web interface. The first user to sign-in and register an account will be automatically placed into the fully privileged Administrators group, permitting server management over the web and over SSH. Subsequent users will be automatically registered as unprivileged users.
Your base Gerrit server is now installed and running. You’re now ready to either set up more projects or start working with the projects you’ve already imported.
See Project Configuration for further details on how to register a new project with Gerrit. This step is necessary if existing Git repositories were not imported during 'init'.
To control the Gerrit Code Review daemon that is running in the background, use the rc.d style start script created by 'init':
review_site/bin/gerrit.sh start review_site/bin/gerrit.sh stop review_site/bin/gerrit.sh restart
('Optional') Configure the daemon to automatically start and stop with the operating system.
Uncomment the following 3 lines in the
chkconfig: 3 99 99 description: Gerrit Code Review processname: gerrit
Then link the
gerrit.sh script into
sudo ln -snf `pwd`/review_site/bin/gerrit.sh /etc/init.d/gerrit sudo ln -snf /etc/init.d/gerrit /etc/rc3.d/S90gerrit
('Optional') To enable autocompletion of the gerrit.sh commands, install
autocompletion from the
/contrib/bash_completion script. Refer to the
script’s header comments for installation instructions.
To install Gerrit into an existing servlet container instead of using the embedded Jetty server, see J2EE installation.
Place Gerrit plugins in the review_site/plugins directory to have them loaded on Gerrit startup.