In this section we will install and configure CouchApp
Before installing CouchApp, you need to install Apache CouchDB. You can download Apache CouchDB in a variety of formats, including as source, which you can build yourself, or as a standalone application for running on Windows™, Mac OS X and Linux®. For example, the Mac OS X application, Apache CouchDBX, runs as a standard application.
On Linux and UNIX®, you will get a binary, couchdb, which you can run from the command-line (see Listing 4).
Listing 4. Running the couchdb binary from the command-line
$ couchdb Apache CouchDB 1.0.1 (LogLevel=info) is starting. Apache CouchDB has started. Time to relax. [info] [<0.33.0>] Apache CouchDB has started on http://127.0.0.1:5984/
You are now ready to go! You can check that the database is running by accessing the given URL. If you want to open up your server so that it can be accessed over the network, change the bind parameter within the local.ini configuration file to match the IP address (not hostname) of your Apache CouchDB server.
For the CouchApp command line tool, you need to download the CouchApp tar or Zip package from GitHub (see Resources). You will need an installation of Python on your machine (if you do not already have it installed), but the CouchApp installer will handle all of the dependencies of additional libraries for you.
After you have downloaded the package, extract it, and then change into
the CouchApp directory:
$ cd couchapp.
Now run the Python setup tool to download and install any dependencies
and install the couchapp tool:
$ python setup.py install.
You can test the installation by running CouchApp, which should return
the help information for the tool:
Note: Normally you would not create a database that allows anybody to access and update it. Apache CouchDB does support authentication and different levels of security and authority for performing different operations, but we do not cover them in this tutorial.
As a good way of understanding the simplicity of Apache CouchDB, you
can create a new database within your Apache CouchDB instance from the
command using the curl command line tool. To create a database, you
PUT HTTP command to the URL of the
database you want to create. For example, to create a contact
database, you could use the command line:
$ curl -X PUT http://127.0.0.1:5984/contacts.
If you check the content of the file contacts, it should specify that the operation completed successfully.
Alternatively, go into Futon, using
http://127.0.0.1:5984/_utils. You can
create a new database using the Futon administration interface.
You now have an empty database. To create a stub application, you can
use CouchApp to generate all of the basic files that you need on your
file system ready to be uploaded to your Apache CouchDB database. You
can do this by running:
$ couchapp generate app contacts.
This creates a directory, contacts, which contains an array of files and contents that we can use to build our contacts application. You can see a top-level file list in Listing 5.
Listing 5. Top-level file list
$ ls -al contacts/ total 605- drwxrwxrwx 9 mcco mcco 4096 Dec 1 14:49 ./ drwxrwxrwx 3 mcco mcco 4096 Dec 1 14:49 ../ -rw-rw-rw- 1 mcco mcco 174 Dec 1 14:49 .couchappignore -rw-rw-rw- 1 mcco mcco 2 Dec 1 14:49 .couchapprc -rw-rw-rw- 1 mcco mcco 1660 Dec 1 11:51 README.md drwxrwxrwx 3 mcco mcco 4096 Dec 1 14:49 _attachments/ -rw-rw-rw- 1 mcco mcco 16 Dec 1 14:49 _id -rw-rw-rw- 1 mcco mcco 70 Dec 1 11:51 couchapp.json drwxrwxrwx 4 mcco mcco 4096 Dec 1 14:49 evently/ -rw-rw-rw- 1 mcco mcco 10 Dec 1 11:51 language drwxrwxrwx 2 mcco mcco 4096 Dec 1 14:49 lists/ drwxrwxrwx 2 mcco mcco 4096 Dec 1 14:49 shows/ drwxrwxrwx 2 mcco mcco 4096 Dec 1 14:49 updates/ drwxrwxrwx 3 mcco mcco 4096 Dec 1 14:49 vendor/ drwxrwxrwx 3 mcco mcco 4096 Dec 1 14:49 views/
Some of the major elements of this are:
Views are critical to the way you access information from the database when you don't know the document ID of the document you want to load. Lists and shows provide built-in methods for displaying information. However, you use other methods, such as the jQuery library, to get information out of the database using the view to return the list of documents that is then processed by the jQuery Apache CouchDB library.
The default document, index.html, is contained within the database attachments directory, contacts/_attachments/index.html. You should edit this to contain some default links to the database.
For that to work, you need to edit the index.html file to that shown in Listing 6.
Listing 6. Editing the index.html file
<!DOCTYPE html> <html> <head> <title>Contacts</title> <link rel="stylesheet" href="style/main.css" type="text/css"> <script src="vendor/couchapp/loader.js"></script> <script src="recordedit.js"></script> </head> <body> <div id="account"></div> <h1>Contacts</h1> <div id="items"><div id="add"><a href="#" class="add">Add Contact</a></div> <div id="contacts"></div> <div id="contactform"></div> </body> </html>
The key elements of structure are:
- The loading of the vendor/couchapp/loader.js script. This in turn loads the jQuery and jQuery Couch libraries, among others.
- A button that will be used to trigger the Add form for creating a new contact.
- A div element, with the id contacts, that will be used to display the contact list.
- A div element, with the id contactform, that will be used to display the contact form.
Once you have edited the file, you need to push the
application to your Apache CouchDB database using the CouchApp
$ couchapp push contacts http://127.0.0.1:5984/contacts.
The first argument is the instruction to push (publish) the
application, the second is the local directory, contacts, where the
application is stored, and the third is the URL of the Apache CouchDB
database where you want to upload the database. Once the push has
completed successfully, you can view the uploaded application using
It is worth dissecting this URL:
127.0.0.1:5984is the hostname, and port number, of the Apache CouchDB server. By default servers run on port 5984.
contactsis the name of the database.
_designis a special identifier to Apache CouchDB that indicates you want to access the design document. Design documents contain the view, list, and show definitions. You can have more than one design document for a given database.
contactsis the name of the design document. The CouchApp tool creates design document with the same name as your application by default.
index.htmlis the name of the attachment for the contacts design document.
CouchDB also includes a rewriting module that will simplify these URLs to something more friendly. See Resources for an article on this topic.
With the basic document in place, you can start to build the rest of the application.