464 lines
13 KiB
Plaintext
464 lines
13 KiB
Plaintext
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[[other_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.
|
|
|
|
GERRIT
|
|
------
|
|
Part of link:index.html[Gerrit Code Review]
|