Setup CouchDB for using the microservice

Overview

To use the Insights microservice with CouchDB, CouchDB has to be configured from source to include some third party libraries for managing the operations done by the dashboard.

Prerequisites

Your machine would need to have maven 3.2.5 and Java 6 installed for running clousseau

Setting up CouchDB to run full text searches

To set up CouchDB to include full text searches you would need to build and compile CouchDB from source. Here are the steps for building and compiling CouchDB 2.3 including dreyfus and clouseau. These steps were written based on the steps in this blog.

1. Download CouchDB from the public git repository. You could run git clone --branch 2.3.x https://github.com/apache/couchdb.git and follow the steps in the Apache CouchDB repo for installing CouchDB on your machine

2. Once installed and you are able to run a CouchDB node on your computer lets add full text search. First lets add dreyfus to the the erlang dependencies. In the directory of the cloned CouchDB repo open the file rebar.config.script and in the DepDescs = [ array add {dreyfus, {url, "https://github.com/cloudant-labs/dreyfus"}, "df88b1c1da6ab63dc23059587f0b9c872342feec"} at the end. Like so

   DepDescs = [
       ...
       {meck,             "meck",             {tag, "0.8.8"}},
       {dreyfus,           {url, "https://github.com/cloudant-labs/dreyfus"}, "df88b1c1da6ab63dc23059587f0b9c872342feec"}
   ]
   

3. We also have to add dreyfus to the rel/reltool.config file. Open it and add dreyfus to the like so

   {sys, [
       {lib_dirs, ["../src"]},
       {rel, "couchdb", "2.3.0", [
           ...
           snappy,
           dreyfus
       ]}
       ...
       {app, snappy, [{incl_cond, include}]},
       {app, dreyfus, [{incl_cond, include}]}
   ]}
   

4. Additionally we have to register the Dreyfus extensible plugin interface (EPI) in rel/apps/couch_epi.config like so

       {plugins, [
           ...
           setup_epi,
           dreyfus_epi
       ]}.
   

5. The Queryserver from CouchDB has to learn how to handle the views that create a search index. In order to make it work we have to add dreyfus.js to our Queryserver by running curl https://raw.githubusercontent.com/cloudant/couchdb/c323f194328822385aa1bb2ab15b927cc604c4b7/share/server/dreyfus.js > share/server/dreyfus.js

6. The build then must include our new dependencies for the Queryserver. Open the support/build_js.escript file and add the downloaded dreyfus.js to it like so

       main([]) ->
           JsFiles = [
               ...
               "share/server/dreyfus.js"
           ]
           CoffeeFiles = [
               ...
               "share/server/dreyfus.js"
           ]
   

7. Now that we have added dreyfus.js we have to add the exposed functions to loop.js to be able to call them in a view. Open the share/server/loop.js and add to it the following

       function create_sandbox() {
           try {
               ...
               sandbox.index = Dreyfus.index;
           }catch (e) {
               ...
   

   And also add

       var Loop = function() {
           var line, cmd, cmdkey, dispatch = {
               ...
               "index_doc": Dreyfus.indexDoc
           };
           ...
   

8. Our node running Dreyfus must know where Clouseau is running in order to communicate with it. One Erlang node will talk to one Clouseau instance. From reading the source, Dreyfus gets that information from the CouchDB config files. Open the rel/overlay/etc/local.ini and dreyfus before the [admins] tag like this

       ...
       [dreyfus]
       name = {{clouseau_name}}
       [admins]
       ;admin = mysecretpassword
   

9. Lets edit the dev/run script so that it adds the appropiate clouseau tag to it. In the setup_configs function after "fauxton_root": fauxton_root, we will add clousseau to change it so it looks like this

       def setup_configs(ctx):
           ...
           "fauxton_root": fauxton_root,
           "clouseau_name": "clouseau%d@127.0.0.1" % (idx+1),
           ...
   

10. Now we can recompile CouchDB with our additions. Let reconfigure and run one node with admin and password

        ./configure
        make
        ./dev/run --admin=<USER>:<PASS> -n 1
    

11. You should now have a CouchDB node running on port 15984. Now we will run clouseau. Remember you need Java 6 and maven 3.2.5 for this to work. Just run

        git clone https://github.com/cloudant-labs/clouseau
        cd clouseau
        mvn scala:run -Dlauncher=clouseau1
    

12. Thats it. Your CouchDB you now handle full text searches. Try it out with the Insights microservice. If your data is already on another database you can replicate it to the node you just set up and use that database instead.