February 6, 2009.
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.