INSTALL

Gerrit 2 - Installation
-----------------------

- Get Maven 2 if you don't have it already:

  http://maven.apache.org/download.html

- Build the application distribution:

  (cd appdist && mvn clean install)

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

  Unfortunately you need to install to your local Maven repository
  (typically under ~/.m2) in order to fully build all of the source
  based dependencies.  Core dependencies for Gerrit are still under
  active development and have not made final releases yet.


- Deploy the WAR file to your application server:

    appdist/target/gerrit-*-bin.dir/gerrit-*/www/gerrit-*.war

  Configure the JNDI DataSource "jdbc/ReviewDb" for the Gerrit
  web application context to point to a SQL database supported
  by gwtorm.  (Currently PostgreSQL and H2 are supported.)

  Deploying on Jetty?

  See appdist/target/gerrit-*-bin.dir/gerrit-*/www/jetty_gerrit.xml
  for Jetty specific installation instructions, including a sample
  JNDI configuration for Gerrit.


- Create the database, e.g. with PostgreSQL:

    createdb -E UTF-8 -O gerrit2 reviewdb


- Create the Gerrit 2 tables:

  Either run CreateSchema from the command line (requires writing
  a GerritServer.properties, see GerritServer.properties_example
  under devdb/src/main/config):

    appdist/target/gerrit-*-bin.dir/gerrit-*/bin/gerrit2.sh \
      --config=GerritServer.properties \
      CreateSchema

  Or run the application once in a container to force it to
  initialize the database schema before accessing it.


- Apply table indexes by executing

    appdist/target/gerrit-*-bin.dir/gerrit-*/sql/query_index.sql

  through your database's query tool,e.g. with PostgreSQL:

    psql -f query_index.sql reviewdb


- Create and configure the 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.

    mkdir /home/gerrit/cfg
    cd /home/gerrit/cfg

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

  Tell Gerrit where the site_path is by setting it in the
  system_config table, e.g.:

    psql -c "UPDATE system_config SET site_path='/home/gerrit/cfg'" reviewdb


- Create and configure the 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
    psql -c "UPDATE system_config SET git_base_path='/srv/git'" reviewdb


- Restart the Gerrit web application:

  The contents of system_config are cached at startup.  If you
  modify its Gerrit needs to be restarted to use the new values.


Optional - Other system_config
------------------------------

Other columns in system_config may also be set:

  gitweb_url:

  Defines the web location where a gitweb.cgi is installed to browse
  $git_base_path and the repositories it contains.  Gerrit appends
  query arguments, e.g. "?p=$project.git;h=$commit" onto the end
  of this URL.

  canonical_url:

  Sets the default URL for Gerrit to be accessed through.
  Typically this would be set to "http://$your.server.com/" or
  "http://$your.server.com/gerrit/" so Gerrit can output links that
  come back to itself.

  sshd_port:

  Port number the internal SSHD listens for connections on.
  Gerrit receives new change submissions through this port by
  "git push ssh://$your.server:$sshd_port/$project.git ...".

  By default this is 29418.


Optional - Site Customization
-----------------------------

At startup Gerrit reads the following files (if they exist) and
uses them to customize the HTML page it sends to clients:

  $site_path/GerritSiteHeader.html
  $site_path/GerritSiteFooter.html
  $site_path/GerritSite.css

If these are modified you need to restart the web application
to make the changes take effect.

The *.html files must be valid XHTML, with one root element,
typically a <div> tag.  The server parses it as XML, and then
inserts that element into the host page.

Static image files can also be served from $site_path/static, and may
be referenced in GerritSite{Header,Footer}.html or GerritSite.css by
the relative URL "static/$name".  To simplify security management
only files are served from $site_path/static, subdirectories are
explicitly forbidden from being served from this location.

Assets from $site_path/static are served with a 5 minute expire;
permitting some (limited) caching.


Optional - Google Analytics Integration
---------------------------------------

To fully connect Gerrit to Google Analytics add the following into
GerritSiteFooter.html:

  <div>
    <!-- standard google analytics tracking setup -->

    <script type="text/javascript"><!--
      window.onload = function() {
        gerrit_addHistoryHook(function (s) {
          pageTracker._trackPageview(s)
        });
      };
      //-->
    </script>
  </div>

The global function gerrit_addHistoryHook accepts functions that
accept a string parameter.  These functions are put into a list
and invoked any time Gerrit shifts URLs.  You'll see the page
names like '/Gerrit#change,123' be passed to these functions,
which in turn are handed off to Analytics for tracking.

The window.onload callback is necessary to ensure that the
gerrit_addHistoryHook function has actually been defined.
Because GWT loads the module asynchronously your <script>
block will execute before Gerrit is ready to receive the
hook callback.