How to setup Clouseau for CouchDB search on Unix-like systems

Introduction

Clouseau is written in Scala code and provides access to the Lucene library. You can use Lucene Query Syntax to run search queries. In previous article I did talk about we can query in Apache CouchDB with Clouseau, today I would like to talk about how to setup Clouseau that link with CouchDB.

Prerequisites📜

Before you begin this guide, you should have a regular, non-root user with sudo privileges configured on your server. Additionally, you will need to have a up and running CouchDB version v3+ on your server. You can learn how to install Apache CouchDB on Unix-like systems by following the official documentation here. Besides that, since Clouseau is written in Scala, we also need to install Java to run Clouseau.

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.

In this tutorial, I am using Ubuntu 20.04, JDK 8 and CouchDB v3.2.1 . CouchDB v3 and higher is a must as CouchDB v3 has extremely simplified the setup of Lucene search.

1. Download Clouseau

You can download the latest Clouseau release from here. Your Clouseau might be different depending on the time you download. My current latest version is Clouseau 2.17.0. I am using wget to download from my Ubuntu server.

sudo wget https://github.com/cloudant-labs/clouseau/releases/download/2.17.0/clouseau-2.17.0-dist.zip

2. Extract Clouseau zip

We are using unzip to extract the Clouseau jar files.

Tips: If you don't have unzip, you can run the command sudo apt-get install unzip for Ubuntu.

Then, we can unzip it with the command below:

sudo unzip clouseau-2.17.0-dist.zip -d /opt/

As you can see, we extract the Clouseau to the destination /opt/
. Now we can navigate to the extracted destination and view the extracted files.

cd /opt/clouseau-2.17.0/

3. Create Configuration files

According to CouchDB official documentation, in order to setup the search plugin, there are 2 configuration files required 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=/opt/couchdb/share/

; 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

4. Create a script to run Clouseau

Below is the script to run Clouseau. If you have a Java background, below syntax should be familiar for you. In this case, I will place the script file under /opt/clouseau-2.17.0/bin/ and the file name called clouseau, full path would be /opt/clouseau-2.17.0/bin/clouseau

#!/bin/sh
/usr/bin/java -server \
     -Xmx2G \
     -Dsun.net.inetaddr.ttl=30 \
     -Dsun.net.inetaddr.negative.ttl=30 \
     -Dlog4j.configuration=file:/opt/clouseau-2.17.0/log4j.properties \
     -XX:OnOutOfMemoryError="kill -9 %p" \
     -XX:+UseConcMarkSweepGC \
     -XX:+CMSParallelRemarkEnabled \
     -classpath '/opt/clouseau-2.17.0/*' \
     com.cloudant.clouseau.Main \
     /opt/clouseau-2.17.0/clouseau.ini

Your path could be different, it depends on where you put the clouseau files, you could change the /opt/clouseau-2.17.0/ if needed, in this case, I'm putting all the clouseau files and configurations under /opt/clouseau-2.17.0 directories.

We are almost there. Now we want to tell Ubuntu to run the service when the server startup. To do that, we can navigate to /lib/systemd/system

cd /lib/systemd/system

and create a file called clouseau.service with the content below:

[Unit]
Description=clouseau service

[Service]
WorkingDirectory=/opt/clouseau-2.17.0
ExecStart=/opt/clouseau-2.17.0/bin/clouseau
Restart=always
RestartSec=3
User=root

[Install]
WantedBy=multi-user.target

Once created, then run the 3 commands below:

sudo systemctl daemon-reload

sudo systemctl enable clouseau.service

sudo systemctl start clouseau

Then, Clouseau should already be up and running. Check with the systemd init system to make sure the service is running by typing

sudo systemctl status apache2

Finally, we can check whether our Apache CouchDB and Clouseau is connected by using CouchDB root endpoint.

curl 127.0.0.1:5984

If Clouseau is connected to CouchDB successfully, You should see the search keyword display under features.

That's it, we did it~🎉

Now we can query with Lucene Query Syntax in CouchDB.
Hope you find this guide useful.👋