Applications can live in CouchDB—nice. You just attach a bunch of HTML and JavaScript files to a design document and you are good to go. Spice that up with view-powered queries and show functions that render any media type from your JSON documents, and you have all it takes to write self-contained CouchDB applications.
Note
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.
In a CouchDB design document, 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 important, you’re already 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, 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
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. Once we have CouchApp, we’ll use it to install and deploy Sofa to a CouchDB database.
The CouchApp Python script and JavaScript 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).
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
it:
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 easy_install
itself. If you got an installation error, the best next step is to attempt
to upgrade setuptools and then upgrade CouchApp by
running the following commands:
sudo easy_install -U setuptools sudo easy_install -U couchapp
If you have other problems installing CouchApp, have a look at
setuptools
for Python’s easy install troubleshooting, or visit the CouchApp mailing list.
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
your system’s PATH so you can immediately begin by
running the help command:
couchapp --help
We’ll be using the clone and
push commands. 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
control.
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 clone
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
running the 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
application—the README and
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
The _attachments directory contains files that are saved to the Sofa design document as binary attachments. CouchDB serves attachments directly (instead of including them in a JSON wrapper), so this is where we store JavaScript, CSS, and HTML files that the browser will access directly.
Note
Making your first edit to the Sofa source code will show you how easy it is to modify the application.
|-- blog.json
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.
|-- couchapp.json
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 md5.js is
JSON-encoded and stored on the
design_document.helpers.md5 element.
|-- lists | `-- index.js
The lists directory contains a JavaScript function that will be executed by CouchDB to render view rows as Sofa’s HTML and Atom indexes. You could add new list functions by creating new files within this directory. Lists are covered in depth in Chapter 14.
|-- 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.
|-- validate_doc_update.js
This file corresponds to the JavaScript validation function used by Sofa to ensure that only the blog owner can create new posts, as well as to ensure that the comments are well formed. Sofa’s validation function is covered in detail in Chapter 12.
|-- 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 couchapp, which
contains JavaScript code that knows how to do things like link between
list and show URLs and render
templates.
During 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
collisions).
`-- views
|-- comments
| |-- map.js
| `-- reduce.js
|-- recent-posts
| `-- map.js
`-- tags
|-- map.js
`-- reduce.jsThe views directory holds MapReduce view definitions, with each view represented as a directory, holding files corresponding to map and reduce functions.
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
of Sofa.
Any time you make edits to the on-disk version of Sofa and want to see them in your browser, run the following command:
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:
curl http://127.0.0.1:5984
The response should look like:
{"couchdb":"Welcome","version":"0.10.1"}
If CouchDB is not running yet, go back to Chapter 3 and follow the “Hello World” instructions there.
If CouchDB was running, then couchapp push
should have directed you to visit the
application’s index URL. Visiting the URL should show you
something like Figure 11-2.
We’re not done yet—there are a couple of steps remaining before you’ve got a fully functional Sofa instance.
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 [admins]
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
try it:
couchapp push . http://jchris:secretpass@localhost:5984/sofa
Make sure to replace jchris and
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
blog.
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.
{"env":{"default":{"db":"http://jchris:secretpass@localhost:5984/sofa"},"staging":{"db":"http://jchris:secretpass@jchrisa.net:5984/sofa-staging"},"drl":{"db":"http://jchris:secretpass@jchrisa.net/drl"}}}
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
are working.
Get CouchDB: The Definitive Guide now with the O’Reilly learning platform.
O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.
