Managing Design Documents with CouchApp

If you want to install and hack on your own version of Sofa while you read the following chapters, we’ll be using CouchApp to upload the source code as we explore it.

We’re particularly excited by the prospect of deploying applications to CouchDB, because depending on a least-common denominator environment, that encourages uses to control not just the data but also the source code, promises to make building personal web apps a reality for more people. And when the web app you’ve hacked together in your spare time hits the big-time, the ability of CouchDB to scale to larger infrastructure sure doesn’t hurt.

In a CouchDB design doc there are a mix of development languages (HTML, JS, CSS) that go into different places like attachments and design document attributes. Ideally you want your development environment to help you as much as possible. More importantly, you’re used to: Proper syntax highlighting, validation, integrated documentation, macros, helpers and whatnot. Editing HTML and JavaScript code as the string-attributes of a JSON object is not exactly modern computing.

Lucky for you, we’ve been working on a solution: Enter CouchApp. CouchApp lets you develop CouchDB applications in a convenient directory hierarchy: Views and shows are separate .js-files neatly organized, your static assets (CSS, images) have their place and with the simplicity of a couchapp push you save your app to a design doc in CouchDB. Make a change? couchapp push and off you go.

This chapter guides you through the installation and moving parts of CouchApp. You will learn what other neat helpers it has in store to make your life easier (Gosh, aren’t we awfully nice?).

The CouchApp script and framework we’ll be using grew out of the work designing this example application. It’s now in use for a variety of applications, and has a mailing list, wiki, and a community of hackers. Just search the internet for "couchapp" to find the latest information. Many thanks to Benoît Chesneau for building and maintaining the library (and contributing to CouchDB’s Erlang codebase and many of the Python libraries.)

If you have Python (you probably do) installing CouchApp is as easy as:

sudo easy_install couchapp

The most common problem people have installing CouchApp is with old versions of dependencies, especially easy_install itself. If you experienced an installation error, the best next step is to attempt to upgrade setuptools and then upgrade CouchApp, like this:

sudo easy_install -U setuptools
sudo easy_install -U couchapp

Installing CouchApp via easy_install should, as they say, be easy. Assuming all goes according to plan, it take care of any dependencies and puts the couchapp utility into your system’s PATH so you can immediately begin:

couchapp
Usage: /usr/bin/couchapp [options] (push|generate)
    -q, --quiet                      Omit extra debug info
    -h, --help                       Display detailed help and exit

If you have problems installing CouchApp, have a look at http://pypi.python.org/pypi/setuptools for Python’s easy install troubleshooting, or visit the CouchApp project on the web at http://groups.google.com/group/couchapp.

We plan to make a tar file available with snapshots of the source for each stage of the blog’s development, as well as use Git tags to snapshot the stage for each chapter. (We’ll be saving this step for closer to paper-book time, so for now, you’ll get to jump right into the application as it’s being evolved for the book and to keep up with CouchDB).

The most up-to-date information about installing the Sofa, the example blogging application, will always be available at its public code repository, found at http://github.com/jchris/sofa.

Now that you’ve got Couchapp installed, running these commands should be all it takes:

    git clone git://github.com/jchris/sofa.git
    cd sofa
    couchapp push . http://127.0.0.1:5984/blog

You can also get a copy of Sofa by cloning directly from a running design document. For instance, you can clone Chris’s blog software via:

    couchapp clone http://jchrisa.net/drl/_design/sofa
    cd sofa
    couchapp push . http://127.0.0.1:5984/blog

You can also get a zip or tar of the latest version of Sofa by running one of these commands:

curl http://github.com/jchris/couchapp/zipball/master > sofa.zip
curl http://github.com/jchris/couchapp/tarball/master > sofa.tar

Bird Break: A happy bird to ease any install-induced frustration

You’ll be able to edit the HTML and CSS to personalize your site. The markup is pretty basic, so it’s easy to rework. Adding new features is just a few lines of JavaScript away.

Anytime you make edits to the on-disk version of Sofa, and want to see them in your browser, you’ll run couchapp push . http://127.0.0.1:5984/blog which mirrors the Sofa source directory into CouchDB. In addition to uploading attachments and documents couchapp push .

If you don’t want to have to type the full url to your blog database, you can use the .couchapprc file to store deployment settings. The contents of this file are not pushed along with the rest of the app, so it can be a safe place to keep credentials for uploading your app to secure servers.

