xref: /OpenGrok/docker/README.md (revision f70822c28c6c084c9798396671051d5cd1e2ca51)

[![](https://images.microbadger.com/badges/image/opengrok/docker.svg)](https://microbadger.com/images/opengrok/docker "Get your own image badge on microbadger.com")
[![](https://images.microbadger.com/badges/version/opengrok/docker.svg)](https://microbadger.com/images/opengrok/docker "Get your own version badge on microbadger.com")

# 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 http://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. 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.)

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 9
* JRE 8 (Required for Opengrok 1.0+)
* 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` for Git
repositories).

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.

### Tags and versioning

Each OpenGrok release triggers creation of new Docker image. The `latest` tag always tracks the latest and there is also versioned image (e.g. `1.2.3`) - if you want to pin against a specific version, use one of these.

## How to run

### From DockerHub

    docker run -d -v <path/to/your/src>:/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.

By default, the index will be rebuild every ten minutes. You can adjust this
time (in minutes) by passing the `REINDEX` environment variable:

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

Setting `REINDEX` to `0` will disable automatic indexing. You can manually trigger an reindex using docker exec:

    docker exec <container> /scripts/index.sh

Setting `INDEXER_OPT` could pass extra options to opengrok-indexer. For example, you can run with:

    docker run -d -e INDEXER_OPT="-i d:vendor" -v <path/to/your/src>:/opengrok/src -p 8080:8080 opengrok/docker:latest

To 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

To avoid the mirroring step, set the `NOMIRROR` variable to non-empty value.

## 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 signigicantly less time.

### Build image locally

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

    mvn -DskipTests=true clean package && \
        docker build -t opengrok-dev .

Then run the container:

    docker run -d -v <path/to/your/src>:/opengrok/src -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/):

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

Enjoy.