How Do I Install Gerrit Under Tomcat with LDAP?

I decided to go ahead an answer this as it's kind of needed for the Gerrit Community. Currently, there're not a whole lot of tutorials covering advanced setups for Gerrit. I'm hoping this will help others explore XP/Agile practices and get Gerrit up and running. It's a great tool once you get past all the subtle setup challenges and details.

This install tutorial is rather unique in that it serves the specific environment:

• Windows 2008 Server
• PostgreSql
• Tomcat
• LDAP via Active Directory
• Gerrit
• msysgit

Before you begin, make sure you have git installed on your system. Download the latest msysgit command line tool for windows from http://code.google.com/p/msysgit/downloads/list

Make sure you get the "Full installer for official Git for Windows".

• Install MSysGit
• Use defaults when prompted
• Configure Git

If you intend on using the GitWeb version in msysgit, you will notice some issues around CGI.pm. I would like to mention a fix to resolve this issue.

The perl included with the msysgit distro, as of 1.7.8, is broken, http://groups.google.com/group/msysgit/browse_thread/thread/ba3501f1f0ed95af. The unicore folder is missing along with utf8_heavy.pl and CGI.pm. You can verify by checking for perl modules:

perl -mCGI -mEncode -mFcntl -mFile::Find -mFile::Basename -e "" You will probably encounter the following exception:

$ perl -mCGI -mEncode -mFcntl -mFile::Find -mFile::Basename -e "" Can't locate CGI.pm in @INC (@INC contains: /usr/lib/perl5/5.8.8/msys /usr/lib/p erl5/5.8.8 /usr/lib/perl5/site_perl/5.8.8/msys /usr/lib/perl5/site_perl/5.8.8 /u sr/lib/perl5/site_perl .). BEGIN failed--compilation aborted.

If you're missing CGI.pm, you'll have to deploy the module to the msys environment: You will have to retrieve them from the 5.8.8 distro on :

http://strawberryperl.com/releases.html

File: strawberry-perl-5.8.8.3.zip

contents: bin/ lib/ site/

copy the contents of lib into msysgit/lib/perl5/5.8.8 and overwrite existing files.

If using commandline git, add your global configuration settings to git:

git config --global user.name "Your Name"
git config --global user.email [email protected]
git config --global core.autocrlf false

Make sure the credentials used here match the credentials in gerrit. Otherwise, gerrit will reject your request.

The instructions for installing and configuring Gerrit are as follows:

• First, login to the server hosting postgres and create a user and database for Gerrit
• createuser --username=postgres -A -D -P -E gerrit2
• createdb --username=postgres -E UTF-8 -O gerrit2 reviewdb
• Now, switch back to the host,if different, for Gerrit and create 3 directories for deploying Gerrit
• Create a base install directory for gerrit, preferably a versioned directory for the war deployment contents
• Create a subdirectory for tomcat
• Create an config directory for deploying the schema and configuration
• The contents should look like this:
• gerrit
  • tomcat
  • config
  • gerrit-X.X
• Download tomcat from http://tomcat.apache.org/download-60.cgi
• Note: Most Linux Distributions will have this available from their update managers. Example: Use Synaptic on Ubuntu
• Deploy your tomcat install to the tomcat directory
• Download the latest gerrit.war from http://code.google.com/p/gerrit/downloads/list.
• copy file to the base gerrit directory
• extract the war file to the gerrit-X.X subdirectory
• CD to the gerrit base directory and run java -jar gerrit-2.4-rc0.war init -d config
  • This configuration includes extras for LDAP and running behind a proxy, don't configure these options if not needed.

Execute:

C:\your_path\gerrit>java -jar gerrit-2.4-rc0.war init -d config
*** Gerrit Code Review 2.4-rc0
***
Create 'C:\your_path\gitserver\gerrit\config' [Y/n]? Y
*** Git Repositories
***
Location of Git repositories   [git]: C:\your_path\gitserver\repository\ha
*** SQL Database
***
Database server type           [H2/?]: postgresql
Server hostname                [localhost]: database.corp.local
Server port                    [(POSTGRESQL default)]:
Database name                  [reviewdb]:
Database username              [Administrator]: gerrit2
gerrit2's password             :
              confirm password :
