# Technical Documentation: oracle/opengrok

> ℹ️ **Provenance:** Hybrid Fusion: `oracle/opengrok` (README + 4 In-Tree Chapters) · [CodeWiki Reference](https://codewiki.google/github.com/oracle/opengrok) · Recency: Active (< 180 days)

## 1. Project Overview & Quickstart (oracle/opengrok)

Copyright (c) 2006, 2025 Oracle and/or its affiliates. All rights reserved.


# OpenGrok - a wicked fast source browser
[](https://github.com/oracle/opengrok/actions)
[](https://sonarcloud.io/summary/new_code?id=org.opengrok%3Aopengrok-top)
[](https://sonarcloud.io/dashboard?id=org.opengrok%3Aopengrok-top)
[](https://opensource.org/licenses/CDDL-1.0)

- [OpenGrok - a wicked fast source browser](#opengrok---a-wicked-fast-source-browser)
  - [1. Introduction](#1-introduction)
  - [2. OpenGrok install and setup](#2-Installation)
  - [3. Information for developers](#3-information-for-developers)
  - [4. Authors](#4-authors)
  - [5. Contact us](#5-contact-us)
  - [6. Run as container](#6-run-as-container)

## 1. Introduction

OpenGrok is a fast and usable source code search and cross reference
engine, written in Java. It helps you search, cross-reference and navigate
your source tree. It can understand various program file formats and
version control histories of many source code management systems.

Official page of the project is on:
<https://oracle.github.io/opengrok/>

## 2. Installation

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

### 2. 1. Updating

OpenGrok uses [semantic versioning](https://semver.org/) and the version components further indicate more details about updating to newer version. The version scheme is *major.minor.micro* and change in any component is interpreted as:

- major - major backwards incompatible update, will require full reindex as well as configuration changes
- minor - full clean reindex of your repositories is needed (e. g. index format has changed)
- micro - redeploy web application

Generally it is possible to go backward only within the micro version.

## 3. Information for developers

See https://github.com/oracle/opengrok/wiki/Developer-intro and https://github.com/oracle/opengrok/wiki/Developers

## 4. Authors

The project has been originally conceived in [Sun Microsystems](https://en.wikipedia.org/wiki/Sun_Microsystems) by Chandan B.N.

For full list of contributors see https://github.com/oracle/opengrok/graphs/contributors

## 5. Contact us

Use the [GitHub Discussions](https://github.com/oracle/opengrok/discussions).

## 6. Run as container

You can run OpenGrok as a Docker container as described [here](docker/README.md).

## Contributing

This project welcomes contributions from the community. Before submitting a pull request, please [review our contribution guide](./CONTRIBUTING.md)

## Security

Please consult the [security guide](./SECURITY.md) for our responsible security vulnerability disclosure process

## License

Copyright (c) 2006, 2025 Oracle and/or its affiliates.

## Powered by

[](https://jb.gg/OpenSourceSupport)

## 2. In-Tree Documentation Chapters (oracle/opengrok)

## File: README.md

Copyright (c) 2006, 2025 Oracle and/or its affiliates. All rights reserved.


# OpenGrok - a wicked fast source browser
[](https://github.com/oracle/opengrok/actions)
[](https://sonarcloud.io/summary/new_code?id=org.opengrok%3Aopengrok-top)
[](https://sonarcloud.io/dashboard?id=org.opengrok%3Aopengrok-top)
[](https://opensource.org/licenses/CDDL-1.0)

- [OpenGrok - a wicked fast source browser](#opengrok---a-wicked-fast-source-browser)
  - [1. Introduction](#1-introduction)
  - [2. OpenGrok install and setup](#2-Installation)
  - [3. Information for developers](#3-information-for-developers)
  - [4. Authors](#4-authors)
  - [5. Contact us](#5-contact-us)
  - [6. Run as container](#6-run-as-container)

## 1. Introduction

OpenGrok is a fast and usable source code search and cross reference
engine, written in Java. It helps you search, cross-reference and navigate
your source tree. It can understand various program file formats and
version control histories of many source code management systems.

Official page of the project is on:
<https://oracle.github.io/opengrok/>

## 2. Installation

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

### 2. 1. Updating

OpenGrok uses [semantic versioning](https://semver.org/) and the version components further indicate more details about updating to newer version. The version scheme is *major.minor.micro* and change in any component is interpreted as:

- major - major backwards incompatible update, will require full reindex as well as configuration changes
- minor - full clean reindex of your repositories is needed (e. g. index format has changed)
- micro - redeploy web application

Generally it is possible to go backward only within the micro version.

## 3. Information for developers

See https://github.com/oracle/opengrok/wiki/Developer-intro and https://github.com/oracle/opengrok/wiki/Developers

## 4. Authors

The project has been originally conceived in [Sun Microsystems](https://en.wikipedia.org/wiki/Sun_Microsystems) by Chandan B.N.

For full list of contributors see https://github.com/oracle/opengrok/graphs/contributors

## 5. Contact us

Use the [GitHub Discussions](https://github.com/oracle/opengrok/discussions).

## 6. Run as container

You can run OpenGrok as a Docker container as described [here](docker/README.md).

## Contributing

This project welcomes contributions from the community. Before submitting a pull request, please [review our contribution guide](./CONTRIBUTING.md)

## Security

Please consult the [security guide](./SECURITY.md) for our responsible security vulnerability disclosure process

## License

Copyright (c) 2006, 2025 Oracle and/or its affiliates.

## Powered by

[](https://jb.gg/OpenSourceSupport)

---

## File: docker/README.md

# A Docker container for OpenGrok

## OpenGrok from official source

Built from official source: https://github.com/oracle/opengrok/releases/

You can learn more about OpenGrok at https://oracle.github.io/opengrok/

The container is available from DockerHub at https://hub.docker.com/r/opengrok/docker/

## When not to use it

This image is simple wrapper around OpenGrok environment. It is basically a small appliance. The indexer and the web container are **not** tuned for large workloads.

If you happen to have one of the following:

  - large source data (e.g. [AOSP](https://en.wikipedia.org/wiki/Android_Open_Source_Project) or the like)
  - stable service
  - Source Code Management systems not supported in the image (e.g. Perforce,
    Clearcase, etc.)
  - need for authentication/authorization

then it is advisable to run OpenGrok standalone or construct your own Docker
image based on the official one.

## Additional info about the image

* Tomcat 10
* JRE 21
* Configurable mirroring/reindexing (default every 10 min)

The mirroring step works by going through all projects and attempting to
synchronize all its repositories (e.g. it will do `git pull --ff-only` for Git
repositories).

Projects are enabled in this setup by default. See environment variables
below on how to change that.

The container processes run under non-root user.

### Indexer logs

The indexer/mirroring is set so that it does not log into files.
Rather, everything goes to standard (error) output. To see how the indexer
is doing, use the `docker logs` command.

### Source Code Management systems supported

- Bazaar
- CVS
- Git
- Mercurial
- Perforce
- RCS
- SCCS
- Subversion

### Tags and versioning

Each OpenGrok release triggers creation of new Docker image.

| Tag      | Note                                                    |
| -------- |:--------------------------------------------------------|
| `master` | corresponds to the latest commit in the OpenGrok repo   |
| `latest` | tracks the latest [released version](https://github.com/oracle/opengrok/releases) |
| `x.y.z`  | if you want to pin against a specific version           |
| `x.y`    | stay on micro versions to avoid reindexing from scratch |

If you want to stay on the bleeding edge, use the `opengrok/docker:master` image which is automatically refreshed whenever a commit is made to the OpenGrok source code repository. This allows to track the development. After all, this is what http://demo.opengrok.org/ is running.

For other use cases, stick to the other image tags.

## How to run

### From DockerHub

    docker run -d -v :/opengrok/src -p 8080:8080 opengrok/docker:latest

The container exports ports 8080 for OpenGrok.

The volume mounted to `/opengrok/src` should contain the projects you want to make searchable (in sub directories). You can use common revision control checkouts (git, svn, etc...) and OpenGrok will make history and blame information available.

## Directories

The image contains these directories:

| Directory | Description |
| --------- | ----------- |
`/opengrok/etc` | stores the configuration for both web app and indexer
`/opengrok/data` | data root - index data
`/opengrok/src` | source root - input data
`/scripts` | startup script and top level configuration. Do not override unless debugging.

At startup, the container generates an internal bearer token for OpenGrok web
application REST API calls using the operating system's cryptographic random
source. The token is not user configurable and is stored only in private files
under `/opengrok/etc` that are used by the startup, synchronization, and indexer
tooling. This is separate from the `REST_TOKEN` variable below, which protects
only the small `/reindex` trigger endpoint exposed by the container startup
program.

## Environment Variables

| Docker Environment Var. | Default value | Description |
| ----------------------- | ------------- | ----------- |
`SYNC_PERIOD_MINUTES` | 10 | Period of automatic synchronization (i.e. mirroring + reindexing) in minutes. Setting to `0` will disable periodic syncing (the sync after container startup will still be done).
`INDEXER_OPT` | empty | pass **extra** options to OpenGrok Indexer. For example, `-i d:vendor` will remove all the `*/vendor/*` files from the index. You can check the indexer options on https://github.com/oracle/opengrok/wiki/Python-scripts-transition-guide. The default set of indexer options is: `--remote on -P -H -W`. Do not add `-R` as it is used internally. Rather, see below for the `READONLY_CONFIG_FILE` environment variable.
`INDEXER_JAVA_OPTS` | empty | pass **extra** Java options to OpenGrok Indexer.
`NOMIRROR` | empty | To avoid the mirroring step, set the variable to non-empty value.
`URL_ROOT` | `/` | Override the sub-URL that OpenGrok should run on.
`WORKERS` | number of CPUs in the container | number of workers to use for syncing (applies only to setup with projects enabled)
`AVOID_PROJECTS` | empty | run in project less configuration. Set to non empty value disables projects. Also disables repository synchronization.
`REST_PORT` | 5000 | TCP port where simple REST app listens for GET requests on `/reindex` to trigger manual reindex.
`REST_TOKEN` | None | if set, the REST app will require this token as Bearer token in order to trigger reindex.
`READONLY_CONFIG_FILE` | None | if set, this [read-only configuration](https://github.com/oracle/opengrok/wiki/Read-only-configuration) file will be merged with configuration from this file. This is done when the container starts. This file has to be distinct from the default configuration file (`/opengrok/etc/configuration.xml`), e.g. `/opengrok/etc/read-only-config.xml`.
`CHECK_INDEX` | None | if set, the format of the index will be checked first. **If the index is not compatible with the currently running version, the data root will be wiped out and reindex from scratch will be performed.**
`API_TIMEOUT` | 8 | Timeout for synchronous API requests. In seconds.

To specify environment variable for `docker run`, use the `-e` option, e.g. `-e SYNC_PERIOD_MINUTES=30`

## Repository synchronization

To get more control over repository synchronization (enabled only when projects
are enabled), the `/opengrok/etc/mirror.yml` configuration file can be modified
as per the https://github.com/oracle/opengrok/wiki/Repository-synchronization
wiki.

## OpenGrok Web-Interface

The container has OpenGrok as default web app installed (accessible directly from `/`). With the above container setup, you can find it running on

http://localhost:8080/

The first reindex will take some time to finish. Subsequent reindex will be incremental so will take significantly less time.

## Using Docker compose

[Docker-compose](https://docs.docker.com/compose/install/) example:

```yaml
version: "3"

# More info at https://github.com/oracle/opengrok/docker/
services:
  opengrok:
    container_name: opengrok
    image: opengrok/docker:latest
    ports:
      - "8080:8080/tcp"
    environment:
      SYNC_PERIOD_MINUTES: '60'
    # Volumes store your data between container upgrades
    volumes:
       - '~/opengrok/src/:/opengrok/src/'  # source code
       - '~/opengrok/etc/:/opengrok/etc/'  # folder contains configuration.xml
       - '~/opengrok/data/:/opengrok/data/'  # index and other things for source code
```

Save the file into `docker-compose.yml` and then simply run

    docker-compose up -d

Equivalent `docker run` command would look like this:

```bash
docker run -d \
    --name opengrok \
    -p 8080:8080/tcp \
    -e SYNC_PERIOD_MINUTES="60" \
    -v ~/opengrok-src/:/opengrok/src/ \
    -v ~/opengrok-etc/:/opengrok/etc/ \
    -v ~/opengrok-data/:/opengrok/data/ \
    opengrok/docker:latest
```

## Build image locally

If you want to do your own development, you can build the image yourself:

    git clone https://github.com/oracle/opengrok.git
    cd opengrok
    docker buildx build -t opengrok-dev .

Then run the container:

    docker run -d -v :/opengrok/src -v :/opengrok/data -p 8080:8080 opengrok-dev

## Inspecting the container

You can get inside a container using the [command below](https://docs.docker.com/engine/reference/commandline/exec/):

```bash
docker exec -it <container> bash
```

Enjoy.

---

## File: plugins/README.md

# Authorization plugins

This directory contains various authorization plugins and supporting pieces.

For documentation look at:
  - https://github.com/oracle/opengrok/wiki/Authorization
  - https://github.com/oracle/opengrok/wiki/Authorization-plugins

---

## File: tools/README.md

# OpenGrok tools

Set of scripts to facilitate project synchronization and mirroring

The scripts require Python 3, and they rely on a binary/symlink `python3` to be
present that points to the latest Python 3.x version present on the system.

Currently, it is assumed that Python 3.9 and greater is used.

See https://github.com/oracle/opengrok/wiki/Repository-synchronization for more details.

# Content

This is a list of the binaries in this package.

```text
opengrok-config-merge
opengrok-deploy
opengrok-groups
opengrok
opengrok-indexer
opengrok-java
opengrok-mirror
opengrok-projadm
opengrok-reindex-project
opengrok-sync
```

# Development

## Environment

Prepare a virtual environment

```bash
python3 -m venv env
. env/bin/activate
```

## Developing

When you start developing, install the package in a development mode.

```bash
python -m pip install -e .
```

This installs the package however keeping the links directly to your source,
so you can edit the files and see the immediate results.

Start developing, making changes in files. Test your changes with calling the entry points.

```bash
export PYTHONPATH=`pwd`/src/main/python:$PYTHONPATH
opengrok-groups
opengrok-sync
```

It is necessary to set the python path as the python interpreter is not able to find the packages
in our provided structure on its own.

Also, you call the opengrok tools scripts by the entry points then (`opengrok-groups`, ...).
Calling directly the python script `groups.py` would lead to error related to relative imports.

Note that on macOS, you will need to install libgit2 library for the tests
to pass.

## Installation

Test installing your package into the local environment

```bash
python -m pip install .
# now you can try console scripts
opengrok-groups
opengrok-sync
```

or make a distribution tarball.

```bash
python -m build
ls -l dist/
```

Note that when run outside of Maven, this will use the 0.0.1 version for the package. 

### Installation on the target system

Use the distribution tarball and run `pip`.

```bash
python3 -m pip install opengrok-tools.tar.gz
```

This will download all dependencies and install the package to your local python3 modules.
You can use console scripts to run the package binaries.

#### Installing to a specified directory

You can also install the tools to a specified directory, we suggest you to use the python virtual environment for it.

```bash
cd /opt/opengrok
python3 -m venv opengrok-tools
opengrok-tools/bin/python -m pip install opengrok-tools.tar.gz
```

This will install the package and all the dependencies under the `/opt/opengrok/opengrok-tools` directory.
You can then call the scripts with

```bash
/opt/opengrok/opengrok-tools/bin/opengrok-indexer
/opt/opengrok/opengrok-tools/bin/opengrok-groups
...
```

#### Uninstalling

```bash
python3 -m pip uninstall opengrok_tools
```

## Testing

```bash
./mvnw test
```

## Cleanup

Deactivate the virtual environment
```bash
deactivate
# optionally
# rm -r env
```

--- METRICS ---
- Files Extracted: 5
- Estimated Token Budget: ~4299 tokens
- Recency Window: Active (< 180 days)
- Canonical Reference: https://codewiki.google/github.com/oracle/opengrok