You are not signed in. or register.

Project: OpenGrok

How to install & use

{OpenGrok can be installed and used under different use cases, let's go through some of the most common ones.
Note, that you need the index setup no matter what use case you plan to use.
This document is a live document, we are updating it as the new versions/changes come out (note the date at the right bottom of the page).

Requirements

You need the following:

JDK 1.5 or higher
{OpenGrok binaries from files section(either the package for Solaris, or .tar.gz with binaries, NOT the src! )
Exuberant Ctags for analysis
A servlet container like GlassFish or Tomcat (5.x or later)
If history is needed, appropriate binary (& repository in cvs/cvn case) must be present on the system (e.g. Subversion or Mercurial or SCCS ... )

INDEX setup : Standalone Swing Application / Command line installation

After installing the package (e.g. pkgadd -d ./OSOLopengrok-0.?.pkg) or untgzing the binaries in your target directory (e.g. cd your_target_dir ; gzcat opengrok-0.?.tar.gz | tar xf - ), you just need to create the index and then you can use either the cli or the java swing gui of opengrok.

Creating the index

OpenGrok's command line use is a typical case where OpenGrok is deployed as indexing service on a webserver for an active source repository, which is updated automatically using scheduled cron jobs.
SRC_ROOT refers to the directory containing your source tree. OpenGrok analyzes the source tree and builds a search index along with cross-referenced hypertext versions of the source files. These generated data files will be stored in DATA_ROOT directory.
Project concept - one project is one directory underneath SRC_ROOT and usually contains a checkout of a project(or it's branch, version, ...) sources, it can have several attributes(in its XML description), interface is being stabilized. Projects effectively replace need for more web applications with opengrok .war and leave you with one indexer and one web application serving MORE source code repositories - projects. A nice concept is to have directories underneath SRC_ROOT with a naming convention, thereby creating a good overview of projects (e.g. name-version-branch). Then you have a simple update script & simple index refresher script in place, which simplifies management of more repositories.
OpenGrok setup

Step.0 - Setting up the Sources.

Source base must be available locally for OpenGrok to work efficiently. No changes are required to your source tree. If the code is under CVS or SVN, OpenGrok requires the checked out source tree under SRC_ROOT.
Note: A local CVSROOT or SVN repository must be available. File history will not be fetched from a remote server for CVS & SVN!.
Note also that OpenGrok ignores symbolic links.

Step.1 - Populate DATA_ROOT Directory & create the project XML config file

Option 1. run.sh: There is a sample shell script run.sh that is suitable for using in a cronjob to run regularly. Modify the variables in the script to point appropriate directories. You need to add the project parameters though, unless you want a project less index (Note: currently index without a project xml file can be used only with web application! - 18.2.2008)

Option 2. opengrok.jar: You can also directly use the Java application. If the sources are all located in a directory SRC_ROOT and the data and hypertext files generated by OpenGrok are to be stored in DATA_ROOT with configuration.xml in DATA_ROOT as configuration XML file, run the verbose generation of index like this:

     $ java -Xmx1524m -jar opengrok.jar -W ${DATA_ROOT}/configuration.xml -P -S -v -s ${SRC_ROOT} -d ${DATA_ROOT}

Hint: web applications config in web.xml is reading the configuration out of /etc/opengrok/configuration.xml by default when it starts. It might make sense to set option -W to point to that file, since then you don't need to change ANYTHING in web.xml and it will save you configuration steps in tomcat or glassfish setup !

See opengrok.jar manual for more details.

Optional Step - Send the project XML config file to local web application

You can easily update configuration of your web application with latest project info, if it's listening on local port (e.g. WEBAPP_URL="localhost:2424" ). Just do:

     $ java -Xmx1524m -jar opengrok.jar -U ${WEBAPP_URL} -R ${DATA_ROOT}/configuration.xml -n

CLI - Command Line Interface Usage

You need to pass location of project file + the query to Search class, e.g. for fulltext search for project with above generated configuration.xml you'd do:

$ java -cp ./opengrok.jar org.opensolaris.opengrok.search.Search -R ${DATA_ROOT}/configuration.xml -f fulltext_search_string

For quick help run:

$ java -cp ./opengrok.jar org.opensolaris.opengrok.search.Search

Sample search:

Glassfish(Sun Java Application Server) + Opengrok

Download a stable GlassFish version or Sun Java Application Server. Refer to its install instructions on how to start it and create a domain.
Now you need to prepare your web application .war for either project use or project less use:

To configure the webapp source.war, look into the parameters defined in WEB-INF/web.xml of source.war (use jar or zip/unzip or your preffered zip tool to get into it - e.g. extract the web.xml file from source.war ($ unzip source.war WEB-INF/web.xml) file, edit web.xml and re-package the jar file (zip -u source.war WEB-INF/web.xml) ) file and change those web.xml parameters appropriately. These sample parameter need modifying(there are more options, refer to manual or read param comments).

Sample web.xml configure notes:

1. source.war using project feature web.xml modifications

CONFIGURATION - the absolute path to XML file containing project configuration (e.g. /DATA_ROOT/configuration.xml )
ConfigAddress - port for remote updates to configuration, optional, but advised(since there is no authentification) to be set to localhost:<some_port> (e.g. localhost:2424), if you choose some_port below 1024 you have to have root privileges

2. source.war web application without projects web.xml modifications

SRC_ROOT the absolute path name of the root directory of your source tree
DATA_ROOT absolute path of the directory where OpenGrok data files are stored
comment out CONFIGURATION and ConfigAddress parameters (enclosing them in  )

Note: beware, SRC_ROOT and DATA_ROOT parameters are commented out (enclosed in  ), so you need to uncomment them first.

Deploy the modified .war file:

Option 1: Use browser and log into glassfish web administration interface: Common Tasks / Applications / Web Applications , button Deploy and point it to your source.war webarchive
Option 2: Copy the source.war file to GLASSFISH/domains/YOURDOMAIN/autodeploy directory, glassfish will try to deploy it "automagically".

Option 3: Use cli from GLASSFISH directory:

# ./bin/asadmin deploy /path/to/source.war

Congratulations, you should now be able to point your browser to your fresh opengrok installation (or use button Launch from web admin interface :-) )!

Tomcat + OpenGrok

Get Tomcat bits installed and start tomcat.

To configure the webapp source.war, look into the parameters defined in web.xml of source.war file and change them (see configure notes on different approaches) appropriately to suit your index setup.

Modify & deploy the modified .war file:

web.xml is the deployment descriptor for the web application. It is in a jar/zipped file named source.war, you should be able to do this:

Extract the web.xml file from source.war ($ unzip source.war WEB-INF/web.xml) file,
edit web.xml appropriately (see configure notes in glassfish steps) and re-package the jar file (zip -u source.war WEB-INF/web.xml).
Then copy the source.war file to TOMCAT/webapps directory.

Optional setup of security manager

On some linux distribution you need to setup permissions for SRC_ROOT and DATA_ROOT. Please check your tomcat documentation on this, or simply disable(your risk!) security manager for tomcat (e.g. in debian/ubuntu : in file /etc/default/tomcat5.5 set TOMCAT5_SECURITY=no ).
A sample approach is to edit /etc/tomcat5.5/04webapps.policy (or /var/apache/tomcat/conf/catalina.policy ) and set this(it will allow opengrok to for your opengrok webapp instance:

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;
};

Alternatively you can be more restrictive(haven't tested below with a complex setup(e.g. some versioning system which needs local access as cvs), if it will not work, please report to discuss):

grant codeBase "file:${catalina.home}/webapps/source/-" {
  permission java.util.PropertyPermission "subversion.native.library", "read";
  permission java.lang.RuntimePermission "loadLibrary.svnjavahl-1?;
  permission java.lang.RuntimePermission "loadLibrary.libsvnjavahl-1?;
  permission java.lang.RuntimePermission "loadLibrary.svnjavahl";
  permission java.util.PropertyPermission "disableLuceneLocks", "read";
  permission java.util.PropertyPermission "catalina.home", "read";
  permission java.util.PropertyPermission "java.io.tmpdir", "read";
  permission java.util.PropertyPermission "org.apache.lucene.lockdir", "read";
  permission java.util.PropertyPermission "org.apache.lucene.writeLockTimeout", "read";
  permission java.util.PropertyPermission "org.apache.lucene.commitLockTimeout", "read";
  permission java.util.PropertyPermission "org.apache.lucene.mergeFactor", "read";
  permission java.util.PropertyPermission "org.apache.lucene.minMergeDocs", "read";
  permission java.util.PropertyPermission "org.apache.lucene.*", "read";
  permission java.io.FilePermission "/var/lib/tomcat5/temp", "read";
  permission java.io.FilePermission "/var/lib/tomcat5/temp/*", "write";
  permission java.io.FilePermission "/var/lib/tomcat5/temp/*", "delete";
};

grant codeBase "file:${catalina.home}/webapps/source/WEB-INF/lib/-" {
  permission java.util.PropertyPermission "subversion.native.library", "read";
  permission java.lang.RuntimePermission "loadLibrary.svnjavahl-1?;

  permission java.util.PropertyPermission "disableLuceneLocks", "read";
  permission java.util.PropertyPermission "catalina.home", "read";
  permission java.util.PropertyPermission "java.io.tmpdir", "read";
};

grant codeBase "file:${catalina.home}/webapps/source/WEB-INF/classes/-" {
  permission java.util.PropertyPermission "subversion.native.library", "read";
  permission java.lang.RuntimePermission "loadLibrary.svnjavahl-1?;
  permission java.util.PropertyPermission "disableLuceneLocks", "read";
  permission java.util.PropertyPermission "catalina.home", "read";
  permission java.util.PropertyPermission "java.io.tmpdir", "read";
};

Thanks to Vincent Liu & Flo.

Congratulations, you should now be able to point your browser to your fresh opengrok installation! :-)

OpenSolaris