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

1. Checkout CouchDB from SVN.

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

2. Make sure you have requirements.

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

3. Build that sucker.

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

4. 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/
   

5. 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"}
   

6. Install Git if you don't already have it installed.

   sudo port install git
   

   Or you can use the git-osx-installer.

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

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

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

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

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

12. 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 ()
    

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