[couchdb-documentation] 01/01: Document Clouseau install process

[ko...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

kocolosk pushed a commit to branch clouseau-install
in repository https://gitbox.apache.org/repos/asf/couchdb-documentation.git

commit 6d17b583dae206cd1df8c446d76588cf87140f73
Author: Adam Kocoloski <ko...@apache.org>
AuthorDate: Tue Feb 4 19:31:57 2020 -0500

    Document Clouseau install process
---
 src/ddocs/search.rst   |   3 +-
 src/install/index.rst  |   1 +
 src/install/search.rst | 101 +++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 104 insertions(+), 1 deletion(-)

diff --git a/src/ddocs/search.rst b/src/ddocs/search.rst
index 38d351b..34d9464 100644
--- a/src/ddocs/search.rst
+++ b/src/ddocs/search.rst
@@ -24,7 +24,8 @@ groups, facets, or geographical searches.
 
 .. warning::
     Search cannot function unless it has a functioning, cluster-connected
-    Clouseau instance.
+    Clouseau instance. See :ref:`Search Plugin Installation <install/search>`
+    for details.
 
 To create a search index, you add a JavaScript function to a design document in the
 database. An index builds after processing one search request or after the server detects
diff --git a/src/install/index.rst b/src/install/index.rst
index 02a645e..fc8f6f6 100644
--- a/src/install/index.rst
+++ b/src/install/index.rst
@@ -26,5 +26,6 @@ Installation
     docker
     snap
     kubernetes
+    search
     upgrading
     troubleshooting
diff --git a/src/install/search.rst b/src/install/search.rst
new file mode 100644
index 0000000..872930b
--- /dev/null
+++ b/src/install/search.rst
@@ -0,0 +1,101 @@
+.. 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.
+
+Installation of Binary Packages
+===============================
+
+IBM maintains binary packages of the search service on `GitHub`_ that bundle all
+the necessary dependencies. The files in each release should be unpacked into a
+directory on the Java classpath. 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=monster
+
+    ; 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