Opengrok的安装及配置

[toc]

Changelog:
* 2019-12-28：添加5.3 如何控制访问权限

Opengrok是一款配置非常方便的读代码工具。其便利性的最根本原因是它是基于web运行的，也就是说只要有一个web服务器，搭建好opengrok之后，你可以通过电脑或者手机的浏览器随时随地的看代码。

此外，它还有如下优点：

可使用正则表达式搜索关键字；
可方便的打开多个网页对照看代码，而不像vi或者source insight一样需要跳转，后退来查看；
支持多种代码管理工具（git、svn等），可方便查看提交历史，提交diff，每行代码的提交SHA1。

废话少说，先上两张截图来对其有一个直观的印象：
index
diff

下面我们以ubuntu 上安装为例，来详细介绍Opengrok的安装及使用。
环境需求：

Ubuntu 16.04.5 LTS
python3执行环境

一、必备软件安装

Opengrok的运行需要以下软件，因此安装前我们需要确保它们被正确安装。各个软件的安装方法简单列举如下。

1.1 安装oracle java 8

1.1.1 命令行安装

sudo add-apt-repository ppa:webupd8team/java
sudo apt-get update
sudo apt-get install oracle-java8-installer
sudo apt-get install oracle-java8-set-default

1.1.2 源码安装（推荐）

如果上述方法安装失败，可以手动安装，安装方法如下：
* 下载oracle-java8的安装文件jdk-8u221-linux-x64.tar.gz，下载链接：https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html

安装方法很简单，只需要将上述压缩包解压，然后设置环境变量即可。

tar zxvf jdk-8u221-linux-x64.tar.gz
mv jdk1.8.0_221 /usr/bin    # /usr/bin为自己制定的安装目录

切换root用户(opengrok运行需要用root用户运行，为了保证root用户能够使用java命令，必须先切换成root用户再进行后续配置)，打开~/.bashrc, 修改环境变量：

su root
vi ~/.bashrc

在上述文件中添加一下内容：

export JAVA_HOME=/usr/bin/jdk1.8.0_221  
export JRE_HOME=$JAVA_HOME/jre
export CLASSPATH=$JAVA_HOME/lib:$JRE_HOME/lib:$CLASSPATH
export PATH=$JAVA_HOME/bin:$PATH

添加完毕之后，关闭文件，并执行source ~/.bashrc使上述配置生效。

1.2 安装tomcat8

1.2.1 命令行安装

sudo apt-get install tomcat8 -y

1.2.2 源码安装（推荐）

下载源码
下载地址：https://tomcat.apache.org/download-80.cgi
安装

tar zxvf apache-tomcat-8.5.37.tar
sudo mv apache-tomcat-8.5.37/ /opt/apache-tomcat-8.5.37
sudo ln -s /opt/apache-tomcat-8.5.37/ /opt/tomcat8
/opt/tomcat8/bin/startup.sh

1.3 安装universal-ctags

给代码建立索引时，要使用到universal-ctags工具，但是一般通过apt-get安装的都是exuberant-ctags，所以要先删除原有的ctags版本，然后安装universal-ctags.

1.3.1 卸载`exuberant-ctags`

sudo apt-get purge ctags

1.3.2 下载`universal-ctags`源码

git clone https://github.com/universal-ctags/ctags.git

1.3.3 编译及安装

cd ctags
./autogen.sh 
./configure
make
sudo make install

1.4 安装pip3

curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
sudo python3 get-pip.py

二、安装opengrok

安装过程很简单，只需要将源码下载，然后解压即可。
下载地址为：https://github.com/oracle/opengrok/releases

sudo tar zxvf opengrok-1.1.2.tar.gz -C /opt
sudo mv /opt/opengrok-1.1.2 /opt/opengrok
cd /opt/opengrok/tools
sudo  python3 -m pip install opengrok-tools.tar.gz

三、配置opengrok

3.1 创建opengrok所需要的目录

cd /opt/opengrok
sudo mkdir -p /opt/opengrok/etc         # Opengrok配置文件目录
sudo mkdir -p /index/src                # Opengrok索引代码目录（可以指定任意目录）
sudo mkdir -p /opt/opengrok/database/data     # Opengrok索引数据目录

