Step-by-Step Guide: Deploying Gerrit with LDAP Authentication on Tomcat (Windows/Linux)


2 views

Before diving into the installation, ensure you have:

  • Java JDK 8 or later installed
  • Apache Tomcat 8.5+ configured
  • Access to an LDAP server (Active Directory, OpenLDAP, etc.)
  • Basic understanding of WAR file deployment

First, download the Gerrit WAR file from the official repository:

wget https://gerrit-releases.storage.googleapis.com/gerrit-{version}.war

Create a dedicated context file for Gerrit in Tomcat:

<Context docBase="gerrit.war" path="/gerrit">
  <Environment name="gerrit.base" value="C:\gerrit_site" type="java.lang.String" override="false"/>
  <Parameter name="gerrit.installDir" value="/path/to/gerrit.war"/>
</Context>

Modify your gerrit.config (in $gerrit_site/etc) with LDAP settings:

[auth]
  type = LDAP
  gitBasicAuth = true
[ldap]
  server = ldap://your.ldap.server
  username = cn=admin,dc=example,dc=com
  password = secret
  accountBase = ou=people,dc=example,dc=com
  groupBase = ou=groups,dc=example,dc=com

For production use, configure a proper database connection:

[database]
  type = mysql
  hostname = localhost
  database = reviewdb
  username = gerrit
  password = dbpass

On Windows Server 2008, ensure proper permissions are set:

icacls "C:\gerrit_site" /grant "NT AUTHORITY\NETWORK SERVICE":(OI)(CI)F

After deploying, check these key URLs:

  • http://localhost:8080/gerrit/
  • http://localhost:8080/gerrit/login/

If you encounter LDAP connection problems, enable debug logging:

[log]
  level = debug

Check Tomcat's catalina.out for detailed error messages.

For better performance with Tomcat:

<Connector port="8080" 
           maxThreads="150" 
           minSpareThreads="25" 
           connectionTimeout="20000" 
           enableLookups="false"/>

Before proceeding with the installation, ensure you have:

  • Java JDK 8 or later installed
  • Apache Tomcat 8.5+ configured
  • Access to an LDAP server (Active Directory or OpenLDAP)
  • Basic understanding of Gerrit's architecture

First, download the Gerrit WAR file from the official repository:

wget https://gerrit-releases.storage.googleapis.com/gerrit-3.6.0.war
mv gerrit-3.6.0.war gerrit.war

Create a context XML file in Tomcat's conf/Catalina/localhost directory:

<Context docBase="/path/to/gerrit.war">
  <Parameter name="gerrit.site_path" value="/var/gerrit" override="false"/>
</Context>

Modify gerrit.config to enable LDAP authentication:

[auth]
  type = LDAP
  gitBasicAuth = true

[ldap]
  server = ldap://your.ldap.server
  username = cn=admin,dc=example,dc=com
  password = secret
  accountBase = ou=people,dc=example,dc=com
  groupBase = ou=groups,dc=example,dc=com

For Windows Server 2008, you'll need to:

  1. Set JAVA_HOME environment variable
  2. Configure Tomcat service to run under a dedicated account
  3. Adjust file permissions for the Gerrit site directory

If you encounter connection problems with LDAP:

# Test LDAP connectivity
ldapsearch -x -H ldap://your.server -b "dc=example,dc=com"

For Tomcat deployment errors, check:

tail -f /var/log/tomcat/catalina.out

Consider these JVM options in Tomcat's setenv.sh/setenv.bat:

export JAVA_OPTS="-Xmx2048m -Xms1024m -XX:MaxPermSize=512m"