1.8. Search Plugin Installation

New in version 3.0.

CouchDB can build and query full-text search indexes using an external Java service that embeds Apache Lucene. Typically, this service is installed on the same host as CouchDB and communicates with it over the loopback network.

The search plugin is runtime-compatible with Java JDKs 6, 7 and 8. Building a release from source requires JDK 6. It will not work with any newer version of Java. Sorry about that.

1.8.1. Installation of Binary Packages

Binary packages that bundle all the necessary dependencies of the search plugin are available on GitHub. The files in each release should be unpacked into a directory on the Java classpath. If you do not have a classpath already set, or you wish to explicitly set the classpath location for Clouseau, then add the line:

  1. -classpath '/path/to/clouseau/*'

to the server command below. If clouseau is installed in /opt/clouseau the line would be:

  1. -classpath '/opt/clouseau/*'

The service expects to find a couple of configuration files conventionally called clouseau.ini and log4j.properties with the following content:

clouseau.ini:

  1. [clouseau]
  3. ; the name of the Erlang node created by the service, leave this unchanged
  4. name=clouseau@127.0.0.1
  6. ; set this to the same distributed Erlang cookie used by the CouchDB nodes
  7. cookie=monster
  9. ; the path where you would like to store the search index files
  10. dir=/path/to/index/storage
  12. ; the number of search indexes that can be open simultaneously
  13. max_indexes_open=500

log4j.properties:

  1. log4j.rootLogger=debug, CONSOLE
  2. log4j.appender.CONSOLE=org.apache.log4j.ConsoleAppender
  3. log4j.appender.CONSOLE.layout=org.apache.log4j.PatternLayout
  4. log4j.appender.CONSOLE.layout.ConversionPattern=%d{ISO8601} %c [%p] %m%n

Once these files are in place the service can be started with an invocation like the following:

  1. java -server \
  2.      -Xmx2G \
  3.      -Dsun.net.inetaddr.ttl=30 \
  4.      -Dsun.net.inetaddr.negative.ttl=30 \
  5.      -Dlog4j.configuration=file:/path/to/log4j.properties \
  6.      -XX:OnOutOfMemoryError="kill -9 %p" \
  7.      -XX:+UseConcMarkSweepGC \
  8.      -XX:+CMSParallelRemarkEnabled \
  9.      com.cloudant.clouseau.Main \
  10.      /path/to/clouseau.ini

1.8.2. Chef

The CouchDB cookbook can build the search plugin from source and install it on a server alongside CouchDB.

1.8.3. Kubernetes

Users running CouchDB on Kubernetes via the Helm chart can add the search service to each CouchDB Pod by setting enableSearch: true in the chart values.

1.8.4. Additional Details

The Search User Guide provides detailed information on creating and querying full-text indexes using this plugin.

The source code for the plugin and additional configuration documentation is available on GitHub at https://github.com/cloudant-labs/clouseau.