*** User Authentication
***
Authentication method          [OPENID/?]: LDAP
LDAP server                    [ldap://localhost]: ldaps://ldap.corp.local:
636
LDAP username                  : CN=Administrator,CN=Users,DC=corp,DC=local
CN=Administrator,CN=Users,DC=corp,DC=local's password :
              confirm password :
Account BaseDN                 [DC=corp,DC=local:636]: CN=Users,DC=corp,DC=l
ocal
Group BaseDN                   [CN=Users,DC=corp,DC=local]:
*** Email Delivery
***
SMTP server hostname           [localhost]: smtp.corporation.com
SMTP server port               [(default)]: 465
SMTP encryption                [NONE/?]: SSL
SMTP username                  [Administrator]: [email protected]
[email protected]'s password :
              confirm password :
*** Container Process
***
Run as                         [Administrator]:
Java runtime                   [C:\Program Files\Java\jre6]:
Copy gerrit.war to C:\your_path\gitserver\gerrit\config\bin\gerrit.war [Y/n]?
Copying gerrit.war to C:\your_path\gitserver\gerrit\config\bin\gerrit.war
*** SSH Daemon
***
Listen on address              [*]:
Listen on port                 [29418]:
Gerrit Code Review is not shipped with Bouncy Castle Crypto v144
  If available, Gerrit can take advantage of features
  in the library, but will also function without it.
Download and install it now [Y/n]? n
Generating SSH host key ... rsa(simple)... done
*** HTTP Daemon
***
Behind reverse proxy           [y/N]?
Use SSL (https://)             [y/N]?
Listen on address              [*]:
Listen on port                 [8080]:
Initialized C:\your_path\gitserver\gerrit\config
Automatic startup not supported on Win32.

• Don't worry about setting up Gerrit as a servers, we will configure that later
• Edit config\etc\gerrit.config
• under gerrit section, add a setting for conicalWebUrl = http://review.corporation.com/
• If your projects don't follow the traditional project.git format, add the following section:
• add the file locaiton and url to your gitweb server along with associated properties

gerrit.config Update:

[gitweb]
        cgi = C:\\path to msysgit\\Git\\share\\gitweb\\gitweb.cgi
        url = https://gitweb.corporation.com
        type = custom
        project = ?p=${project};a=summary 
        revision = ?p=${project};a=commit;h=${commit}
        branch = ?p=${project};a=shortlog;h=${branch}
        filehistory = ?p=${project};a=history;hb=${branch};f=${file}

• If you're using http/https to serve, add the following:

gerrit.config Update:

[download]
scheme = http

• If you're using LDAP with active directory, you will need to tweak your settings add additional settings to support AD:

gerrit.config Update:

[ldap]
sslVerify = true
server = ldaps://ldap.corp.local:636
username = CN=Administrator,CN=Users,DC=corp,DC=local
accountBase = CN=Users,DC=corp,DC=local
accountPattern = (&(objectClass=person)(sAMAccountName=${username})) 
accountFullName = displayName 
accountEmailAddress = mail 
accountSshUserName = sAMAccountName 
groupBase = CN=Users,DC=corp,DC=local
groupMemberPattern = (sAMAccountName=${username}) 
groupName = cn

• Download the latest release of Bouncy Castles from http://www.bouncycastle.org/latest_releases.html
• Copy bcmail-jdk15on-147.jar, bcpg-jdk15on-147.jar, bcpkix-jdk15on-147.jar, bcprov-jdk15on-147.jar, bcprov-ext-jdk15on-147.jar to gerrit-X.X\WEB-INF\lib
• Edit the server.xml. Add your gerrit deployment to the Host section of the server.xml: (Note: For Tomcat 7, instead of server.xml, you may have to edit context.xml. Refer: http://tomcat.apache.org/tomcat-7.0-doc/jndi-datasource-examples-howto.html#MySQL_DBCP_Example )

Server.xml:

<Server port="8006" shutdown="SHUTDOWN">
<Service name="Catalina">
 <Engine name="Catalina" defaultHost="localhost">
  <Host name="localhost"  appBase="webapps" unpackWARs="true">
    <Context path="" docBase="C:\your_path\gitserver\gerrit\gerrit-2.4" debug="0" reloadable="false">
        <Resource
           name="jdbc/ReviewDb"
           type="javax.sql.DataSource"
           username="gerrit2"
           driverClassName="org.postgresql.Driver"
           password="secret"
           url="dbc:postgresql://yourPsqlServer:5432/reviewdb"
        />
    </Context>
  </Host>
</Engine>
<Connector port="8080" protocol="HTTP/1.1"
               connectionTimeout="20000"/>
<Connector port="8011" protocol="AJP/1.3" maxHttpHeaderSize="8192"
           maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
           disableUploadTimeout="true" enableLookups="false"
           acceptCount="100" URIEncoding="UTF-8" />
</Service>
</Server>

• You don't need the AJP connector unless you intend on proxying with Apache HTTP Server. I use it to offload SSL encryption and manage certificates. Just remove it if not needed. Be sure to change your HTTP connector port to 80 if you intend to run standalone.

• The configuration above is for usage with postgres. If you're using MySQL, you will have to replace the resource with the following for MySQL:

Server.xml:

<Resource
name="jdbc/ReviewDb"
type="javax.sql.DataSource"
username="gerrit2"
driverClassName="org.gjt.mm.mysql.Driver"
password="secret"
url="jdbc:mysql://yourMsqlServer/reviewdb?autoReconnect=true"
/>

At this point, you are now ready to Configure Gerrit as a service and bring the review system online.

• First, tweak Tomcat Settings for Running Gerrit as a Service
• Goto tomcat/bin and edit service.bat

The jvm options are set separately for the nt service. You must modify your service.bat file before installing the nt service. This file resides in the tomcat/bin directory with the other startup.bat and shutdown scripts. Scroll down to the following section:

"%EXECUTABLE%"  //US//%SERVICE_NAME% \++JvmOptions  "-Djava.io.tmpdir=%CATALINA_BASE%\temp;-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager;-Djava.util.logging.config.file=%CATALINA_BASE%\conf\logging.properties"  \--JvmMs 128 \--JvmMx 256

Modify this line to match the following:

"%EXECUTABLE%" //US//%SERVICE_NAME%  \++JvmOptions  "-Djava.io.tmpdir=%CATALINA_BASE%\temp;-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager;-Djava.util.logging.config.file=%CATALINA_BASE%\conf\logging.properties"  \++JvmOptions="-XX:MaxPermSize=256m"  \++JvmOptions="-XX:+CMSClassUnloadingEnabled"  \++JvmOptions="-XX:+CMSPermGenSweepingEnabled" \--JvmMs 512 \--JvmMx 1024

The initial memory, jvmMs, should definitely be set to 512Mb for gerrit and extended, JvmMx, to 1024Mb.

Now you are ready to deploy gerrit as a service under windows. Just execute the following:

C:\your_path\gitserver\gerrit\tomcat\bin>service install gerrit
Installing the service 'gerrit' ...
Using CATALINA_HOME: "C:\your_path\gitserver\gerrit\tomcat"
Using CATALINA_BASE: "C:\your_path\gitserver\gerrit\tomcat"
Using JAVA_HOME: "C:\Program Files\Java\jdk1.6.0_31"
Using JVM: "C:\Program Files\Java\jdk1.6.0_31\jre\bin\server\jvm.dl
l"
The service 'gerrit' has been installed.

C:\your_path\gitserver\gerrit\tomcat\bin>

Goto your server manager and open the Services node. Open the properties for Gerrit and make sure you set the startup type to Automatic:

Apply and Close Dialog.

OK... Are we done yet? Unfortunately no, just a few more steps to go. Hang in there.

Now you're ready to start the service. Just highlight the Gerrit service and click the Start option to the left.

Review the logs under the tomcat/log directory. Ensure there are no outstanding errors. If you have problems, you can ask questions here or on the gerrit mailing list: http://groups.google.com/group/repo-discuss

You should be able to goto your browser and enter the url of your server to view Gerrit now: http://review.corporation.com:8080

You will be prompted to enter your ssh public key. This is only necessary if you intend on using Git/Gerrit via ssh instead of HTTP. I went ahead and set it up because it's a good option to have.

Configure SSH

Generate an ssh key for access:

Administrator@SERVER~/test $ ssh-keygen -t rsa

Register a new account in Gerrit through the web interface with the email address of your choice. 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.

Once signed in as your user, you find a little wizard to get you started. The wizard helps you fill out:

• Real name (visible name in Gerrit)
• Register your email (it must be confirmed later)
• Select a username with which to communicate with Gerrit over ssh+git

• The server will ask you for an RSA public key. That’s the key we generated above, and it’s time to make sure that Gerrit knows about our new key and can identify us by it.

  user@host:~$ cat .ssh/id_rsa.pub

Configure HTTP access for registered users only, unless your project is open to the public:

Generate an HTTP Password

Despite having configured your own login, you still have to generate a password for gerrit to server via http/https. Goto your Settings->HTTP Password configuration and click on 'Generate Password'. Use this password for all git operations over http(s).

Now we can test Gerrit via HTTP. You should be able to clone any projects existing in the repository you've referenced in the Gerrit config.

Test with clone operation

Administrator@SERVER ~/test
$ git clone https://review.corporation.com/sandbox

Test your ssh account

Administrator@SERVER~/test
$ ssh jhuntley@localhost -p 29418

**** Welcome to Gerrit Code Review ****

Hi Jason Huntley, you have successfully connected over SSH.

Unfortunately, interactive shells are disabled.
To clone a hosted Git repository, use:

git clone ssh://[email protected]:29418/REPOSITORY_NAME.g
it

Connection to localhost closed.

Clone a project from Gerrit via SSH:

Administrator@SERVER~/test
$ git clone ssh://[email protected]:29418/sandbox
Cloning into 'sandbox'...
remote: Counting objects: 183, done
remote: Finding sources: 100% (183/183)
remote: Total 183 (delta 0), reused 0 (delta 0)Receiving objects: 50% (92/183)
Receiving objects: 52% (96/183)
Receiving objects: 100% (183/183), 23.76 KiB, done.

If you haven't given up by now, you can relax, you should find yourself with a working Gerrit Code Review system hosted by a Windows 2008 Server :) It's not as common as a setup and as you can tell, warrants all the extra steps. However, some of us have limited resources and can only use what's provided. I hope this tutorial helps those seeking to run Gerrit in a similar environment. You should be ready now to start using Gerrit! Enjoy!

For further information regarding using Gerrit, please consult with the user guide from the Gerrit project:

http://gerrit-documentation.googlecode.com/svn/Documentation/2.3/index.html

Thank You Shawn Pierce for the help on IRC!

For future reference

Tutorial has been converted over to documentation for the Gerrit project. For those interested and need a good reference. Please see the patch request here:

https://gerrit-review.googlesource.com/#/c/37072