Webapp configuration

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.

Note that the contents of these files are cached in the web application for performance. If you need to reload the content use the /system/includes/reload API endpoint - see https://github.com/oracle/opengrok/wiki/Web-services for details.

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. This should only be enabled on non-production instance as everyone would get to see the complete authorization stack.
`authenticationTokens`	set of String	1.5.9	Authentication Bearer tokens. These are necessary to access some parts of the RESTful API.
`allowInsecureTokens`	boolean	1.5.13	allow API tokens to be used over insecure channel (i.e. HTTP as opposed to HTTPS). Normally they are allowed over HTTPS only.
`webappCtags`	boolean	XXX	If set to true, the web application will generate definitions for historical versions of a file so that they can appear in the Navigate window. The default is `false`. This requires correct path to Universal ctags set via the `ctags` tunable.
`ctags`	String	XXX	path to Universal ctags binary. Needed for the `webappCtags` tunable.

Read-only configuration snippet for the authenticationTokens:

<void property="authenticationTokens">
   <void method="add">
    <string>bar</string>
   </void>
   <void method="add">
    <string>foo</string>
   </void>
  </void>

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly