Ubuntu 24.04 部署 Opengrok

注意：这篇文章上次更新于442天前，文章内容可能已经过时。

This article was last updated442 days ago, the content may be outdated.

Opengrok 官方文档

https://github.com/oracle/opengrok/wiki/How-to-setup-OpenGrok

Opengrok 的官方文档是全英文的，本文将按照官方文档的教程进行最基础的部署。

OpenGrok Official Documentation

https://github.com/oracle/opengrok/wiki/How-to-setup-OpenGrok

OpenGrok’s official documentation is entirely in English; this article follows the official docs for the most basic deployment.

环境准备

安装 Java

opengrok 要求 Java 版本为 17 到 21 之间，使用如下命令安装 Java 17。

1 2	$ sudo apt update $ sudo apt install openjdk-17-jdk

检查 Java 版本。

$ java -version
openjdk version "17.0.15" 2025-04-15
OpenJDK Runtime Environment (build 17.0.15+6-Ubuntu-0ubuntu124.04)
OpenJDK 64-Bit Server VM (build 17.0.15+6-Ubuntu-0ubuntu124.04, mixed mode, sharing)

下载 Opengrok 二进制文件

从 Opengrok 的 GitHub Releases 页面下载最新的二进制文件。

https://github.com/oracle/opengrok/releases

将下载的文件解压备用。

下载 Ctags

Opengrok 需要 Ctags 来解析代码，创建索引。

这里 Opengrok 官方给出 3 点提示：

不建议使用太新的版本，可能会导致一些兼容性问题。
如果是 Linux 系统，不建议从 snap 安装。
如果是 Windows 系统，建议使用 Chocolatey 安装。

我这里是 Ubuntu 系统，从 ctags nightly build 仓库下载 ctags。

https://github.com/universal-ctags/ctags-nightly-build/releases/download/2025.06.02%2Bc06d333b3162660694b26604a364cdab89e2010e/uctags-2025.06.02-linux-x86_64.release.tar.gz

下载之后解压备用。

下载 Tomcat

Opengrok 需要 Tomcat 来运行 Web 界面。

官方要求使用 Tomcat 10.x 版本，可以从 Apache Tomcat 的官网上下载。

https://tomcat.apache.org/download-10.cgi

下载 .tar.gz 文件，解压备用。

部署 Opengrok

首先创建 opengrok 目录树，opengrok 的所有文件都放在这个目录下。

1	$ sudo mkdir -p /opt/opengrok/{data,src,dist,etc,log}

将解压后的 opengrok 放在 /opt/opengrok/dist 目录下。
复制 opengrok 的配置文件到 /opt/opengrok/etc 目录下。

1	$ sudo cp /opt/opengrok/dist/doc/logging.preperties /opt/opengrok/etc/

在 /opt/opengrok/etc/logging.properties 文件中，需要修改日志文件的路径。

修改后的内容如下：

# default file output is in user's home directory.
#java.util.logging.FileHandler.pattern = %hjava%u.log
####### 修改这一行 #######
java.util.logging.FileHandler.pattern = /opt/opengrok/log/opengrok%g.%u.log     
#########################
java.util.logging.FileHandler.limit = 52428800
java.util.logging.FileHandler.count = 3
java.util.logging.FileHandler.level = ALL
#java.util.logging.FileHandler.formatter = java.util.logging.XMLFormatter
java.util.logging.FileHandler.formatter = org.opengrok.indexer.logger.formatter.SimpleFileLogFormatter

# Limit the message that are printed on the console to WARNING and above (default "quiet" mode).
# if verbose is set, then log INFO and above
java.util.logging.ConsoleHandler.level = WARNING
java.util.logging.ConsoleHandler.formatter = org.opengrok.indexer.logger.formatter.SimpleConsoleFormatter

添加源码文件

将需要索引的源码文件放在 /opt/opengrok/src 目录下。

可以采用 Git 克隆的方式，也可以直接将源码文件复制到该目录下。

安装 Web 应用

Opengrok 这里对 web 应用做了一个简单的介绍，它说 web 应用是一个 WAR 文件，部署一个 web 应用需要将 WAR 文件放在 Tomcat 的 webapps 目录下。
Tomcat 会自动解压 WAR 文件，并将其部署为一个 web 应用。

opengrok 已经打包好了一个 WAR 文件，放在了 /opt/opengrok/dist/lib/source.war, 我们只需要将这个 WAR 文件复制到 Tomcat 的 webapps 目录下即可。

1	$ sudo cp /opt/opengrok/dist/lib/source.war /opt/tomcat/webapps/

执行 Tomcat 的启动脚本，启动 Tomcat。

1	$ /opt/tomcat/bin/startup.sh

看到终端输出 Tomcat started.，说明 Tomcat 启动成功。

此时访问 http://localhost:8080/source，应该可以看到 Opengrok 的 Web 界面，但此时会看到一个错误的界面，目前为止这是一个期望的行为，因为我们还没有索引源码生成配置文件。

当 web 应用解压了 WAR 文件之后，它会搜索 WEB-INF/web.xml 文件来获取配置。

在这个 xml 文件中有一个 CONFIGURATION 参数，它指向了一个配置文件，web 应用会读取这个配置文件。
这里将配置文件指向 /opt/opengrok/etc/configuration.xml。

configuration.xml 文件是 Opengrok 的配置文件，它会由索引器来创建。

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
         http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
         version="3.1">

    <display-name>OpenGrok</display-name>
    <description>A wicked fast source browser</description>
    <context-param>
        <description>Full path to the configuration file where OpenGrok can read its configuration</description>
        <param-name>CONFIGURATION</param-name>
        <param-value>/opt/opengrok/etc/configuration.xml</param-value>
    </context-param>

创建索引

opengrok 的索引器的工作过程主要包含下面 3 个过程。

创建索引
生成配置文件
通知 web 应用新的索引已经创建

Opengrok 通过下面的命令来创建索引。

其中 /usr/local/bin/ctags 是 ctags 的路径，需要根据自己的实际情况进行替换。

java \
    -Djava.util.logging.config.file=/opt/opengrok/etc/logging.properties \
    -jar /opt/opengrok/dist/lib/opengrok.jar \
    -c /usr/local/bin/ctags \
    -s /opt/opengrok/src -d /opt/opengrok/data -H -P -S -G \
    -W /opt/opengrok/etc/configuration.xml -U http://localhost:8080/source

索引创建完成后，再次打开 http://localhost:8080/source，应该可以看到 Opengrok 的 Web 界面了。

Environment Preparation

Installing Java

OpenGrok requires Java version 17 to 21. Use the following commands to install Java 17.

1 2	$ sudo apt update $ sudo apt install openjdk-17-jdk

Check the Java version.

$ java -version
openjdk version "17.0.15" 2025-04-15
OpenJDK Runtime Environment (build 17.0.15+6-Ubuntu-0ubuntu124.04)
OpenJDK 64-Bit Server VM (build 17.0.15+6-Ubuntu-0ubuntu124.04, mixed mode, sharing)

Downloading the OpenGrok Binary

Download the latest binary from OpenGrok’s GitHub Releases page.

https://github.com/oracle/opengrok/releases

Extract the downloaded file and keep it for later use.

Downloading Ctags

OpenGrok needs Ctags to parse code and create the index.

OpenGrok’s official docs give 3 tips here:

Don’t use too-new versions; they may cause compatibility issues.
On Linux, don’t install from snap.
On Windows, use Chocolatey to install.

My system is Ubuntu, so I downloaded ctags from the ctags nightly build repository.

https://github.com/universal-ctags/ctags-nightly-build/releases/download/2025.06.02%2Bc06d333b3162660694b26604a364cdab89e2010e/uctags-2025.06.02-linux-x86_64.release.tar.gz

Download and extract it for later use.

Downloading Tomcat

OpenGrok needs Tomcat to run the web interface.

