Documentation/install.txt

Gerrit2 - Installation Guide
============================

You need a SQL database to house the Gerrit2 metadata.  Currently
H2, MySQL and PostgreSQL are the only supported databases.

Important Links
---------------

PostgreSQL:

* http://www.postgresql.org/docs/[Documentation]
* link:http://jdbc.postgresql.org/download.html[JDBC Driver]

MySQL:

* http://dev.mysql.com/doc/[Documentation]
* http://dev.mysql.com/downloads/connector/j/5.0.html[JDBC Driver]

Optional Libraries:

* link:http://sourceforge.net/project/showfiles.php?group_id=25357[c3p0 JDBC Driver]
* link:http://www.bouncycastle.org/java.html[Bouncy Castle Crypto API]
* link:http://java.sun.com/products/javamail/downloads/index.html[JavaMail]


Downloading Gerrit
------------------

Current and past binary releases of Gerrit can be obtained from
the downloads page at the project site:

* http://code.google.com/p/gerrit/downloads/list[Gerrit Downloads]

Download any current `*.war` package.


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:

* http://maven.apache.org/download.html[Download]
* http://maven.apache.org/run-maven/index.html[Running 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 IDENTIFIED BY PASSWORD 'secret';
  CREATE DATABASE reviewdb;
  GRANT ALL ON reviewdb.* TO 'gerrit2'@'localhost';
====


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
====

MySQL:

====
  java -jar gerrit.war --cat sql/index_generic.sql | mysql reviewdb
  java -jar gerrit.war --cat sql/mysql_nextval.sql | mysql reviewdb
====

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/gerrit/cfg
  cd /home/gerrit/cfg

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

SSH Host Keys
~~~~~~~~~~~~~

If you choose to install the Bouncy Castle Crypto APIs (see below)
you must create RSA and DSA 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
  UPDATE system_config SET git_base_path='/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.

* http://www.kernel.org/pub/software/scm/git/docs/git-daemon.html[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.

* link:config-sso.html[Single Sign-On Systems]
* link:config-replication.html[Git Replication/Mirroring]
* link:config-headerfooter.html[Site Header/Footer]
* link:config-gitweb.html[Gitweb Integration]
* link:config-gerrit.html[Other System Settings]


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`.

* link:http://dist.codehaus.org/jetty/[Jetty Downloads]

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

* link:http://jdbc.postgresql.org/download.html[PostgreSQL JDBC Driver]
* link:http://sourceforge.net/project/showfiles.php?group_id=25357[c3p0 JDBC Driver]

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

* link:http://www.bouncycastle.org/java.html[Bouncy Castle Crypto API]

Jetty comes with JavaMail, so there is no need to install it.

Copy Gerrit into the deployment:
====
  java -jar gerrit.war --cat extra/jetty_gerrit.xml >$JETTY_HOME/contexts/gerrit.xml
  cp gerrit.war $JETTY_HOME/webapps/gerrit.war

  rm -f $JETTY_HOME/context/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 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.mortbay.jetty.nio.SelectChannelConnector`:

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

To start automatically when the system boots, consider a start
script such as the following in `/etc/init.d/gerrit2-jetty`

====
  #!/bin/sh
  
  export JETTY_HOST=127.0.0.1
  export JETTY_PORT=8081
  export JETTY_USER=gerrit2
  export JETTY_PID=/var/run/jetty$JETTY_PORT.pid
  export JETTY_HOME=/home/$JETTY_USER/jetty
  export JAVA_HOME=/usr/lib/jvm/java-6-sun-1.6.0.07/jre
  
  JAVA_OPTIONS=""
  JAVA_OPTIONS="$JAVA_OPTIONS -Djetty.host=$JETTY_HOST"
  export JAVA_OPTIONS

  C="jetty-logging jetty"
  [ -f "$JETTY_HOME/etc/jetty_sslproxy.xml" ] && C="$C jetty_sslproxy"
  
  exec $JETTY_HOME/bin/jetty.sh "$@" $C
====

[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 <<apache2,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`:
====
  java -jar gerrit.war --cat extra/jetty_sslproxy.xml >$JETTY_HOME/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 `canonical_url` in `system_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 <<apache2,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.

('Optional') Configure the JNDI name `mail/Outgoing` for the web
application context to be a factory for a `javax.mail.Session`,
with the connection information necessary to send outgoing emails.
You may need to download and install the Java Mail JARs in your
container's classpath.  If this is not configured, Gerrit will
function, but will not be able to send email.


[[apache2]]
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
-------------------

Login to Gerrit through the web interface, so that a user account
is initialized for you.

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
====


Project Setup
-------------

See link:project-setup.html[Project Setup] for further details on
how to register a project with Gerrit.