注：Opengrok可以索引多套独立的代码。因此，建议建立一个Opengrok索引代码目录（/index/src），将不同的代码分别放到单独的目录里，然后统一复制到Opengrok索引代码目录（/index/src）。

3.2 copy源码至Opengrok的src目录

sudo cp -rf /your/code/dir1 /your/code/dir2 /index/src

注：请将/your/code/dir1 /your/code/dir2改为代码的实际路径。

3.3 部署Opengrok

sudo cp /opt/opengrok/lib/source.war /opt/tomcat8/webapps

3.4 生成索引

sudo opengrok-indexer -J=-Djava.util.logging.config.file=/var/opengrok/logging.properties -a /opt/opengrok/lib/opengrok.jar --  -s /index/src -d /opt/opengrok/database/data -H -P -S -G -W /opt/opengrok/etc/configuration.xml -U http://localhost:8080/source

3.5 修改配置文件的路径

sudo vi /opt/tomcat8/webapps/source/WEB-INF/web.xml

修改Opengrok的config文件为真实的config文件路径：

10 <context-param>
11 <description>Full path to the configuration file where OpenGrok can read its configuration</description>
12 <param-name>CONFIGURATION</param-name>
13 <param-value>/opt/opengrok/etc/configuration.xml</param-value>
14 </context-param>

3.6 重启tomcat service

/opt/tomcat8/bin/shutdown.sh && /opt/tomcat8/bin/startup.sh

到此为止，Opengrok的安装已经全部结束，假如server的ip为192.168.10.4，这时，在浏览器中打开192.168.10.4:8080/source，就能够看到刚刚安装好的opengrok了。

四、卸载Opengrok

4.1 停止tomcat服务

/opt/tomcat8/bin/shutdown.sh

4.2 卸载tomcat并删除所有配置文件

sudo apt-get --purge remove tomcat8 -y
sudo rm -rf /opt/tomcat8/

4.3 删除Opengrok的配置文件及相关数据

sudo rm -rf /opt/opengrok/etc/configuration.xml /opt/opengrok/database

五、常见问题

5.1 如何更新索引数据

更新索引数据和生成索引的方法是一样的，命令如下：

sudo opengrok-indexer -J=-Djava.util.logging.config.file=/var/opengrok/logging.properties -a /opt/opengrok/lib/opengrok.jar --  -s /index/src -d /opt/opengrok/database/data -H -P -S -G -W /opt/opengrok/etc/configuration.xml -U http://localhost:8080/source

在更新完之后，最好重启一下tomcat：

/opt/tomcat8/bin/shutdown.sh && /opt/tomcat8/bin/startup.sh

5.2 如何重装Opengrok

很多时候会碰到一些莫名其妙的错误，如果实在没有办法解决，就只有重装Opengrok了。重装的时候务必按照四、卸载Opengrok里写的方法保证所有的配置文件都删除干净，然后重新执行三、配置opengrok的步骤即可。

注：/your/code/dir为索引代码时的路径（即5.1中-s参数后的代码路径）。

5.3 如何控制访问权限

很多时候为了方便访问，Opengrok经常会搭建到公网服务器上，但是如果又不想公开代码，那么该如何禁止其他人访问呢？其实tomcat提供了控制访问权限的方法。具体如下：
* 打开tomcat的配置文件server.xml（/opt/tomcat8/conf文件夹下）
* 找到Host标签，具体路径为Server -> Service -> Engine -> Host。
* 在其下添加下列代码：

< Valve allow="xxx.xxx.xxx.xxx|localhost|127.0.0.1" className="org.apache.catalina.valves.RemoteAddrValve" deny="" />

其中，allow字段是访问白名单。deny是访问黑名单。多个IP需要用|分隔开。

六、常见错误

6.1 在执行索引源码的时候出现”Exception: Cannot find Java”的错误

opengrok

错误原因 ：root用户无法使用java命令
解决办法 :
1. 按照1.1 安装oracle java 8描述的方法重新安装oracle 8, 确保执行sudo java -v能够正确输出java版本信息；
2. 如果执行sudo java -v能够正确输出java版本信息，还是报上述错误，则先切换到root用户，然后执行索引源码的命令。

6.2 在索引源码时出现”Couldn’t notify the webapp…”