Updating

Updating OpenGrok from one version to another is usually easy:

1. extract the distribution archive
2. deploy the new web application

When updating OpenGrok, it is usually prudent to update Universal ctags as well. That said, it is recommended to update them one at a time to avoid surprises. I.e. update OpenGrok first, wait for couple of reindex period, then update Universal ctags.

In general, the update should happen only if reindex is not in progress.

If you are using the Python tools for managing OpenGrok, this is another thing to update.

Sometimes, there is a case where certain part of configuration changes. Such cases are treated separately and do not usually require reindex from scratch.

Reindexing from scratch

However, in case the index format changed, it is necessary to reindex from scratch, i.e. delete all files under data root and indexing anew. How do you tell that index format changed ? The release notes will contain such information. Since reindexing from scratch is usually costly procedure (both time and resource wise), for most production deployments it should be done in the background, to a dedicated data root (to avoid overwriting existing data), using a snapshot of the source root (to avoid indexing data in flux). Once it is over, the data root can be switched (e.g. by renaming the directories) and the new web application deployed. Since the web application has a dependency on concrete format of the index, it is necessary to switch it only in the last step.

There is a way how to make this step easier, if you are using a file system that supports snapshots and data sets, such as ZFS.

Example

Here is a basic outline of steps to perform reindex from scratch:

1. make the latest configuration persistent (using the opengrok-projadm Python tool or getting it via the RESTful API)
2. create temporary data root
3. create Java logging configuration file that logs everything to a distinct file
4. extract the distribution from the tar ball into temporary location
5. if using the Python tools, update them in the temporary location
6. create stable image of source code
7. if using read-only configuration, change it to reflect any OpenGrok configuration changes between currently running OpenGrok version and the version we are upgrading to (e.g. new/changed configuration options)
8. reindex