Installing OpenGrok On Ubuntu Linux

I am really impressed with OpenGrok, a web-based source code search engine that I've found while I was trying to look up OpenJDK's source code. It is pretty cool as OpenGrok allows you to point your browser into an exact line of source code in your respository, allowing citations directly for discussion using hyperlinks, rather than cutting and pasting chunks of code. I find useful for annotating code, like when I'm using a wiki in conjunction with it to document design considerations for the source.

I'm only supplementing OpenGrok documentation because there were some parts of it which were less clear, taking longer than I expected to get it running. Hopefully, these instructions will help you cut down your setup time.

The assumption is that you're installing from a bare-bones Ubuntu system, and all commands here assume that you are root, which if you're like me, coming from a Gentoo background and sick of typing sudo all the time, you stay rooted all the time by using:

sudo -i

The next thing to do is to get all the relevant software via aptitude. I'll be using Apache Tomcat as my application server:

aptitude install sun-java6-jdk tomcat5.5 exuberant-ctags

Before we set up OpenGrok, we need to create the directory structure to store the files. For the sake of brevity, I'll use the same directory structure from OpenGrok's EXAMPLE.txt:

/opengrok
|-- bin
|-- data
`-- source

Download the tar.gz archive from its website, unpack and extract it. Copy the OpenGrok binaries into the /opengrok/bin:

# cp -r run.sh opengrok.jar lib /opengrok/bin

Edit run.sh and setup up the following parameters:

SRC_ROOT=/opengrok/source
DATA_ROOT=/opengrok/data
EXUB_CTAGS=/usr/bin/ctags

Note that I have put in the default location for the installed ctags for Ubuntu, you may have different locations/application names depending on your Linux distro. You'll then have to configure the web application. Go to the directory where you've downloaded your files, and unzip source.war to make modifications:

# mkdir source
# cd source
# unzip /path/to/opengrok-release/source.war

And make changes into WEB-INF/web.xml. The completed changes look like this:

<context-param>
<param-name>DATA_ROOT</param-name>
<param-value>/opengrok/data</param-value>
<description>REQUIRED: Full path of the directory where data files generated by OpenGrok are stored</description>
</context-param>

<context-param>
<param-name>SRC_ROOT</param-name>
<param-value>/opengrok/src</param-value>
<description>REQUIRED: Full path to source tree</description>
</context-param>

<context-param>
<param-name>SCAN_REPOS</param-name>
<param-value>false</param-value>
<description>Set this variable to true if you would like the web application to scan for external repositories (Mercurial)</description>
</context-param>

The text coloured red are the parts where you need to make modifications. The tags in blue indicate where the XML has originally been commented out by <!-- and --> you'll have to take them away.

Once that's done, you'll have to rezip the .war file back in place, and put it into Tomcat's webapps directory:

# zip -r source.war ./
# mv source.war /usr/share/tomcat5.5/webapps

After which, we'll need to configure our source code for OpenGrok to use, and set it up:

# cd /opengrok/source
# cp -r /your/source/code/ .
# java -Xmx1524m -jar opengrok.jar -W /opengrok/configuration.xml -P -S -v -s /opengrok/source -d /opengrok/data

This will generate the list of indices that allows OpenGrok to cross reference your source code. With that done, the final task is to setup Tomcat so that it has correct privileges. Append the following lines to /etc/tomcat5.5/04webapps.policy:

grant codeBase "file:${catalina.home}/webapps/source/-" {
    permission java.security.AllPermission;
};

grant codeBase "file:${catalina.home}/webapps/source/WEB-INF/lib/-" {
    permission java.security.AllPermission;
};

I'm just being cavalier here by giving full security access to OpenGrok, which should be safe. But I only doing it given because my application is firewalled from the outside world, so do make your own security adjustments appropriately! Once that's done, restart Tomcat:

# /etc/init.d/tomcat5.5 restart

You should now have a functioning own OpenGrok respository to play with! However if you get an error with the stack trace showing Apache Lucene not being able to create a file, grant full permissions to the data directory:

# chmod -R 777 /opengrok/data/