Webapp configuration

Java system properties

The web app needs to be able to execute Source Code Management commands in order to perform repository invalidation and other tasks like getting historical contents for files (e.g. in order to display a diff). If a SCM command is in location that the application container cannot readily find, this is done by passing Java option that sets a system property. For Tomcat this is done by adding them to JAVA_OPTS environment variable defined in setenv.sh located in CATALINA_BASE/bin.

For the list of properties see https://github.com/oracle/opengrok/wiki/Indexer-configuration#java-system-properties

Logging

In the webapp logging config (logging.properties file withing the application server configuration) you can set the log levels of related classes, e.g.:

org.opengrok.level = INFO
opengrok.auth.level = INFO

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. Take a look at https://github.com/oracle/opengrok/issues/3777 on how to modify the overall header height for scopes to work properly.

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 in search results).

For the path descriptions to be put into effect use RESTful API, in particular the /system/pathdesc endpoint.

For example call it like so:

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

where /opengrok/etc/paths.json is path to the file with path descriptions in JSON format. These descriptions will replace any pre-existing descriptions.

The web application will take the descriptions and stores them in the dtags.eftar file under the data root. Next time the web application is redeployed, it will read the contents of the file and apply the descriptions. So, it is only necessary to invoke the API endpoint when path description update is needed.

Configuration tunables

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

Tunable	Type	Meaning
`navigateWindowEnabled`	`boolean`	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`	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`	Suffix for the `userPage` URL. Can be also controlled with indexer `--userPageSuffix` option.
`bugPage`	`String`	URL used to display links to bugs detected with `bugPattern` in the Comments column in History view. This is also configurable on per project level.
`bugPattern`	`String`	regular expression pattern to detect bug number that will be appended to `bugPage`. This is also configurable on per project level.
`reviewPage`	`String`	URL used to display link to architecture review cases in the Comments column in History view. This is also configurable on per project level.
`reviewPattern`	`String`	regular expression pattern to extract architecture review case identification which will be appended to the URL in `reviewPage`. This is also configurable on per project level.
`pluginDirectory`	`String`	absolute path of authorization framework plugin directory
`allowLeadingWildcard`	`boolean`	If set to `true`, allow queries to start with wildcards (e.g. `*` or `?`).
`authorizationWatchdogEnabled`	`boolean`	If set to `true`, observe changes to the authorization plugin directory and reload plugins if there was any change.
`messageLimit`	`int`	maximum number of messages in the system (see https://github.com/oracle/opengrok/wiki/Web-services)
`interactiveCommandTimeout`	`int`	timeout in seconds of external commands executed from the UI. Default is 30 seconds.
`webappStartCommandTimeout`	`int`	timeout in seconds of external commands executed during web application start. Default is 5 seconds.
`restfulCommandTimeout`	`int`	timeout in seconds of external commands executed via RESTful API. Default is 60 seconds.
`includeRoot`	`String`	root directory of include files (see the Include files section above)
`chattyStatusPage`	`boolean`	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<String>`	Authentication Bearer tokens. These are necessary to access some parts of the RESTful API.
`allowInsecureTokens`	`boolean`	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`	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`	path to Universal ctags binary. Needed for the `webappCtags` tunable.
`repositoryInvalidationParallelism`	`int`	This is used to set the concurrency level for invalidating repositories. This is performed e.g. whenever new configuration is set in the web application so that the web application has fresh view of projects. Typically this happens at the end of the indexing (if using the -U Indexer option). To alleviate the load caused by this invalidation process, this property can be set to value lower than the default. On web app startup, `indexerParallelism` tunable is used instead. The default value is half of the number of available processors on the machine.
`serverName`	`String`	Used to set server name in an environment where the application server runs behind reverse proxy. This is needed to generate correct URLs for OpenSearch and RSS.
`contextLimit`	`int`	total number of context lines per file to show in search results in cases where it is limited. Default is 10.
`contextSurround`	`int`	number of context lines to show before or after any match in search results. Default is 0.
`fetchHistoryWhenNotInCache`	`boolean`	avoid generating history for individual files when indexing. This prevents excess commands if the history log for top-level directory of a project cannot be retrieved for some reason (e.g. the command to get the history log fails) at the cost of not having history for given project available (if projects are enabled). This is specific to SCMs that can generate history for directories (e.g. Mercurial, Git, ...).
`displayRepositories`	`boolean`	If false, do not display listing or projects/repositories on the index page. Default true. This is handy if there is a huge amount of repositories/projects to keep the index page loading/rendering time low.
`indexCheckTimeout`	`int`	How many seconds to wait for the check of index(es) during web app startup. Default value is 60 seconds.
`useHistoryCacheForDirectoryListing`	`boolean`	whether to display dates in the directory listing from history cache. When active, the dates for directories will be omitted. True by default, however it requires repository to be configured with merge changesets enabled (see `mergeCommitsEnabled` on Indexer configuration) for this feature to be active.

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>

OpenGrok

Provide feedback

Saved searches

Use saved searches to filter your results more quickly