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 users to control not just the data but also the source code, which will let more people build personal web apps. 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.
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, neatly organized .js files; your static
assets (CSS, images) have their place; and with the simplicity of a
couchapp push, you save your app to a design document
in CouchDB. Make a change?
couchapp push and off you
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. Once we have CouchApp, we’ll use it to install and deploy Sofa to a CouchDB database.
CouchApp is easiest to install using the Python
easy_install script, which is part of the
setuptools package. If you are on a Mac,
easy_install should already be available. If
easy_install is not installed and you are on a Debian
variant, such as Ubuntu, you can use the following command to install
sudo apt-get install python-setuptools
Once you have
easy_install, installing CouchApp
should be as easy as:
sudo easy_install -U couchapp
Hopefully, this works and you are ready to start using CouchApp. If not, read on….
The most common problem people have installing CouchApp is with old
versions of dependencies, especially
itself. If you got an installation error, the best next step is to attempt
setuptools and then upgrade CouchApp by
running the following commands:
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 takes care of
any dependencies and puts the
couchapp utility into
PATH so you can immediately begin by
running the help command:
We’ll be using the
clone pulls an
application from a running instance in the cloud, saving it as a directory
structure on your filesystem.
push deploys a standalone CouchDB application
from your filesystem to any CouchDB over which you have administrative
There are three ways to get the Sofa source code. They are all equally valid; it’s just a matter of personal preference and how you plan to use the code once you have it. The easiest way is to use CouchApp to clone it from a running instance. If you didn’t install CouchApp in the previous section, you can read the source code (but not install and run it) by downloading and extracting the ZIP or TAR file. If you are interested in hacking on Sofa and would like to join the development community, the best way to get the source code is from the official Git repository. We’ll cover these three methods in turn. First, enjoy Figure 11-1.
One of the easiest ways to get the Sofa source code is by cloning
directly from J. Chris’s blog using CouchApp’s
command to download Sofa’s design document to a collection of files on
your local hard drive. The
clone command operates on
a design document URL, which can be hosted in any CouchDB database
accessible via HTTP. To clone Sofa from the version running on J.
Chris’s blog, run the following command:
couchapp clone http://jchrisa.net/drl/_design/sofa
You should see this output:
[INFO] Cloning sofa to ./sofa
Now that you’ve got Sofa on your local filesystem, you can skip to Deploying Sofa to make a small local change and push it to your own CouchDB.
If you merely want to peruse the source code while reading along with this book, it is available as standard ZIP or TAR downloads. To get the ZIP version, access the following URL from your browser, which will redirect to the latest ZIP file of Sofa: http://github.com/couchapp/couchapp/zipball/master. If you prefer, a TAR file is available as well: http://github.com/couchapp/couchapp/tarball/master.
The most up-to-date version of Sofa will always be available at its public code repository. If you are interested in staying up-to-date with development efforts and contributing patches back to the source, the best way to do it is via Git and GitHub.
Git is a form of distributed version control that allows groups of developers to track and share changes to software. If you are familiar with Git, you’ll have no trouble using it to work on Sofa. If you’ve never used Git before, it has a bit of a learning curve, so depending on your tolerance for new software, you might want to save learning Git for another day—or you might want to dive in head first! For more information about Git and how to install it, see the official Git home page. For other hints and help using Git, see the GitHub guides.
To get Sofa (including all development history) using Git, run the following command:
git clone git://github.com/jchris/sofa.git
Once you’ve succeeded with any of these methods, you’ll have a
copy of Sofa on your local disk. The following text is generated by
tree command on the Sofa directory to
reveal the full set of files it contains. Sections of the text are
annotated to make it clear how various files and directories correspond
to the Sofa design document.
sofa/ |-- README.md |-- THANKS.txt
The source tree contains some files that aren’t necessary for the
THANKS files are among those.
|-- _attachments | |-- LICENSE.txt | |-- account.html | |-- blog.js | |-- jquery.scrollTo.js | |-- md5.js | |-- screen.css | |-- showdown-licenese.txt | |-- showdown.js | |-- tests.js | `-- textile.js
Making your first edit to the Sofa source code will show you how easy it is to modify the application.
The blog.json file contains JSON used to configure individual installations of Sofa. Currently, it sets one value, the title of the blog. You should open this file now and personalize the title field—you probably don’t want to name your blog “Daytime Running Lights,” so now’s your chance to come up with something more fun!
You could add other blog configurations to this file—maybe things like how many posts to show per page and a URL for an About page for the author. Working changes like these into the application will be easy once you’ve walked through later chapters.
We’ll see later that
couchapp outputs a link to
Sofa’s home page when
couchapp push is run. The way
this works is pretty simple: CouchApp looks for a JSON field on the
design document at the address
design_doc.couchapp.index. If it finds it, it
appends the value to the location of the design document itself to build
the URL. If there is no CouchApp index specified, but the design
document has an attachment called index.html, then it is considered the
index page. In Sofa’s case, we use the index value to point to a list of
the most recent posts.
|-- helpers | `-- md5.js
The helpers directory here is just an
arbitrary choice—CouchApp will push any files and folders to the design
document. In this case, the source code to
JSON-encoded and stored on the
|-- lists | `-- index.js
|-- shows | |-- edit.js | `-- post.js
The shows directory holds the functions CouchDB uses to generate HTML views of blog posts. There are two views: one for reading posts and the other for editing. We’ll look at these functions in the next few chapters.
|-- templates | |-- edit.html | |-- index | | |-- head.html | | |-- row.html | | `-- tail.html | `-- post.html
The templates directory is like the helpers directory and unlike the lists, shows, or views directories in that the code stored is not directly executed on CouchDB’s server side. Instead, the templates are included into the body of the list and show functions using macros run by CouchApp when pushing code to the server. These CouchApp macros are covered in Chapter 12. The key point is that the templates name could be anything. It is not a special member of the design document; just a convenient place to store and edit our template files.
|-- vendor | `-- couchapp | |-- README.md | |-- _attachments | | `-- jquery.couchapp.js | |-- couchapp.js | |-- date.js | |-- path.js | `-- template.js
The vendor directory holds code that is
managed independently of the Sofa application itself. In Sofa’s case,
the only vendor package used is
list and show URLs and render
couchapp push, files within a
vendor/**/_attachments/* path are pushed as design
document attachments. In this case,
jquery.couchapp.js will be pushed to an attachment called
couchapp/jquery.couchapp.js (so that multiple
vendor packages can have the same attachment names without worry of
`-- views |-- comments | |-- map.js | `-- reduce.js |-- recent-posts | `-- map.js `-- tags |-- map.js `-- reduce.js
The source code is safely on your hard drive, and you’ve even been
able to make minor edits to the blog.json file. Now
it’s time to deploy the blog to a local CouchDB. The
push command is simple and should work the first time,
but two other steps are involved in setting up an admin account on your
CouchDB and for your CouchApp
deployments. By the end of this chapter you’ll have your own running copy
couchapp push . sofa
This deploys the Sofa source code into CouchDB. You should see output like this:
[INFO] Pushing CouchApp in /Users/jchris/sofa to design doc: http://127.0.0.1:5984/sofa/_design/sofa [INFO] Visit your CouchApp here: http://127.0.0.1:5984/sofa/_design/sofa/_list/index/recent-posts?descending= true&limit=5
If you get an error, make sure your target CouchDB instance is running by making a simple HTTP request to it:
The response should look like:
If CouchDB is not running yet, go back to Chapter 3 and follow the “Hello World” instructions there.
Sofa is 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
section with your preferred username and password:
[admins] jchris = secretpass
Now that you’ve edited your local.ini configuration file, you need to restart CouchDB for changes to take effect. Depending on how you started CouchDB, there are different methods of restarting it. If you started in a console, then hitting Ctrl-C and rerunning the same command you used to start it is the simplest way.
If you don’t like your passwords lying around in plain-text files, don’t worry. When CouchDB starts up and reads this file, it takes your password and changes it to a secure 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.
Now that we’ve set up admin credentials, we’ll need to supply them
on the command line when running
couchapp push. Let’s
couchapp push . http://jchris:secretpass@localhost:5984/sofa
Make sure to replace
secretpass with your actual values or you will get a
“permission denied” error. If all works according to plan, everything
will be set up in CouchDB and you should be able to start using your
At this point, we are technically ready to move on, but you’ll be much happier if you make use of the .couchapprc file as documented in the next section.
If you don’t want to have to put the full URL (potentially including authentication parameters) of your database onto the command line each time you push, 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.
The .couchapprc file lives in the source
directory of your application, so you should look to see if it is at
/path/to/the/directory/of/sofa/.couchapprc (or create
it there if it is missing). Dot files (files with names that start with a
period) are left out of most directory listings. Use whatever tricks your
OS has to “show hidden files.” The simplest one in a standard command
shell is to list the directory using
ls -a, which will
show all hidden files as well as normal files.
With this file set up, you can push your CouchApp with the command
couchapp push, which will push the application to the
“default” database. CouchApp also supports alternate environments. To push
your application to a development database, you could use
couchapp push dev. In our experience, taking the time
to set up a good .couchapprc is always worth it.
Another benefit is that it keeps your passwords off the screen when you