You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by wo...@apache.org on 2020/02/07 19:49:13 UTC
[couchdb-documentation] branch master updated: Document Clouseau
install process (#495)
This is an automated email from the ASF dual-hosted git repository.
wohali pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/couchdb-documentation.git
The following commit(s) were added to refs/heads/master by this push:
new 8958045 Document Clouseau install process (#495)
8958045 is described below
commit 8958045c2e116512e1633d8b3ca0f0bc15b5486d
Author: Adam Kocoloski <ko...@apache.org>
AuthorDate: Fri Feb 7 14:49:04 2020 -0500
Document Clouseau install process (#495)
* minor bump to release notes
* Document Clouseau install process
Co-authored-by: Joan Touzet <wo...@users.noreply.github.com>
---
src/api/ddoc/search.rst | 12 ++++--
src/api/server/common.rst | 8 ++--
src/ddocs/search.rst | 3 +-
src/install/index.rst | 1 +
src/install/search.rst | 101 ++++++++++++++++++++++++++++++++++++++++++++++
src/whatsnew/3.0.rst | 5 ++-
6 files changed, 120 insertions(+), 10 deletions(-)
diff --git a/src/api/ddoc/search.rst b/src/api/ddoc/search.rst
index ba10762..3a48021 100644
--- a/src/api/ddoc/search.rst
+++ b/src/api/ddoc/search.rst
@@ -16,6 +16,10 @@
``/db/_design/design-doc/_search/index-name``
=============================================
+.. warning::
+ Search endpoints require a running search plugin connected to each cluster
+ node. See :ref:`Search Plugin Installation <install/search>` for details.
+
.. versionadded:: 3.0
.. http:get:: /{db}/_design/{ddoc}/_search/{index}
@@ -116,10 +120,6 @@
might cause problems when contact is attempted with replicas that are slow or not
available.
-.. warning::
- Search requests will fail unless the CouchDB server is connected to a functioning
- Clouseau instance.
-
.. seealso::
For more information about how search works, see the
:ref:`Search User Guide<ddoc/search>`.
@@ -128,6 +128,10 @@
``/db/_design/design-doc/_search_info/index-name``
==================================================
+.. warning::
+ Search endpoints require a running search plugin connected to each cluster
+ node. See :ref:`Search Plugin Installation <install/search>` for details.
+
.. versionadded:: 3.0
.. http:get:: /{db}/_design/{ddoc}/_search_info/{index}
diff --git a/src/api/server/common.rst b/src/api/server/common.rst
index 0343625..68a50f4 100644
--- a/src/api/server/common.rst
+++ b/src/api/server/common.rst
@@ -1650,6 +1650,10 @@ containing only the requested individual statistic.
``/_search_analyze``
==========================================
+.. warning::
+ Search endpoints require a running search plugin connected to each cluster
+ node. See :ref:`Search Plugin Installation <install/search>` for details.
+
.. versionadded:: 3.0
.. http:post:: /_search_analyze
@@ -1683,10 +1687,6 @@ containing only the requested individual statistic.
]
}
-.. warning::
- Requests to this endpoint will fail unless the CouchDB server is connected to a
- functioning Clouseau instance.
-
.. _api/server/utils:
===========
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..1fe07b6
--- /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
+===============================
+
+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. 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
diff --git a/src/whatsnew/3.0.rst b/src/whatsnew/3.0.rst
index 5e4e251..8758bac 100644
--- a/src/whatsnew/3.0.rst
+++ b/src/whatsnew/3.0.rst
@@ -222,7 +222,7 @@ Features and Enhancements
text-based indexes can be enabled in CouchDB. It is recommended to have as many Clouseau
nodes as you have CouchDB nodes. Search is advertised in the feature list present at
``GET /`` if configured correctly (:ghissue:`2206`). :ref:`Configuration
- <config/search>` and **[TODO]** installation documentation is available.
+ <config/search>` and :ref:`installation documentation is available <install/search>`.
* :ghissue:`2411`: The ``/_up`` endpoint no longer requires authentication, even when
``require_valid_user`` is ``true``.
@@ -407,6 +407,9 @@ Bugfixes
* :ghissue:`2486`: The ``$lt``, ``$lte``, ``$gt``, and ``$gte`` Mango operators are
correctly quoted internally when used in conjunction with a text index search.
+* :ghissue:`2493`: The ``couch_auth_cache`` no longer has a runaway condition in which
+ it creates millions of monitors on the ``_users`` database.
+
Other
-----