Skip to content

How to install OpenGrok

Jump to bottom Edit New page
vladak edited this page Feb 11, 2013 · 1 revision

{OpenGrok can be installed and used under different use cases, we will just show how to use the wrapper script. Advanced usage depends on your knowledge of running java applications and command line options of {OpenGrok. 

 Note, that you **need** the **index setup** no matter what use case you plan to use. Without indexes {Opengrok will be simply useless.
 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).

Table of Contents

Requirements

You need the following:

Recommended links to read for advanced users

INDEX and web application setup

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 the command line interface to grok your sources.

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.
    • 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), note that interface of projects is being stabilized so it can change. 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.
 [[image:setup-project.png]]

__Step.0__ - Setting up the Sources. Having the web application container ready.

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 if opengrok version less than 0.7) repository must be available. File history will not be fetched from a remote server for CVS (& SVN if opengrok version less than 0.7) !. For newer opengrok versions you must use option -r on for remote repositories history to be indexed, also note this can be more resource(time,cpu,network) demanding.
Note also that OpenGrok ignores symbolic links.

Please install web application container of your choice (e.g. Tomcat>>http://tomcat.apache.org/,GlassFish>>https://glassfish.dev.java.net/ or Sun Java Application Server>>http://www.sun.com/software/products/appsrvr) before going to the next step and make sure it's started.

__Step.1__ - Deploy the web application

We provided you with OpenGrok wrapper script, which should aid in deploying the web application. Please change to opengrok directory (can vary on your system)

and run

This command will do some sanity checks and will deploy the source.war in its directory to one of detected web application containers. Please follow the error message it provides. If it fails to discover your container, please refer to optional steps on changing web application properties, which has manual steps on how to do this. Alternatively use OPENGROK_TOMCAT_BASE environment variable, e.g.

Note that OpenGrok script expects the directory /var/opengrok to be available to user running opengrok with all permissions. In root user case it will create all the directories needed, otherwise you have to manually create the directory and grant all permissions to the user used.

__Step.2__ - Populate DATA_ROOT Directory, let the indexer generate the project XML config file, update configuration.xml to your web app

Second step is to just run the indexing (can take a lot of time). After this is done, indexer automatically attempts to upload newly generated configuration to the web application. Most probably you will not be able to use {Opengrok before this is done.

Please change to opengrok directory (can vary on your system)

and run, if your SRC_ROOT is prepared under /var/opengrok/src

otherwise (if SRC_ROOT is in different directory) run:

Above command should try to upload latest index status reflected into configuration.xml to a running source web application. Once above command finishes without errors(e.g. SEVERE: Failed to send configuration to localhost:2424 ), you should be able to enjoy your opengrok and search your sources using latest indexes and setup.

Congratulations, you should now be able to point your browser to http://:/source to work with your fresh opengrok installation! :-)

\\

At this time we'd like to point out some customization to OpenGrok script for advanced users. A common case would be, that you want the data in some other directory than /var/opengrok. This can be easily achieved by using environment variable OPENGROK_INSTANCE_BASE . E.g. if my opengrok data directory is /tank/opengrok and my source root is in /tank/source and I'd like to get more verbosity I'd run the indexer as:

Since above will also change default location of config file, beforehands(or restart your web container after creating this symlink) I suggest doing below for our case of having opengrok instance in /tank/opengrok :

A lot more customizations can be found inside the script, you just need to have a look at it>>http://src.opensolaris.org/source/xref/opengrok/trunk/OpenGrok, eventually create a configuration>>http://src.opensolaris.org/source/xref/opengrok/trunk/OpenGrok#75 out of it and use OPENGROK_CONFIGURATION environment variable to point to it. Obviously such setups can be used for nightly cron job updates of index or other automated purposes.

Optional info

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:

 For quick help run:

 Sample search:

image:CLI-search.png

Optional need to change web application properties or name 

 You might need to modify the web application if you don't store the configuration file in the default location (/var/opengrok/etc/configuration.xml).

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 parameters need modifying(there are more options, refer to manual>>Project opengrok.WebHome or read param comments).

  • CONFIGURATION - the absolute path to XML file containing project configuration (e.g. /var/opengrok/etc/configuration.xml )
  • ConfigAddress - port for remote updates to configuration, optional, but **advised(since there is no authentification)** to be set to **localhost**:<some_port></some_port> (e.g. localhost:2424), if you choose some_port below 1024 you have to have root privileges
If you need to change name of the web application from source to something else you need to use special option -w <new_name></new_name> for indexer to create proper xrefs, besides changing the .war file name. Examples below show just deploying source.war, but you can use it to deploy your new_name.war too.

Deploy the modified .war file in glassfish/Sun Java App Server:

  • **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:

Deploy the modified .war file in tomcat:

  • just copy the source.war file to //TOMCAT_INSTALL///webapps directory.

Optional setup of security manager for tomcat 

 On some linux distribution you need to setup permissions for SRC_ROOT and DATA_ROOT. Please check your [[tomcat documentation>>http://tomcat.apache.org/tomcat-5.5-doc/security-manager-howto.html]] 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 give opengrok all permissions) 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>>http://www.opensolaris.org/jive/forum.jspa?forumID=117]]):

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.
Add a custom footer
Add a custom sidebar
Clone this wiki locally