Setting up CouchDB-Lucene on OS X

couchdb (6), lucene (1)

Here are the instructions I put together while setting up CouchDB-Lucene on OS X. You should be able to follow these instructions verbatim on a standard OS X 10.5 install, and I think on 10.4 as well.

Installation on a Linux system will be generally the same, but the specifics will vary. Windows doesn't have a prayer.

Oh. Here is a good time to mention the pages for the loveable Schemaless database CouchDB and full-text search Lucene.

This is the second version of this article, updated to use Robert Newson's fork of couchdb-lucene, which is more up-to-date than Paul Davis'.

Checkout CouchDB from SVN.

svn co http://svn.apache.org/repos/asf/couchdb/trunk couchdb

Make sure you have requirements.

port install automake autoconf libtool help2man
port install icu erlang spidermonkey curl

Build that sucker.

cd couchdb
./bootstrap
./configure
make && sudo make install

If you happen to have tried installing couchdb-lucene a month ago and given up in a fit of anger, then you may have a broken local.ini file laying around on your system. (Conceivably you might have had an alternative path to failure.)

In that case, replace your current local.ini with a copy in the CouchDB source.
```
sudo cp etc/couchdb/local.ini /usr/local/etc/couchdb/
```
Run CouchDB and verify it installed. First run it,
```
sudo /usr/local/var/bin/couchdb
```
and then navigate over to http://127.0.0.1:5984/ and you should see this:
```
{"couchdb":"Welcome","version":"0.9.0a741596-incubating"}
```
Install Git if you don't already have it installed.
```
sudo port install git
```
Or you can use the git-osx-installer.
Clone the couchdb-lucene project. (I like to keep all of my git repositories in ~/git/, but it's just a personal thing.)
```
cd ~/git/
git clone git://github.com/rnewson/couchdb-lucene.git
```
Now we beg OS X to let us use Java 1.6. This step isn't possible for people on PowerPCs, and possibly those using 10.4 or earlier. I'd describe it all as a bit rediculous, but I'm glad I don't use Java frequently on OS X.

Run the application (you can just mouse over to this one, since it is a GUI) at Applications/Utilities/Java/Java Preferences. When it opens, drag 1.6 to the top in the bottom half of the screen (sorry, hard to describe the convoluted UI more precisely than that). Then exit. No, it doesn't tell you that it changed anything or confirm that it saved. Arg.

Verify that the change happened:
```
will-larsons-macbook:lib will$ java -version
java version "1.6.0_07"
Java(TM) SE Runtime Environment (build 1.6.0_07-b06-153)
Java HotSpot(TM) 64-Bit Server VM (build 1.6.0_07-b06-57, mixed mode)
```
Great.

Update 2/11/2009: the above method of changing your current version of Java may not be sufficient. If you attempt to run mvn below and get an error complaining that one of the Java libraries is missing a static value MINUTES, then try this solution instead:
```
cd /System/Library/Frameworks/JavaVM.framework/Versions
sudo ln -s 1.6 ./Current
```
I haven't experienced any negative side-effects from doing that, but it might generally be a bad idea. It certainly feels wrong....

Build couchdb-lucene.

cd couchdb-lucene
mvn

While you're there you should figure out the path to couchdb-lucene-SNAPSHOT-jar-with-dependencies.jar.

will-larsons-macbook:couchdb-lucene will$ cd target/ will-larsons-macbook:target will$ ls archive-tmp classes couchdb-lucene-SNAPSHOT-jar-with-dependencies.jar couchdb-lucene-SNAPSHOT.jar maven-archiver will-larsons-macbook:target will$ pwd /Users/will/git/couchdb-lucene/target

You’ll need to remember the full path to that file. For me it is:

/Users/will/git/couchdb-lucene/target/couchdb-lucene-SNAPSHOT-jar-with-dependencies.jar

This is a good time to create a database and upload some data into your database.

If you don't already have some specific data in mind, you can use Futon to setup; go to http://127.0.0.1:5984/_utils/, create a database and add a few documents.

Open up your local.ini file. (Yes, using Emacs is mandatory. ;)

sudo emacs /usr/local/etc/couchdb/local.ini

And add these lines (make sure to update the jar path to your system!):

[external]
fti = /System/Library/Frameworks/JavaVM.framework/Versions/1.6/Commands/java -jar /Users/will/git/couchdb-lucene/target/couchdb-lucene-SNAPSHOT-jar-with-dependencies.jar
[httpd_db_handlers]
_fti = {couch_httpd_external, handle_external_req, <<"fti">>}

You might say "But the instructions say to use /usr/bin/java, screw that long path!" And I say, even though you changed for your current user to use Java 1.6, root is still using Java 1.5, and if you’re running CouchDB via sudo, then you’ll want the longer path.

Actually, if you're running CouchDB via a couchdb user, you'll probably want the longer path as well, since they are probably using Java 1.5 too.

Do another sanity check by closing CouchDB (Control-C in the terminal it was running in), and then relaunching it (which will cause it to load the new local.ini file).

sudo /usr/local/bin/couchdb

If you see this, then you're fine:

Apache CouchDB 0.9.0a741596-incubating (LogLevel=info) is starting.
Apache CouchDB has started. Time to relax.

On the other hand, if you see this, then there is an error somewhere in your local.ini file.

Apache CouchDB 0.9.0a741596-incubating (LogLevel=info) is starting.
[error] [<0.47.0>] {error_report,<0.22.0>,
    {<0.47.0>,supervisor_report,
     [{supervisor,{local,couch_secondary_services}},
      {errorContext,start_error},
      etc,etc,etc,etc
Crash dump was written to: erl_crash.dump
init terminating in do_boot ()

Now let's test if it works.
```
http://127.0.0.1:5984/my_db/_fti?q=title:cat
```
Awesome! Except it probably just returned the file with the application/json mimetype, which means your browser probably downloaded it instead of showing it in a visible manner.

We can fix that by appending &debug to the query.
```
http://127.0.0.1:5984/my_db/_fti?q=title:cat&debug=true
```

And there you have it, CouchDB-Lucene running on OS X.

Published on February 6, 2009.