1# A Docker container for OpenGrok 2 3## OpenGrok from official source 4 5Built from official source: https://github.com/oracle/opengrok/releases/ 6 7You can learn more about OpenGrok at http://oracle.github.io/opengrok/ 8 9The container is available from DockerHub at https://hub.docker.com/r/opengrok/docker/ 10 11## When not to use it 12 13This 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. 14 15If you happen to have one of the following: 16 17 - large source data (e.g. [AOSP](https://en.wikipedia.org/wiki/Android_Open_Source_Project) or the like) 18 - stable service 19 - Source Code Management systems not supported in the image (e.g. Perforce, 20 Clearcase, etc.) 21 - need for authentication/authorization 22 23then it is advisable to run OpenGrok standalone or construct your own Docker 24image based on the official one. 25 26## Additional info about the image 27 28* Tomcat 10 29* JRE 11 30* Configurable mirroring/reindexing (default every 10 min) 31 32The mirroring step works by going through all projects and attempting to 33synchronize all its repositories (e.g. it will do `git pull --ff-only` for Git 34repositories). 35 36Projects are enabled in this setup by default. See environment variables 37below on how to change that. 38 39### Indexer logs 40 41The indexer/mirroring is set so that it does not log into files. 42Rather, everything goes to standard (error) output. To see how the indexer 43is doing, use the `docker logs` command. 44 45### Source Code Management systems supported 46 47- Mercurial 48- Git 49- Subversion 50 51### Tags and versioning 52 53Each OpenGrok release triggers creation of new Docker image. 54 55| Tag | Note | 56| -------- |:--------------------------------------------------------| 57| `master` | corresponds to the latest commit in the OpenGrok repo | 58| `latest` | tracks the latest [released version](https://github.com/oracle/opengrok/releases) | 59| `x.y.z` | if you want to pin against a specific version | 60| `x.y` | stay on micro versions to avoid reindexing from scratch | 61 62If 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. 63 64For other use cases, stick to the other image tags. 65 66## How to run 67 68### From DockerHub 69 70 docker run -d -v <path/to/your/src>:/opengrok/src -p 8080:8080 opengrok/docker:latest 71 72The container exports ports 8080 for OpenGrok. 73 74The 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. 75 76## Directories 77 78The image contains these directories: 79 80| Directory | Description | 81| --------- | ----------- | 82`/opengrok/etc` | stores the configuration for both web app and indexer 83`/opengrok/data` | data root - index data 84`/opengrok/src` | source root - input data 85`/scripts` | startup script and top level configuration. Do not override unless debugging. 86 87## Environment Variables 88 89| Docker Environment Var. | Default value | Description | 90| ----------------------- | ------------- | ----------- | 91`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). 92`INDEXER_OPT` | empty | pass **extra** options to OpenGrok Indexer. The default set of indexer options is: `--remote on -P -H -W`. 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 93`NOMIRROR` | empty | To avoid the mirroring step, set the variable to non-empty value. 94`URL_ROOT` | `/` | Override the sub-URL that OpenGrok should run on. 95`WORKERS` | number of CPUs in the container | number of workers to use for syncing (applies only to setup with projects enabled) 96`AVOID_PROJECTS` | empty | run in project less configuration. Set to non empty value disables projects. Also disables repository synchronization. 97`REST_PORT` | 5000 | TCP port where simple REST app listens for GET requests on `/reindex` to trigger manual reindex. 98`REST_TOKEN` | None | if set, the REST app will require this token as Bearer token in order to trigger reindex. 99`READONLY_CONFIG_FILE` | None | if set, the configuration will be merged with configuration from this file. This is run when the container starts. 100`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.** 101 102To specify environment variable for `docker run`, use the `-e` option, e.g. `-e SYNC_PERIOD_MINUTES=30` 103 104## Repository synchronization 105 106To get more control over repository synchronization (enabled only when projects 107are enabled), the `/opengrok/etc/mirror.yml` configuration file can be modified 108as per the https://github.com/oracle/opengrok/wiki/Repository-synchronization 109wiki. 110 111## OpenGrok Web-Interface 112 113The container has OpenGrok as default web app installed (accessible directly from `/`). With the above container setup, you can find it running on 114 115http://localhost:8080/ 116 117The first reindex will take some time to finish. Subsequent reindex will be incremental so will take signigicantly less time. 118 119## Using Docker compose 120 121[Docker-compose](https://docs.docker.com/compose/install/) example: 122 123```yaml 124version: "3" 125 126# More info at https://github.com/oracle/opengrok/docker/ 127services: 128 opengrok: 129 container_name: opengrok 130 image: opengrok/docker:latest 131 ports: 132 - "8080:8080/tcp" 133 environment: 134 SYNC_PERIOD_MINUTES: '60' 135 # Volumes store your data between container upgrades 136 volumes: 137 - '~/opengrok/src/:/opengrok/src/' # source code 138 - '~/opengrok/etc/:/opengrok/etc/' # folder contains configuration.xml 139 - '~/opengrok/data/:/opengrok/data/' # index and other things for source code 140``` 141 142Save the file into `docker-compose.yml` and then simply run 143 144 docker-compose up -d 145 146Equivalent `docker run` command would look like this: 147 148```bash 149docker run -d \ 150 --name opengrok \ 151 -p 8080:8080/tcp \ 152 -e SYNC_PERIOD_MINUTES="60" \ 153 -v ~/opengrok-src/:/opengrok/src/ \ 154 -v ~/opengrok-etc/:/opengrok/etc/ \ 155 -v ~/opengrok-data/:/opengrok/data/ \ 156 opengrok/docker:latest 157``` 158 159## Build image locally 160 161If you want to do your own development, you can build the image yourself: 162 163 git clone https://github.com/oracle/opengrok.git 164 cd opengrok 165 docker build -t opengrok-dev . 166 167Then run the container: 168 169 docker run -d -v <path/to/your/src>:/opengrok/src -p 8080:8080 opengrok-dev 170 171## Inspecting the container 172 173You can get inside a container using the [command below](https://docs.docker.com/engine/reference/commandline/exec/): 174 175```bash 176docker exec -it <container> bash 177``` 178 179Enjoy. 180