Skip to content

Webapp configuration

Jump to bottom
Vladimir Kotal edited this page Jan 28, 2022 · 67 revisions

Table of contents

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

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 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. This is also configurable on per project level.
bugPattern String XXX regular expression pattern to detect bug number that will be appended to bugPage. This is also configurable on per project level.
reviewPage String XXX 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 XXX 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 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 1.4.4 timeout in seconds of external commands executed from the UI. Default is 30 seconds.
webappStartCommandTimeout int 1.4.4 timeout in seconds of external commands executed during web application start. Default is 5 seconds.
restfulCommandTimeout int 1.4.4 timeout in seconds of external commands executed via RESTful API. Default is 60 seconds.
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<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.
repositoryInvalidationParallelism int 1.7.24 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 1.7.25 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 XXX total number of context lines per file to show in search results in cases where it is limited. Default is 10.
contextSurround int XXX number of context lines to show before or after any match in search results. Default is 0.
fetchHistoryWhenNotInCache boolean XXX 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 XXX 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.

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

Clone this wiki locally