{
  "env": {
    "default": {
      "db": "http://jchris:secretpass@127.0.0.1:5984/sofa-local"
    },
    "dev": {
      "db": "http://jchris:secretpass@jchris.mfdz.com:5984/sofa-dev"
    },
    "production": {
      "db": "http://jchris:secretpass@jchrisa.net/drl"
    }
  }
}

With this file set up, you can push your CouchApp with the command couchapp push CouchApp also supports alternate environments. If you have staging server to test your application before it goes live, you can use couchapp push dev. In our experience, taking the time to setup a good .couchapprc is always worth it. Another benefit is that it keeps your passwords off the screen when you are working.

The blog will be a single-user application. You, the author, are the administrator and the only one who can add and edit posts. To make sure no one else goes in and messes with your writing, you must create an administrator account in CouchDB. This is a straightforward task. Find your local.ini file and open it in your text editor. (By default it’s stored at /usr/local/etc/couchdb/local.ini) If you haven’t already, uncomment the [admins] section at the end of the file. Next, add a line right below the [admins] section with your preferred username and password.

[admins]
jchris = secretpass

If you don’t like your passwords lying around in plain-text files, don’t worry. The next time CouchDB starts up and reads this file, it takes your password and changes it to an unreverseengineerable hash, like this:

[admins]
jchris = -hashed-207b1b4f8434dc604206c2c0c2aa3aae61568d6c,964 \
  06178007181395cb72cb4e8f2e66e

CouchDB will now ask you for your credentials when you try to create databases or change documents; exactly the things you want to keep to yourself.

One of the easiest ways to get the Sofa source code is by cloning directly from Chris’s blog using CouchApp’s clone command. Follow along if you’d like to get your own copy of the source.

By running a command that points CouchApp to th

couchapp clone http://jchrisa.net/drl/_design/sofa

moar typing please

$ couchapp clone http://jchrisa.net/drl/_design/sofa
[INFO] Cloning sofa to sofa...
$ tree sofa/
sofa/
|-- README.md
|-- THANKS.txt
|-- _attachments
|   |-- LICENSE.txt
|   |-- THANKS.txt
|   |-- account.html
|   |-- blog.js
|   |-- jquery.scrollTo.js
|   |-- md5.js
|   |-- screen.css
|   |-- showdown-licenese.txt
|   |-- showdown.js
|   |-- tests.js
|   `-- textile.js
|-- blog.json
|-- couchapp.json
|-- helpers
|   `-- md5.js
|-- lists
|   `-- index.js
|-- shows
|   |-- edit.js
|   `-- post.js
|-- templates
|   |-- edit.html
|   |-- index
|   |   |-- head.html
|   |   |-- row.html
|   |   `-- tail.html
|   `-- post.html
|-- validate_doc_update.js
|-- vendor
|   |-- _attachments
|   |   `-- jquery.couchapp.js
|   `-- couchapp
|       |-- README.md
|       |-- _attachments
|       |   `-- jquery.couchapp.js
|       |-- couchapp.js
|       |-- date.js
|       |-- path.js
|       `-- template.js
`-- views
    |-- comments
    |   |-- map.js
    |   `-- reduce.js
    |-- recent-posts
    |   `-- map.js
    `-- tags
        |-- map.js
        `-- reduce.js

14 directories, 37 files

Now that you’ve got the couchapp script installed, let’s push the app to your local CouchDB for the first time. To ensure that everything’s working alright, run this line in your terminal shell.

curl http://127.0.0.1:5984

The response should include text like:

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

If CouchDB is not running yet, go back to the Futon chapter and follow the hello world instructions there.

Change into the sofa directory and issue the follow command:

couchapp push . http://admin:ihavenosecrets@127.0.0.1:5984/blog

Make sure to replace admin and ihavenosecrets with your actual values or you will get a permission denied error. If all works according to plan everything is set up in CouchDB and you should be able to start using the blog. If you already set up your .couchapprc file, you can just do couchapp push.

$ couchapp push
[INFO] Pushing CouchApp in /Users/jchris/code/couchapps/sofa to design doc:
http://localhost:5984/sofa/_design/sofa
[INFO] Visit your CouchApp here:
http://localhost:5984/sofa/_design/sofa/_list/index/recent-posts?descending=true&limit=5

Visit this location in your browser:

http://127.0.0.1:5984/blog/_design/sofa/_list/index/recent-posts

And you should see something like this:

Figure: Empty index page

Ok, we know the application has installed in your CouchDB, so now it’s time to get to work wiring it up. Before we can start building, let’s sit back a moment and think about what the goal is. The most tangible place to model CouchDB applications is the JSON document format that they use. Before we can add posts to our blog, we need to plan how we’ll store them.