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/