.. Licensed under the Apache License, Version 2.0 (the "License"); you may not .. use this file except in compliance with the License. You may obtain a copy of .. the License at .. .. http://www.apache.org/licenses/LICENSE-2.0 .. .. Unless required by applicable law or agreed to in writing, software .. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT .. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the .. License for the specific language governing permissions and limitations under .. the License.

.. _install/search:

========================== Search Plugin Installation

.. versionadded:: 3.0

.. highlight:: ini

CouchDB can build and query full-text search indexes using an external Java service that embeds Apache Lucene <http://lucene.apache.org>_. 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.

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::

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

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

-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::

[clouseau]

; the name of the Erlang node created by the service, leave this unchanged
[email protected]

; set this to the same distributed Erlang cookie used by the CouchDB nodes
cookie=brumbrum

; the path where you would like to store the search index files
dir=/path/to/index/storage

; the number of search indexes that can be open simultaneously
max_indexes_open=500

log4j.properties::

log4j.rootLogger=debug, CONSOLE
log4j.appender.CONSOLE=org.apache.log4j.ConsoleAppender
log4j.appender.CONSOLE.layout=org.apache.log4j.PatternLayout
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::

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

Chef

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

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.

Additional Details

The :ref:Search User Guide <ddoc/search> 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.

.. _GitHub: https://github.com/cloudant-labs/clouseau/releases .. _cookbook: https://supermarket.chef.io/cookbooks/couchdb .. _Helm chart: https://github.com/apache/couchdb-helm