Jan 16, 2012

Installing CouchDB for Mac OS X. Nuances.

Our project will have a new architecture changes in future. We've chosen from different tech. But now we 're experimenting with CouchDB a bit. It may become a part of our new architectural Changes. I'll try to cover most of newbies observations with CouchDB for Python(Django) programmer, planning to use it in your project.

First article will be, unsurprisingly, installing CouchDB under Mac OS X. It, sure, has some inches that you need to scratch. So let's roll...

CouchDB is not a simple SQL database like you used to install before. It has own server to accept connections. And, in fact, you can work with database from your browser GUI (without other server proxy, like Django or ...). Anyway it will not be our target. Building JS UI is quite easier with CouchDB and changes your logic dramatically. To build UI with Python we need some proxy parts. Anyway, again, CouchDB is a standalone server, that runs on your server's port and talks to your APP/Browser/whatever... through JSON API. It's quite a bad thing, because it's a bit slow, but a good thing, because it's extremely easy to implement. Most programming languages have adaptors to JSON.  CouchDB is quite a new tech. And it is highly developed and "pushed through" tech for now...

Ok enough preface... Actual install is described in official DOCS HERE. I'm using "mac ports" for my project already. So it's my choice of install method by all means. I'll cover docs here in brief to be consistent:

1. Install it through mac ports.

$ sudo port install couchdb

Will start huge and massive install of required ports for this DB.

2. Good idea would be to update Mac ports. If you have some ports installed already, like I do:

$ sudo port upgrade couchdb

Will upgrade only ports required by "couchdb" port.
It's also a good idea to selfupdate ports if you already have them installed:

$ sudo port selfupdate

This must be sufficient for all of our needs.

At this point you must be able to run CouchDB from command line running:

$ couchdb

command in Terminal. If it runs with error, no worries. Read on. There is a known issue!

3.  Bug occurs in MacPorts itself with "couchdb" package. It does not create some paths in required dir. You need to manually create those paths and give CouchDB permissions to write there. Mac Ports Track has the solution. Or you can manually (better IMHO) make sure all your permissions and directories exist.
You need to make sure those directories exist, and create them if they don't:

/opt/local/var/lib/couchdb/
/opt/local/var/log/couchdb/
/opt/local/etc/couchdb/

and have permission to work with CouchDB:

$ sudo chown -R couchdb:couchdb /opt/local/var/lib/couchdb/
$ sudo chown -R couchdb:couchdb /opt/local/var/log/couchdb/
$ sudo chown -R couchdb:couchdb /opt/local/etc/couchdb/

(Those paths are ok for a standart "mac ports" install.. If your directories differ... than change those paths accordingly)
After those actions, running couchdb from console should led to normal startup sequence output:

$ couchdb
Apache CouchDB 1.1.1-incubating (LogLevel=info)
Apache CouchDB is starting.
Apache CouchDB has started. Time to relax.

This will signal that your CouchDB install is almost OK and you may check that it is running:

http://127.0.0.1:5984/

In your browser. It must Show output JSON. Something like:

{"couchdb":"Welcome","version":"1.1.1"}

You may also examine it's web admin UI, typing in browser:

http://127.0.0.1:5984/_utils/index.html

Should show handy Admin UI. You may examine/edit DB by hand there... (Something similar to PHP MyAdmin or whatever you used to use on SQL DB's)

4. Add autorun command (optionally). It's good to run every time you need it for experiments, etc... But if you plan to Debug test apps on that platform it's good idea to make it start with system every toime it runs. To make that you need to type this command into console:

$ sudo launchctl load -w /opt/local/Library/LaunchDaemons/org.apache.couchdb.plist


THE END.

Comments and suggestions are welcome!
In future I plan to make some articles on actual befriending CouchDB with Python. Stay tuned and thanks for reading that far.

No comments:

Post a Comment