OpenGrok Documentation

It is recommended to use a Python virtual environment to install the tools into a specific directory. This keeps the package and its dependencies isolated within that directory.

After installation, you can invoke the scripts directly from the virtual environment's bin directory (e.g., /opt/opengrok/opengrok-tools/bin/opengrok-indexer).

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

To develop OpenGrok tools, prepare a Python virtual environment and install the package in editable mode so that changes to the source are reflected immediately.

Note: When running scripts manually during development, you must set the PYTHONPATH to include the src/main/python directory to avoid import errors. Always call the tools via their entry point names (e.g., opengrok-groups) rather than calling the .py files directly to avoid relative import errors.

# Prepare virtual environment
python3 -m venv env
. env/bin/activate

# Install in development mode
python -m pip install -e .

# Set PYTHONPATH and run entry points
export PYTHONPATH=`pwd`/src/main/python:$PYTHONPATH
opengrok-groups
opengrok-sync

Use the following docker-compose.yml configuration to manage OpenGrok. This setup includes persistent volumes for source code, configuration, and index data to ensure data is preserved during container upgrades.

To start the service, save the configuration and run docker-compose up -d.

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

docker-compose up -d

You can install the tools using a distribution tarball created via python -m build.

Standard Installation

Install the package and its dependencies to your local Python 3 modules:

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

Install to a specified directory

It is recommended to use a Python virtual environment for isolated installations in specific directories (e.g., /opt/opengrok):

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

After this installation, you can execute the scripts using their full paths, for example: /opt/opengrok/opengrok-tools/bin/opengrok-indexer.

Uninstalling

To remove the package:

python3 -m pip uninstall opengrok_tools

To run the OpenGrok container, use docker run. You must mount a local directory to /opengrok/src containing the source code projects you want to index. The container exposes port 8080 for the web interface.

Note: The first reindex may take some time. Subsequent reindexes are incremental and faster. The container runs as a non-root user.

docker run -d -v <path/to/your/src>:/opengrok/src -p 8080:8080 opengrok/docker:latest

OpenGrok follows semantic versioning (major.minor.micro). The type of update required depends on which component changes:

• major: Backwards incompatible update. Requires full reindex and configuration changes.
• minor: Requires a full clean reindex of your repositories (e.g., due to index format changes).
• micro: Requires redeploying the web application.

Note: Going backward is generally only possible within the same micro version.

To install the tools globally on your target system using a distribution tarball, use pip. This will download all necessary dependencies and install the package into your local Python 3 modules.

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