.. 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
    name=clouseau@127.0.0.1

    ; 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