The official requirement is Tomcat 10.x, downloadable from the Apache Tomcat website.

https://tomcat.apache.org/download-10.cgi

Download the .tar.gz file and extract it for later use.

Deploying OpenGrok

First create the opengrok directory tree; all of opengrok’s files go under this directory.

1	$ sudo mkdir -p /opt/opengrok/{data,src,dist,etc,log}

Put the extracted opengrok into /opt/opengrok/dist.
Copy opengrok’s configuration file to /opt/opengrok/etc.

1	$ sudo cp /opt/opengrok/dist/doc/logging.preperties /opt/opengrok/etc/

In the /opt/opengrok/etc/logging.properties file, you need to change the log file path.

The modified content is as follows:

# default file output is in user's home directory.
#java.util.logging.FileHandler.pattern = %hjava%u.log
####### Modify this line #######
java.util.logging.FileHandler.pattern = /opt/opengrok/log/opengrok%g.%u.log     
#########################
java.util.logging.FileHandler.limit = 52428800
java.util.logging.FileHandler.count = 3
java.util.logging.FileHandler.level = ALL
#java.util.logging.FileHandler.formatter = java.util.logging.XMLFormatter
java.util.logging.FileHandler.formatter = org.opengrok.indexer.logger.formatter.SimpleFileLogFormatter

# Limit the message that are printed on the console to WARNING and above (default "quiet" mode).
# if verbose is set, then log INFO and above
java.util.logging.ConsoleHandler.level = WARNING
java.util.logging.ConsoleHandler.formatter = org.opengrok.indexer.logger.formatter.SimpleConsoleFormatter

Add source files

Put the source files to be indexed into /opt/opengrok/src.

You can either git clone or simply copy the source files into this directory.

Install the web application

OpenGrok gives a brief introduction to web applications: a web app is a WAR file, and deploying one means putting the WAR file into Tomcat’s webapps directory.
Tomcat will automatically extract the WAR file and deploy it as a web application.

OpenGrok has already packaged a WAR file at /opt/opengrok/dist/lib/source.war — we just need to copy this WAR file to Tomcat’s webapps directory.

1	$ sudo cp /opt/opengrok/dist/lib/source.war /opt/tomcat/webapps/

Run Tomcat’s startup script.

1	$ /opt/tomcat/bin/startup.sh

When the terminal outputs Tomcat started., Tomcat has started successfully.

Now visit http://localhost:8080/source — you should see OpenGrok’s web interface, but it will show an error page. So far this is expected behavior, because we haven’t indexed the source code to generate the configuration file yet.

After the web application extracts the WAR file, it searches for the WEB-INF/web.xml file to get its configuration.

In this XML file there is a CONFIGURATION parameter pointing to a configuration file, which the web app reads.
Here we point the configuration file to /opt/opengrok/etc/configuration.xml.

The configuration.xml file is OpenGrok’s configuration file, and it is created by the indexer.

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
         http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
         version="3.1">

    <display-name>OpenGrok</display-name>
    <description>A wicked fast source browser</description>
    <context-param>
        <description>Full path to the configuration file where OpenGrok can read its configuration</description>
        <param-name>CONFIGURATION</param-name>
        <param-value>/opt/opengrok/etc/configuration.xml</param-value>
    </context-param>

Creating the index

The OpenGrok indexer’s workflow mainly consists of the following 3 steps.

Create the index
Generate the configuration file
Notify the web application that a new index has been created

OpenGrok creates the index with the following command.

Here /usr/local/bin/ctags is the path to ctags; replace it according to your actual situation.

java \
    -Djava.util.logging.config.file=/opt/opengrok/etc/logging.properties \
    -jar /opt/opengrok/dist/lib/opengrok.jar \
    -c /usr/local/bin/ctags \
    -s /opt/opengrok/src -d /opt/opengrok/data -H -P -S -G \
    -W /opt/opengrok/etc/configuration.xml -U http://localhost:8080/source

After the index is created, open http://localhost:8080/source again — you should now see OpenGrok’s web interface.