DEV Community

Cover image for How to setup Clouseau for  CouchDB search on Unix-like systems
Jordan Soo Yen Yih
Jordan Soo Yen Yih

Posted on

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


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.


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
Enter fullscreen mode Exit fullscreen mode

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 -d /opt/
Enter fullscreen mode Exit fullscreen mode

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/
Enter fullscreen mode Exit fullscreen mode

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 with the following content:



; the name of the Erlang node created by the service, leave this unchanged

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

; the path where you would like to store the search index files

; the number of search indexes that can be open simultaneously
Enter fullscreen mode Exit fullscreen mode

log4j.rootLogger=debug, CONSOLE
log4j.appender.CONSOLE.layout.ConversionPattern=%d{ISO8601} %c [%p] %m%n
Enter fullscreen mode Exit fullscreen mode

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

/usr/bin/java -server \
     -Xmx2G \ \ \
     -Dlog4j.configuration=file:/opt/clouseau-2.17.0/ \
     -XX:OnOutOfMemoryError="kill -9 %p" \
     -XX:+UseConcMarkSweepGC \
     -XX:+CMSParallelRemarkEnabled \
     -classpath '/opt/clouseau-2.17.0/*' \
     com.cloudant.clouseau.Main \
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

Description=clouseau service


Enter fullscreen mode Exit fullscreen mode

Once created, then run the 3 commands below:

sudo systemctl daemon-reload
Enter fullscreen mode Exit fullscreen mode
sudo systemctl enable clouseau.service
Enter fullscreen mode Exit fullscreen mode
sudo systemctl start clouseau
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

Enter fullscreen mode Exit fullscreen mode

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.👋

Discussion (2)

cortescasado profile image
Alvaro Cortes • Edited on

Hi Jordan, thanks for your tutorial, is by far clearer than official documentation installing, however I don't get the search working.
The clouseau.service loads right but it fails when I try to start it without any log message. Any idea?

yenyih profile image
Jordan Soo Yen Yih Author • Edited on

Hi Alvaro Cortes, did you try to use systemctl status clouseau.service to check the clouseau status? Btw, I ever experience that clouseau service slow to bootup due to server instance resources not enough, in this scenario, clouseau didn't throw any error message and when I checked on the CouchDB features list, there is no "search" feature show up. But after a time of period, It did appeared and was connected successful. I am not sure whether it is the same issue you have encountered, but you may try to use systemctl or check on CouchDB logs see any hints from there.