gerrit/Documentation/install.txt

Gerrit Code Review - Installation Guide
=======================================

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

[[download]]
Download 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. 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 link:dev-readme.html[developer setup].

[[createdb]]
Database Setup
--------------

[[createdb_h2]]
H2
~~

During init Gerrit will automatically configure the embedded H2
database.  No additional configuration is necessary.  Using the
embedded H2 database is the easiest way to get a Gerrit site up
and running.

[[createdb_postgres]]
PostgreSQL
~~~~~~~~~~

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 -A -D -P -E gerrit2
  createdb -E UTF-8 -O gerrit2 reviewdb
----

[[createdb_mysql]]
MySQL
~~~~~

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;
  ALTER DATABASE reviewdb charset=latin1;
  GRANT ALL ON reviewdb.* TO 'gerrit2'@'localhost';
  FLUSH PRIVILEGES;
----


[[init]]
Initialize the Site
-------------------

Gerrit stores configuration files, the server's SSH keys, and the
managed Git repositories under a local directory, typically referred
to as `'$site_path'`.  If the embedded H2 database is being used,
its data files will also be stored under this directory.

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
  cd ~gerrit2

  java -jar gerrit.war init -d review_site
----

If run from an interactive terminal, 'init' will prompt through a
series of configuration questions, including gathering information
about the database created above.  If the terminal is not interactive
init will make some reasonable default selections, and will use the
embedded H2 database.

Init may need to download additional JARs 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 'init' 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.


[[project_setup]]
Project Setup
-------------

See link:project-setup.html[Project Setup] 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'.


[[rc.d]]
Start/Stop Daemon
-----------------

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') Link the gerrit.sh script into rc3.d so the daemon
automatically starts and stops with the operating system:

====
  sudo ln -snf `pwd`/review_site/bin/gerrit.sh /etc/init.d/gerrit.sh
  sudo ln -snf ../init.d/gerrit.sh /etc/rc3.d/S90gerrit
====

To install Gerrit into an existing servlet container instead of using
the embedded Jetty server, see
link:install-j2ee.html[J2EE installation].


[[customize]]
Site Customization
------------------

Gerrit Code Review supports some site-specific customization options.
For more information, see the related topic in this manual:

* link:config-apache2.html[Apache 2 Reverse Proxy]
* 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]


[[anonymous_access]]
Anonymous Access
----------------

Exporting the Git repository directory
(link:config-gerrit.html#gerrit.basePath[gerrit.basePath]) over the
anonymous, unencrypted git:// protocol 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]


External Documentation Links
----------------------------

* http://www.postgresql.org/docs/[PostgreSQL Documentation]
* http://dev.mysql.com/doc/[MySQL Documentation]
* http://www.kernel.org/pub/software/scm/git/docs/git-daemon.html[git-daemon]


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