5 Steps to setup OpenGrok on your Computer

Have you ever referred to existing projects for correct usages of annotations like @SpringBootTest,@Async,@Cached or have you ever went back to a project that you have worked before to check the way you wrote that ThreadPool, Pom.xml, DockerFile. Everyone does that!

So how do you do it? Do you load the project on your IntelliJ or PyCharm or any other IDE and search for it? Or do you go to the GitHub UI and look for it? Its just not convenient and we do this so often! If you are working on a Microservice architecture this will be gazillion times harder.

I use Opengrok. It’s pretty handy, makes my life much easier. I can index all my little projects and search for any thing in any number of repos easily and quickly. Apart from search it comes very handy when you quickly want to check for any file’s Git history. Instead of setting up in local, if its hosted on a server accessible to your coworkers, it will be the easiest way to point to specific line in code in indirect discussions. You can refer to all the stuff it can do and on its git repo.

In this article I shared the steps that I used to easily setup OpenGrok on my Macbook. Opengrok uses Java 11, I didn’t want to install Java 11 on my mac since my company still uses Java 8 and applications doesn’t work with Java 11 (I tried installing both JDks but it just makes everything messy).

To avoid all this complications I used docker image. It also takes care of updating you repositories and reindexing with latest code as per the defined intervals. Most of what I mentioned here can be found in the official docker hub page. I just filtered out things that I used and also included some other steps I did.

Step 1: Install docker if you haven’t already (You can download Docker Desktop, its pretty convenient and installs all command line tools too)

Step 2: Clone all your repos in one folder, use SSH for automatically updating git repos periodically (Avoid using your development workplace since we want to update and reindex all the code regularly)

Step 3: Create a docker-compose.yml file and copy the below contents

version: "3"
# More info at https://github.com/oracle/opengrok/docker/
services:
  opengrok:
    container_name: opengrok
    image: opengrok/docker:latest
    ports:
      - "9090:8080/tcp"
    environment:
      SYNC_PERIOD_MINUTES: '60'
    # Volumes store your data between container upgrades
    volumes:
       - '<path to your source code>/:/opengrok/src/'  # source code
       - '<path to opengrok dir>/opengrok/etc/:/opengrok/etc/'  # folder contains configuration.xml
       - '<path to opengrok dir>/opengrok/data/:/opengrok/data/'  # index and other things for source code
       - '<path to your .ssh folder>/.ssh:/root/.ssh' # ssh key for git access

Lets go through few key configurations in this file

1. The port configuration is 9090:8080/tcp. We are basically mapping your localhost port 9090 to 8080 of the tomcat inside docker. Since I use 8080 port frequently I set it as 9090, you can update it to any valid value as you wish
2. SYNC_PERIOD_MINUTES refers to the time intervals in which repos needs to be updated and reindexed, its set to 60 mins here
3. <path to your source code> — This is path to your local folder containing all the cloned repos (don’t miss ‘/’ at the end)
4. <path to opengrok dir> — Create a folder ‘opengrok’ for storing generated indexes and other stuff locally, inside this folder create two more folders ‘etc’ and ‘data’
5. <path to your .ssh folder> — You will need this mapping if you want to automatically pull code from git or any other versioning system using ssh

Step 5: Run docker-compose up to bring up opengrok container, this will pull the latest image and index the source code

Thats it! In 5 steps you have OpenGrok on your machine, you can access it @ localhost:9090

Although these steps refer to what I followed to setup open grok in my macbook, it should be pretty similar on other setups as well. Do you let me know if you encounter any difficulties.

Few Tips:

1. Add following two lines in .sh file, make it executable, change the default opening application to terminal and add it to your startup/login items. This will keep your open grok ready to use when you start your machine
   cd <path to docker compose file folder>
docker-compose up -d
2. Add a custom search engine for the key word grok in your browser to point it to localhost:9090 for easy access