Update:
This tutorial is somewhat outdated. Maybe
relevant setup parts are still valid, however nowadays you should find
plenty of ready-to-use docker images out there providing a working
gerrit setup. I leave the tutorial online, just remember that it was
written in 2012.
When you followed my
previous post on git you might already have expected this one to come. Today we will setup a
gerrit code review server.
A typical setup would use the integrated jetty server, an H2 database and openID for authentication. As this might not always be the first choice of components we will use a different approach here:
As a servlet container we will use tomcat running behind an apache webserver. We will use apache to deal with authentication so that we don't need openID for that. Finally we will replace H2 with mysql. To make this work we need to tweak a bit as especially mysql does not seem to be the first choice for gerrit programmers. For all you guys out there that deal with apache/tomcat/reverse proxy setups: please feel free to help to improve the setup as I (as a novice) struggled to make this work. To all the others: be warned that it might have some security issues.
That said, we are ready to start. Like the git server setup we will implement this on
gentoo, my linux distribution of choice.
To actually work with gerrit you need access to a working SMTP server. I guess you'll figure out how to do this on your own.
Step 1: Install components
When building apache we need some extra modules named
proxy,
proxy_ajp and
proxy_http. To enable these modules we need to add them to the
APACHE2_MODULES configuration. So edit
/etc/make.conf and add the line:
APACHE2_MODULES="actions alias auth_basic authn_alias authn_anon authn_dbm authn_default authn_file authz_dbm authz_default authz_groupfile authz_host authz_owner authz_user autoindex cache cgi cgid dav dav_fs dav_lock deflate dir disk_cache env expires ext_filter file_cache filter headers include info log_config logio mem_cache mime mime_magic negotiation rewrite setenvif speling status unique_id userdir usertrack vhost_alias proxy proxy_ajp proxy_http"
I left the other modules as defined by the default settings. If you are going to experiment with these you do this at your own risk.
Now install all needed components:
emerge apache tomcat mysql git commons-dbcp commons-pool
After starting apache and tomcat you should be able to see the welcome pages when pointing your browser to
http://localhost and http://locahost:8080.
/etc/init.d/apache2 start
/etc/init.d/tomcat-7 start
Step 2: Configure mySQL
If you installed mysql for the first time, you need to configure it before starting it.
emerge --config =dev-db/mysql-5.1.62-r1
/etc/init.d/mysql start
mysql -u root -p
On the mysql shell enter following commands
CREATE USER 'gerrit'@'localhost' IDENTIFIED BY 'gentoo';
CREATE DATABASE gerritdb;
ALTER DATABASE gerritdb charset=latin1;
GRANT ALL ON gerritdb.* TO 'gerrit'@'localhost';
FLUSH PRIVILEGES;
exit;
We created a database
gerritdb and a user
gerrit using the password
gentoo.
Step 3: Configure tomcat
We need a tomcat user to access the manager console. So edit
/etc/tomcat-7/tomcat-users.xml
<tomcat-users>
<role rolename="manager-gui"/>
<user username="root" password="gentoo" roles="manager-gui"/>
</tomcat-users>
Additionally we need a database connector for the mysql database. Open
/etc/tomcat-7/context.xml and add:
<Context>
<!-- DB connector for gerrit -->
<Resource name="jdbc/ReviewDb" auth="Container"
type="javax.sql.DataSource"
maxActive="100" maxIdle="30" maxWait="10000"
username="gerrit" password="gentoo"
driverClassName="com.mysql.jdbc.Driver"
factory="org.apache.commons.dbcp.BasicDataSourceFactory"
url="jdbc:mysql://localhost:3306/gerritdb"/>
</Context>
Now we need to tell tomcat where to find
commons-dbcp.jar and
commons-pool.jar.
ln -s /usr/share/commons-dbcp/lib/commons-dbcp.jar /usr/share/tomcat-7/lib/
ln -s /usr/share/commons-pool/lib/commons-pool.jar /usr/share/tomcat-7/lib/
Restart tomcat to use the new settings:
/etc/init.d/tomcat-7 restart
Step 4: Configure apache
Apache will act as reverse proxy, which allows us to hide tomcat behind the apache webserver. Apache acts as a proxy between the client and the tomcat application. As we normally do not want to relay all traffic to tomcat we will create our own named vhost
First enable proxy support by changing
APACHE2_OPTS in
/etc/conf.d/apache2
APACHE2_OPTS="-D DEFAULT_VHOST -D INFO -D SSL -D SSL_DEFAULT_VHOST -D LANGUAGE -D PROXY"
Add a new file
/etc/apache2/vhosts.d/01_gerrit_proxy.conf to host our virtual server:
<IfDefine DEFAULT_VHOST>
Listen 81
NameVirtualHost *:81
<VirtualHost *:81>
ServerName localhost
Include /etc/apache2/vhosts.d/default_vhost.include
<IfModule mpm_peruser_module>
ServerEnvironment apache apache
</IfModule>
ProxyRequests Off
<proxy *="">
Order deny,allow
Allow from all
</proxy>
ProxyPass /gerrit/ http://localhost:8080/gerrit/
ProxyPassReverse /gerrit/ http://localhost:8080/gerrit/
<Location /gerrit/login/>
AuthType Basic
AuthName "Gerrit Code Review"
AuthBasicProvider file
AuthUserFile /var/www/localhost/passwords
Require valid-user
</Location>
</VirtualHost>
</IfDefine>
We defined to use a ht password file to access gerrit, so we need to create it first.
htpasswd -c /var/www/localhost/passwords administrator # create first entry
htpasswd/var/www/localhost/passwords user1 # create additional entry
Remember that every gerrit user needs its own entry here.
Finally restart apache
/etc/init.d/apache2 restart
Step 5: Setup gerrit
Next we need to
download gerrit. At the time of writing
gerrit-full-2.5.war was the latest release. Rename your downloaded file to
gerrit.war.
Open up the local tomcat manager application
http://localhost:8080/manager and scroll down to
WAR file to deploy. Select your downloaded gerrit.war and
deploy it.
Gerrit cannot install when
binlogs are enabled in mysql. So lets disable them during setup. Modify /etc/mysql/my.cnf and comment out
log-bin:
#log-bin
afterwards restart mysql
/etc/init.d/mysql restart
Now we are ready to setup gerrit:
java -jar /var/lib/tomcat-7/webapps/gerrit.war init -d /opt/gerrit
The setup script will ask some questions, see my installation log below for answers:
*** Gerrit Code Review 2.5
***
Create '/opt/gerrit' [Y/n]?
*** Git Repositories
***
Location of Git repositories [git]: /var/lib/git/repositories
*** SQL Database
***
Database server type [H2/?]: mysql
Gerrit Code Review is not shipped with MySQL Connector/J 5.1.10
** This library is required for your configuration. **
Download and install it now [Y/n]?
Downloading http://repo2.maven.org/maven2/mysql/mysql-connector-java/5.1.10/mysql-connector-java-5.1.10.jar ... OK
Checksum mysql-connector-java-5.1.10.jar OK
Server hostname [localhost]:
Server port [(MYSQL default)]:
Database name [reviewdb]: gerritdb
Database username [root]: gerrit
gerrit's password : gentoo
confirm password : gentoo
*** User Authentication
***
Authentication method [OPENID/?]: http
Get username from custom HTTP header [y/N]?
SSO logout URL :
*** Email Delivery
***
SMTP server hostname [localhost]: <enter your smtp server>
SMTP server port [(default)]: <...>
SMTP encryption [NONE/?]: <...>
SMTP username : <...>
*** Container Process
***
Run as [root]:
Java runtime [/opt/icedtea-bin-6.1.11.5/jre]:
Copy gerrit.war to /opt/gerrit/bin/gerrit.war [Y/n]?
Copying gerrit.war to /opt/gerrit/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]?
Downloading http://www.bouncycastle.org/download/bcprov-jdk16-144.jar ... OK
log-bin
Checksum bcprov-jdk16-144.jar OK
Generating SSH host key ... rsa... dsa... done
*** HTTP Daemon
***
Behind reverse proxy [y/N]?
Use SSL (https://) [y/N]?
Listen on address [*]:
Listen on port [8080]: 8081
*** Plugins
***
Prompt to install core plugins [y/N]?
Initialized /opt/gerrit
Executing /opt/gerrit/bin/gerrit.sh start
Starting Gerrit Code Review: * WARNING: -c/--chuid is deprecated and will be removed in the future, please use -u/--user instead
log-bin
* WARNING: -a/--startas is deprecated and will be removed in the future, please use -x/--exec or -n/--name instead
OK
Waiting for server to start ... OK
Opening browser ...
Please open a browser and go to http://vserver:8081/#/admin/projects/
Your settings are stored in /opt/gerrit/etc/gerrit.config. See the
configuration docs for details. In case you want to change some of them simply run the setup again.
SMTP data is up to you to provide. You'll need it as gerrit depends on sending emails.
You may revert the binlogs settings of mysql now if you wish.
As the setup automatically starts gerrit (and ssh, jetty) we have to stop it:
/opt/gerrit/bin/gerrit.sh stop
Some final settings to make tomcat happy:
chown tomcat:tomcat -R /opt/gerrit
chown tomcat:tomcat -R /var/lib/git/repositories
cp /opt/gerrit/lib/bcprov-jdk16-144.jar /usr/share/tomcat-7/lib/
cp /opt/gerrit/lib/mysql-connector-java-5.1.10.jar /usr/share/tomcat-7/lib/
Step 6: Fine tuning of mysql
Gerrit is a little picky about text encodings in mysql. Typically all fields should be encoded
latin1_bin, but for the web frontend to work some of them need to be changed to
utf8_bin. This seems to be a long lasting struggle between gerrit and mysql. To fix those issues you need to convert some text fields to utf8. I tried to locate them all by playing around with the web interface. You might change them by running following sql statements in mysql:
USE gerritdb;
ALTER TABLE `accounts` CHANGE `full_name` `full_name` VARCHAR( 255 ) CHARACTER SET utf8 COLLATE utf8_bin NULL DEFAULT NULL , CHANGE `preferred_email` `preferred_email` VARCHAR( 255 ) CHARACTER SET utf8 COLLATE utf8_bin NULL DEFAULT NULL;
ALTER TABLE `account_external_ids` CHANGE `email_address` `email_address` VARCHAR( 255 ) CHARACTER SET utf8 COLLATE utf8_bin NULL DEFAULT NULL;
If you encounter application errors, please consult
/var/logs/tomcat-7/localhost.<current_date>.log and look for lines like this one:
com.google.gwtorm.server.OrmException: fetch failure on account_external_ids
It tells you that table
acount_external_ids needs some tweaking. Here the field
email_address needs conversion to utf8-bin.
As sql is not a language that I 'speak' fluently I used
phpmyadmin to change the database layout.
Please let me know of any additional changes so that I can update this post.
Step 7: Restart servers
Now all that's left to do is restart your servers and add them to your default runlevel.
/etc/init.d/mysql restart
/etc/init.d/apache2 restart
/etc/init.d/tomcat-7 restart
rc-update add mysql default
rc-update add apache2 default
rc-update add tomcat-7 default
Point your browser to
http://localhost:81/gerrit/ to see your server in action.
Take care to first login with your designated administrator user as the very first user to login to gerrit will automatically gain admin rights.
Final thoughts
The setup as described is working, but I guess the apache/tomcat setup might need some tweaking. I'd be glad to get some comments from more experienced users on this. Eg. after entering login data the user is redirected to an error site. When entering the base address for a second time you end up in the gerrit application.
Setting
gerrit.canonicalWebUrl in the gerrit config file is highly recommended as gerrit wants to provide some links to itself. With the reverse proxy such links will only work when a correct host is specified here (like http://hostname:81/gerrit).
