| 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] |
| |
| |
| 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 an RSA, DSA, or both, 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 |
| git config --file $site_path/gerrit.config gerrit.basePath /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] |
| |
| 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 `gerrit.canonicalWebUrl` in `'$site_path'/gerrit.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. |
| |
| [[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] |