Skip to content

Webapp configuration

Jump to bottom
Vladimir Kotal edited this page Nov 3, 2020 · 67 revisions

Table of contents

Include files

There are various files that can be placed under data root directory (e.g. /var/opengrok/data on Unix systems) that affect how the web pages generated by the webapp will look like:

  • header_include - The contents of this file will be appended to the header of each web page after the OpenGrok logo element.
  • footer_include - The contents of this file will be appended to the footer of each web page after the information about last index update.
  • body_include - The contents of this file will be inserted above the footer of the web application's "Home" page.
  • error_forbidden_include - The contents of this file will be displayed as the error page when the user is forbidden to see a particular project with HTTP 403 code.
  • http_header_include - The content of this file will be inserted into the <head> after <script></script>

The directory where to find include files can be configured in the read-only configuration with the includeRoot property.

In general, be careful with what you put inside these files. Especially the header_include is sensitive - if you put too high elements in there, it could corrupt the rendering of the pages.

webapp parameters

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 preferred 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 or read param comments).

To configure the webapp source.war, look into the parameters defined in web.xml of source.war file and change them (see note1) appropriately.

  • CONFIGURATION – the absolute path to XML file containing project configuration (e.g. /var/opengrok/etc/configuration.xml)

Changing webapp parameters

web.xml is the deployment descriptor for the web application. It is in a Jar file named source.war, you can change it as follows:

  • Option 1: Unzip the file to TOMCAT/webapps/source/ directory and change the source/WEB-INF/web.xml and other static html files like index.html to customize to your project.

  • Option 2: Extract the web.xml file from source.war file

    unzip source.war WEB-INF/web.xml

    edit web.xml and re-package the jar file.

    zip -u source.war WEB-INF/web.xml

    Then copy the war files to TOMCAT/webapps directory.

  • Option 3: Edit the Context container element for the webapp

    Copy source.war to TOMCAT/webapps

    When invoking OpenGrok to build the index, use -w <webapp> to set the context. If you change this(or set using OPENGROK_WEBAPP_CONTEXT) later, FULL clean reindex is needed.

    After the index is built, there's a couple different ways to set the Context for the servlet container:

    • Add the Context inside a Host element in TOMCAT/conf/server.xml

      <Context path="/<webapp>" docBase="source.war">
    <Parameter name="DATA_ROOT" value="/path/to/data/root" override="false" />
    <Parameter name="SRC_ROOT" value="/path/to/src/root" override="false" />
    <Parameter name="HEADER" value='...' override="false" />
</Context>

    • Create a Context file for the webapp

      This file will be named <webapp>.xml.

      For Tomcat, the file will be located at: TOMCAT/conf/<engine_name>/<hostname>, where <engine_name> is the Engine that is processing requests and <hostname> is a Host associated with that Engine. By default, this path is TOMCAT/conf/Catalina/localhost or TOMCAT/conf/Standalone/localhost.

      This file will contain something like the Context described above.

Changing webapp 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). This can be conveniently done using the opengrok-deploy script by supplying the path to the configuration.

If you need to change name of the web application from source to something else, just deploy source.war as new_name.war.

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 "auto magically".

  • Option 3: Use cli from GLASSFISH directory:

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

Deploy the modified .war file in tomcat:

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

Default projects

It is possible to set a list of projects that will be selected by default in the UI if the user did not previously select any. Once the user selects a project, this setting will be stored in a cookie and will override the set of default projects.

To specify default projects, either use:

  • the -p option when running the indexer directly from opengrok.jar file. Can be specified multiple times.

Path Descriptions

OpenGrok can use path descriptions in various places (e.g. while showing directory listings or search results).

The descriptions are contained in plain text file normally called paths.tsv.

The file contains descriptions for directories - one per line. Path to the directory and its description are separated by tab. The path to the directory is absolute path under the source root directory.

For example, if the source root directory contains the following directories:

  • foo
  • bar
  • bar/blah
  • random
  • random/code

then the paths.tsv file contents can look like this:

/foo  source code for foo
/bar  source code for bar
/bar/blah source code for blah

Note that just some paths can have a description.

For the path descriptions to be put into effect use RESTful API call like so:

curl -i -X POST -H "Content-Type: text/plain" \
    --data-binary "@/opengrok/etc/paths.tsv" \
    http://localhost:8080/source/api/v1/system/pathdesc

where /opengrok/etc/paths.tsv is path to the plain text file with path descriptions.

Configuration tunables

These can be set in https://github.com/OpenGrok/OpenGrok/wiki/Read-only-configuration

Tunable Type Since version Meaning
navigateWindowEnabled boolean 1.1 display navigate window automatically when browsing xrefs, can be overridden on project level (see https://github.com/oracle/opengrok/wiki/Per-project-configuration)
userPage String XXX URL used to display links to user info in the Author column in the History view, e.g. http://www.myserver.org/viewProfile.jspa?username=" . Can be also controlled with indexer --userPage option.
userPageSuffix String XXX Suffix for the userPage URL. Can be also controlled with indexer --userPageSuffix option.
bugPage String XXX URL used to display links to bugs detected with bugPattern in the Comments column in History view.
bugPattern String XXX regular expression pattern to detect bug number that will be appended to bugPage.
reviewPage String XXX URL used to display link to architecture review cases in the Comments column in History view.
reviewPattern String XXX regular expression pattern to extract architecture review case identification which will be appended to the URL in reviewPage.
pluginDirectory String XXX absolute path of authorization framework plugin directory
allowLeadingWildcard boolean XXX If set to true, allow queries to start with wildcards (e.g. * or ?).
authorizationWatchdogEnabled boolean XXX If set to true, observe changes to the authorization plugin directory and reload plugins if there was any change.
messageLimit int XXX maximum number of messages in the system (see https://github.com/oracle/opengrok/wiki/Web-services)
interactiveCommandTimeout int (seconds) 1.4.4 timeout of external commands executed from the UI
webappStartCommandTimeout int (seconds) 1.4.4 timeout of external commands executed during web application start
restfulCommandTimeout int (seconds) 1.4.4 timeout of external commands executed via RESTful API
includeRoot string XXX root directory of include files (see the Include files section above)
chattyStatusPage boolean XXX display verbose information on the status page (e.g. http://YOURHOST:8080/source/status.jsp), for instance the details of the authorization stack

Optional setup of security manager for Tomcat

On some Linux distributions you need to setup permissions for source 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 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 through Discussions.

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

OpenGrok

Clone this wiki locally