http://git-wip-us.apache.org/repos/asf/couchdb/blob/1055ea0e/share/docs/couchdb-manual-1.1/couchdb-configuration.xml ---------------------------------------------------------------------- diff --git a/share/docs/couchdb-manual-1.1/couchdb-configuration.xml b/share/docs/couchdb-manual-1.1/couchdb-configuration.xml new file mode 100644 index 0000000..ef1fd2b --- /dev/null +++ b/share/docs/couchdb-manual-1.1/couchdb-configuration.xml @@ -0,0 +1,328 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' + 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd'> +<chapter id="couchdb-single-configuration"> + + <title>Configuring CouchDB</title> + + <para> + + </para> + + <section id="couchdb-single-configuration-files"> + + <title>CouchDB Configuration Files</title> + + <para> + + </para> + + </section> + + <section id="couchdb-single-configuration-files-locations"> + + <title>Configuration File Locations</title> + + <para> + CouchDB reads files from the following locations, in the following + order. + </para> + + <orderedlist> + + <listitem> + <para> + <filename>PREFIX/default.ini</filename> + </para> + </listitem> + + <listitem> + <para> + <filename>PREFIX/default.d/*</filename> + </para> + </listitem> + + <listitem> + <para> + <filename>PREFIX/local.ini</filename> + </para> + </listitem> + + <listitem> + <para> + <filename>PREFIX/local.d/*</filename> + </para> + </listitem> + + </orderedlist> + + <para> + Settings in successive documents override the settings in earlier + entries. For example, setting the <literal>bind_address</literal> + parameter in <filename>local.ini</filename> would override any + setting in <literal>default.ini</literal>. + </para> + + <warning> + <para> + The <filename>default.ini</filename> file may be overwritten + during an upgrade or re-installation, so localised changes + should be made to the <filename>local.ini</filename> file or + files within the <filename>local.d</filename> directory. + </para> + </warning> + + </section> + + <section id="couchdb-single-configuration-mochiweb"> + + <title>MochiWeb Server Options</title> + + <para> + Server options for the MochiWeb component of CouchDB can be added + to the configuration files. Settings should be added to the + <literal>server_options</literal> option of the + <literal>[httpd]</literal> section of + <filename>local.ini</filename>. For example: + </para> + +<programlisting> +[httpd] +server_options = [{backlog, 128}, {acceptor_pool_size, 16}] + </programlisting> + + </section> + + <section id="couchdb-single-configuration-osprocess"> + + <title>OS Daemons</title> + + <para> + CouchDB now supports starting external processes. The support is + simple and enables CouchDB to start each configured OS daemon. If + the daemon stops at any point, CouchDB will restart it (with + protection to ensure regularly failing daemons are not repeatedly + restarted). + </para> + + <para> + The daemon starting process is one-to-one; for each each + configured daemon in the configuration file, CouchDB will start + exactly one instance. If you need to run multiple instances, then + you must create separate individual configurations. Daemons are + configured within the <literal>[os_daemons]</literal> section of + your configuration file (<filename>local.ini</filename>). The + format of each configured daemon is: + </para> + +<programlisting> +NAME = PATH ARGS + </programlisting> + + <para> + Where <literal>NAME</literal> is an arbitrary (and unique) name to + identify the daemon; <literal>PATH</literal> is the full path to + the daemon to be executed; <literal>ARGS</literal> are any + required arguments to the daemon. + </para> + + <para> + For example: + </para> + +<programlisting> +[os_daemons] +basic_responder = /usr/local/bin/responsder.js +</programlisting> + + <para> + There is no interactivity between CouchDB and the running process, + but you can use the OS Daemons service to create new HTTP servers + and responders and then use the new proxy service to redirect + requests and output to the CouchDB managed service. For more + information on proxying, see + <xref + linkend="couchdb-single-features-proxying"/>. For + further background on the OS Daemon service, see + <ulink url="http://davispj.com/2010/09/26/new-couchdb-externals-api.html";>CouchDB + Externals API</ulink> + </para> + + </section> + + <section id="couchdb-single-configuration-update_notification"> + + <title>Update Notifications</title> + + <para> + + </para> + + </section> + + <section id="couchdb-single-configuration-socketoptions"> + + <title>Socket Options Configuration Setting</title> + + <para> + The socket options for the listening socket in CouchDB can now be + set within the CouchDB configuration file. The setting should be + added to the <literal>[httpd]</literal> section of the file using + the option name <literal>socket_options</literal>. The + specification is as a list of tuples. For example: + </para> + +<programlisting> +[httpd] +socket_options = [{recbuf, 262144}, {sndbuf, 262144}, {nodelay, true}] +</programlisting> + + <para> + The options supported are a subset of full options supported by + the TCP/IP stack. A list of the supported options are provided in + the + <ulink + url="http://www.erlang.org/doc/man/inet.html#setopts-2";>Erlang + inet</ulink> documentation. + </para> + + </section> + + <section id="couchdb-single-configuration-vhost"> + + <title><literal>vhosts</literal> definitions</title> + + <para> + Similar to the rewrites section of a <literal>_design</literal> + document, the <literal>vhosts</literal> system uses variables in + the form of :varname or wildcards in the form of asterisks. The + variable results can be output into the resulting path as they are + in the rewriter. + </para> + + </section> + + <section id="couchdb-single-configuration-ssl"> + + <title>Configuring SSL Network Sockets</title> + + <para> + SSL configuration in CouchDB was designed to be as easy as + possible. All you need is two files; a certificate and a private + key. If you bought an official SSL certificate from a certificate + authority, both should be in your possession already. + </para> + + <para> + If you just want to try this out and don't want to pay anything + upfront, you can create a self-signed certificate. Everything will + work the same, but clients will get a warning about an insecure + certificate. + </para> + + <para> + You will need the OpenSSL command line tool installed. It probably + already is. + </para> + +<programlisting> +shell> <userinput>mkdir cert && cd cert</userinput> +shell> <userinput>openssl genrsa > privkey.pem</userinput> +shell> <userinput>openssl req -new -x509 -key privkey.pem -out mycert.pem -days 1095</userinput> +shell> <userinput>ls</userinput> +mycert.pem privkey.pem +</programlisting> + + <para> + Now, you need to edit CouchDB's configuration, either by editing + your <filename>local.ini</filename> file or using the + <literal>/_config</literal> API calls or the configuration screen + in Futon. Here is what you need to do in + <filename>local.ini</filename>, you can infer what needs doing in + the other places. + </para> + + <para> + Be sure to make these edits. Under <literal>[daemons]</literal> + you should see: + </para> + +<programlisting> +; enable SSL support by uncommenting the following line and supply the PEM's below. +; the default ssl port CouchDB listens on is 6984 +;httpsd = {couch_httpd, start_link, [https]} +</programlisting> + + <para> + Here uncomment the last line: + </para> + +<programlisting> +httpsd = {couch_httpd, start_link, [https]} +</programlisting> + + <para> + Next, under <literal>[ssl]</literal> you will see: + </para> + +<programlisting> +;cert_file = /full/path/to/server_cert.pem +;key_file = /full/path/to/server_key.pem +</programlisting> + + <para> + Uncomment and adjust the paths so it matches your system's paths: + </para> + +<programlisting> +cert_file = /home/jan/cert/mycert.pem +key_file = /home/jan/cert/privkey.pem +</programlisting> + + <para> + For more information please read + <ulink + url="http://www.openssl.org/docs/HOWTO/certificates.txt";>http://www.openssl.org/docs/HOWTO/certificates.txt</ulink>. + </para> + + <para> + Now start (or restart) CouchDB. You should be able to connect to + it using HTTPS on port 6984: + </para> + +<programlisting> +shell> <userinput>curl https://127.0.0.1:6984/</userinput> +curl: (60) SSL certificate problem, verify that the CA cert is OK. Details: +error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed +More details here: http://curl.haxx.se/docs/sslcerts.html + +curl performs SSL certificate verification by default, using a "bundle" +of Certificate Authority (CA) public keys (CA certs). If the default +bundle file isn't adequate, you can specify an alternate file +using the --cacert option. +If this HTTPS server uses a certificate signed by a CA represented in +the bundle, the certificate verification probably failed due to a +problem with the certificate (it might be expired, or the name might +not match the domain name in the URL). +If you'd like to turn off curl's verification of the certificate, use +the -k (or --insecure) option. +</programlisting> + + <para> + Oh no what happened?! â Remember, clients will notify their + users that your certificate is self signed. + <command>curl</command> is the client in this case and it notifies + you. Luckily you trust yourself (don't you?) and you can specify + the <option>-k</option> option as the message reads: + </para> + +<programlisting> +shell> <userinput>curl -k https://127.0.0.1:6984/</userinput> +{"couchdb":"Welcome","version":"1.1.0"} +</programlisting> + + </section> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="metadoc-couchdb-config-options.xml"/> + +</chapter>
http://git-wip-us.apache.org/repos/asf/couchdb/blob/1055ea0e/share/docs/couchdb-manual-1.1/couchdb-dbmaint.xml ---------------------------------------------------------------------- diff --git a/share/docs/couchdb-manual-1.1/couchdb-dbmaint.xml b/share/docs/couchdb-manual-1.1/couchdb-dbmaint.xml new file mode 100644 index 0000000..bdd4184 --- /dev/null +++ b/share/docs/couchdb-manual-1.1/couchdb-dbmaint.xml @@ -0,0 +1,15 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' + 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [ +<!ENTITY % every.entities SYSTEM "entities.ent"> +%every.entities; +]> +<chapter id="couchdb-single-dbmaint"> + + <title>Database Maintenance</title> + + <para> + + </para> + +</chapter> http://git-wip-us.apache.org/repos/asf/couchdb/blob/1055ea0e/share/docs/couchdb-manual-1.1/couchdb-features.xml ---------------------------------------------------------------------- diff --git a/share/docs/couchdb-manual-1.1/couchdb-features.xml b/share/docs/couchdb-manual-1.1/couchdb-features.xml new file mode 100644 index 0000000..3c7edc3 --- /dev/null +++ b/share/docs/couchdb-manual-1.1/couchdb-features.xml @@ -0,0 +1,301 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' + 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [ +<!ENTITY % every.entities SYSTEM "entities.ent"> +%every.entities; +]> +<chapter id="couchdb-single-features"> + + <title>Features and Functionality</title> + + <para> + + </para> + + <section id="couchdb-single-features-httprange"> + + <title>HTTP Range Requests</title> + + <para> + HTTP allows you to specify byte ranges for requests. This allows + the implementation of resumable downloads and skippable audio and + video streams alike. The following example uses a text file to + make the range request process easier. + </para> + +<programlisting> +shell> <userinput>cat file.txt</userinput> +My hovercraft is full of eels! +</programlisting> + + <para> + Uploading this as an attachment to a <literal>text</literal> + database using <command>curl</command>: + </para> + +<programlisting> +shell> <userinput>curl -X PUT http://127.0.0.1:5984/test/doc/file.txt \ + -H "Content-Type: application/octet-stream" [email protected]</userinput> +{"ok":true,"id":"doc","rev":"1-287a28fa680ae0c7fb4729bf0c6e0cf2"} +</programlisting> + + <para> + Requesting the whole file works as normal: + </para> + +<programlisting> +shell> <userinput>curl -X GET http://127.0.0.1:5984/test/doc/file.txt</userinput> +My hovercraft is full of eels! +</programlisting> + + <para> + But to retrieve only the first 13 bytes using + <command>curl</command>: + </para> + +<programlisting> +shell> <userinput>curl -X GET http://127.0.0.1:5984/test/doc/file.txt -H "Range: bytes=0-12"</userinput> +My hovercraft +</programlisting> + + <para> + HTTP supports many ways to specify single and even multiple byte + rangers. See + <ulink + url="http://tools.ietf.org/html/rfc2616#section-14.27";>RFC + 2616</ulink>. + </para> + + <note> + <para> + Databases that have been created with CouchDB 1.0.2 or earlier + will support range requests in 1.1.0, but they are using a + less-optimal algorithm. If you plan to make heavy use of this + feature, make sure to compact your database with CouchDB 1.1.0 + to take advantage of a better algorithm to find byte ranges. + </para> + </note> + + </section> + + <section id="couchdb-single-features-proxying"> + + <title>HTTP Proxying</title> + + <para> + The HTTP proxy feature makes it easy to map and redirect different + content through your CouchDB URL. The proxy works by mapping a + pathname and passing all content after that prefix through to the + configured proxy address. + </para> + + <para> + Configuration of the proxy redirect is handled through the + <literal>[httpd_global_handlers]</literal> section of the CouchDB + configuration file (typically <filename>local.ini</filename>). The + format is: + </para> + +<programlisting> +[httpd_global_handlers] +PREFIX = {couch_httpd_proxy, handle_proxy_req, <<"DESTINATION">>} + </programlisting> + + <para> + Where: + </para> + + <itemizedlist> + + <listitem> + <para> + <literal>PREFIX</literal> + </para> + + <para> + Is the string that will be matched. The string can be any + valid qualifier, although to ensure that existing database + names are not overridden by a proxy configuration, you can use + an underscore prefix. + </para> + </listitem> + + <listitem> + <para> + <literal>DESTINATION</literal> + </para> + + <para> + The fully-qualified URL to which the request should be sent. + The destination must include the <literal>http</literal> + prefix. The content is used verbatim in the original request, + so you can also forward to servers on different ports and to + specific paths on the target host. + </para> + </listitem> + + </itemizedlist> + + <para> + The proxy process then translates requests of the form: + </para> + +<programlisting> +http://couchdb:5984/PREFIX/path +</programlisting> + + <para> + To: + </para> + +<programlisting> +DESTINATION/path +</programlisting> + + <note> + <para> + Everything after <literal>PREFIX</literal> including the + required forward slash will be appended to the + <literal>DESTINATION</literal>. + </para> + </note> + + <para> + The response is then communicated back to the original client. + </para> + + <para> + For example, the following configuration: + </para> + +<programlisting> +<![CDATA[ +_google = {couch_httpd_proxy, handle_proxy_req, <<"http://www.google.com";>>}]]> +</programlisting> + + <para> + Would forward all requests for + <literal>http://couchdb:5984/_google</literal> to the Google + website. + </para> + + <para> + The service can also be used to forward to related CouchDB + services, such as Lucene: + </para> + +<programlisting> + <![CDATA[ +[httpd_global_handlers] +_fti = {couch_httpd_proxy, handle_proxy_req, <<"http://127.0.0.1:5985";>>}]]> +</programlisting> + + <note> + <para> + The proxy service is basic. If the request is not identified by + the <literal>DESTINATION</literal>, or the remainder of the + <literal>PATH</literal> specification is incomplete, the + original request URL is interpreted as if the + <literal>PREFIX</literal> component of that URL does not exist. + </para> + + <para> + For example, requesting + <literal>http://couchdb:5984/_intranet/media</literal> when + <filename>/media</filename> on the proxy destination does not + exist, will cause the request URL to be interpreted as + <literal>http://couchdb:5984/media</literal>. Care should be + taken to ensure that both requested URLs and destination URLs + are able to cope + </para> + </note> + + </section> + + <section id="couchdb-single-features-commonjs"> + + <title>CommonJS support for map functions</title> + + <para> + CommonJS support allows you to use CommonJS notation inside + <methodname>map</methodname> and <methodname>reduce</methodname> + functions, but only of libraries that are stored inside the views + part of the design doc. + </para> + + <para> + So you could continue to access CommonJS code in design_doc.foo, + from your list functions etc, but we'd add the ability to require + CommonJS modules within map and reduce, but only from + <filename>design_doc.views.lib</filename>. + </para> + + <para> + There's no worry here about namespace collisions, as Couch just + plucks <literal>views.*.map</literal> and + <literal>views.*.reduce</literal> out of the design doc. So you + could have a view called <literal>lib</literal> if you wanted, and + still have CommonJS stored in <literal>views.lib.sha1</literal> + and <literal>views.lib.stemmer</literal> if you wanted. + </para> + + <para> + The implementation is simplified by enforcing that CommonJS + modules to be used in <methodname>map</methodname> functions be + stored in views.lib. + </para> + + <para> + A sample design doc (taken from the test suite in Futon) is below: + </para> + +<programlisting> +{ + "views" : { + "lib" : { + "baz" : "exports.baz = 'bam';", + "foo" : { + "zoom" : "exports.zoom = 'yeah';", + "boom" : "exports.boom = 'ok';", + "foo" : "exports.foo = 'bar';" + } + }, + "commonjs" : { + "map" : "function(doc) { emit(null, require('views/lib/foo/boom').boom)}" + } + }, + "_id" : "_design/test" +} +</programlisting> + + <para> + The <literal>require()</literal> statement is relative to the + design document, but anything loaded form outside of + <literal>views/lib</literal> will fail. + </para> + + </section> + + <section id="couchdb-single-features-etag"> + + <title>Granular ETag support</title> + + <para> + ETags have been assigned to a map/reduce group (the collection of + views in a single design document). Any change to any of the + indexes for those views would generate a new ETag for all view + URL's in a single design doc, even if that specific view's results + had not changed. + </para> + + <para> + In CouchDB 1.1 each <literal>_view</literal> URL has it's own ETag + which only gets updated when changes are made to the database that + effect that index. If the index for that specific view does not + change, that view keeps the original ETag head (therefore sending + back 304 Not Modified more often). + </para> + + </section> + +</chapter> http://git-wip-us.apache.org/repos/asf/couchdb/blob/1055ea0e/share/docs/couchdb-manual-1.1/couchdb-introduction.xml ---------------------------------------------------------------------- diff --git a/share/docs/couchdb-manual-1.1/couchdb-introduction.xml b/share/docs/couchdb-manual-1.1/couchdb-introduction.xml new file mode 100644 index 0000000..15c123b --- /dev/null +++ b/share/docs/couchdb-manual-1.1/couchdb-introduction.xml @@ -0,0 +1,578 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' + 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [ +<!ENTITY % every.entities SYSTEM "entities.ent"> +%every.entities; +]> +<chapter id="couchdb-single-introduction"> + + <title>Introduction</title> + + <para> + There are two interfaces to CouchDB, the built-in + Futon web-based interface and the CouchDB API accessed through the + HTTP REST interface. The former is the simplest way to view and + monitor your CouchDB installation and perform a + number of basic database and system operations. More information on + using the Futon interface can be found in + <xref linkend="couchdb-single-introduction-futon"/>. + </para> + + <para> + The primary way to interact with the CouchDB API is to use a client + library or other interface that provides access to the underlying + functionality through your chosen language or platform. However, + since the API is supported through HTTP REST, you can interact with + your CouchDB with any solution that supports the + HTTP protocol. + </para> + + <para> + There are a number of different tools that talk the HTTP protocol + and allow you to set and configure the necessary information. One + tool for this that allows for access from the command-line is + <command>curl</command>. See + <xref + linkend="couchdb-single-introduction-curl"/>. + </para> + + <section id="couchdb-single-introduction-futon"> + + <title>Using Futon</title> + + <para> + Futon is a native web-based interface built into CouchDB. It provides a basic interface to the majority of the + functionality, including the ability to create, update, delete and + view documents and views, provides access to the configuration + parameters, and an interface for initiating replication. + </para> + + <para> + The default view is the <guilabel>Overview</guilabel> page which + provides you with a list of the databases. The basic structure of + the page is consistent regardless of the section you are in. The + main panel on the left provides the main interface to the + databases, configuration or replication systems. The side panel on + the right provides navigation to the main areas of Futon + interface: + </para> + + <figure id="fig-ccouchdb-single-introduction-futon-overview"> + + <title>Futon Overview</title> + + <mediaobject> + + <imageobject> + + <imagedata width="100%" contentdepth="100%" scalefit="1" +fileref="images/futon-overview.png" +format="PNG" lang="en"/> + + </imageobject> + + <textobject> + + <phrase lang="en">Futon Overview</phrase> + + </textobject> + + </mediaobject> + + </figure> + + <para> + The main sections are: + </para> + + <itemizedlist> + + <listitem> + <para> + <guibutton>Overview</guibutton> + </para> + + <para> + The main overview page, which provides a list of the databases + and provides the interface for querying the database and + creating and updating documents. See + <xref + linkend="couchdb-single-introduction-futon-dbdocs"/>. + </para> + </listitem> + + <listitem> + <para> + <guibutton>Configuration</guibutton> + </para> + + <para> + An interface into the configuration of your CouchDB installation. The interface allows you to edit the + different configurable parameters. For more details on + configuration, see + <xref + linkend="couchdb-single-configuration"/>. + </para> + </listitem> + + <listitem> + <para> + <guibutton>Replicator</guibutton> + </para> + + <para> + An interface to the replication system, enabling you to + initiate replication between local and remote databases. See + <xref + linkend="couchdb-single-introduction-futon-replication"/>. + </para> + </listitem> + + <listitem> + <para> + <guibutton>Status</guibutton> + </para> + + <para> + Displays a list of the running background tasks on the server. + Background tasks include view index building, compaction and + replication. The <guibutton>Status</guibutton> page is an + interface to the + <link linkend="couchdb-api-misc_active-tasks_get">Active + Tasks</link> API call. See + <xref + linkend="couchdb-api-misc_active-tasks_get"/>. + </para> + </listitem> + + <listitem> + <para> + <guibutton>Verify Installation</guibutton> + </para> + + <para> + The <guibutton>Verify Installation</guibutton> allows you to + check whether all of the components of your CouchDB installation are correctly installed. + </para> + </listitem> + + <listitem> + <para> + <guibutton>Test Suite</guibutton> + </para> + + <para> + The <guibutton>Test Suite</guibutton> section allows you to + run the built-in test suite. This executes a number of test + routines entirely within your browser to test the API and + functionality of your CouchDB installation. If + you select this page, you can run the tests by using the + <guibutton>Run All</guibutton> button. This will execute all + the tests, which may take some time. + </para> + </listitem> + + </itemizedlist> + + <section id="couchdb-single-introduction-futon-dbdocs"> + + <title>Managing Databases and Documents</title> + + <para> + You can manage databases and documents within Futon using the + main <guibutton>Overview</guibutton> section of the Futon + interface. + </para> + + <para> + To create a new database, click the <guibutton>Create Database + &ellipsis;</guibutton> button. You will be prompted for the + database name, as shown in the figure below. + </para> + + <figure id="fig-ccouchdb-single-introduction-futon-dbdocs-createdb"> + + <title>Creating a Database</title> + + <mediaobject> + + <imageobject> + + <imagedata width="100%" contentdepth="100%" scalefit="1" +fileref="images/futon-createdb.png" +format="PNG" lang="en"/> + + </imageobject> + + <textobject> + + <phrase lang="en">Creating a Database</phrase> + + </textobject> + + </mediaobject> + + </figure> + + <para> + Once you have created the database (or selected an existing + one), you will be shown a list of the current documents. If you + create a new document, or select an existing document, you will + be presented with the edit document display. + </para> + + <para> + Editing documents within Futon requires selecting the document + and then editing (and setting) the fields for the document + individually before saving the document back into the database. + </para> + + <para> + For example, the figure below shows the editor for a single + document, a newly created document with a single ID, the + document <literal>_id</literal> field. + </para> + + <figure id="fig-ccouchdb-single-introduction-futon-dbdocs-editdoc"> + + <title>Editing a Document</title> + + <mediaobject> + + <imageobject> + + <imagedata width="100%" contentdepth="100%" scalefit="1" +fileref="images/futon-editdoc.png" +format="PNG" lang="en"/> + + </imageobject> + + <textobject> + + <phrase lang="en">Editing a Document</phrase> + + </textobject> + + </mediaobject> + + </figure> + + <para> + To add a field to the document: + </para> + + <orderedlist> + + <listitem> + <para> + Click <guibutton>Add Field</guibutton>. + </para> + </listitem> + + <listitem> + <para> + In the fieldname box, enter the name of the field you want + to create. For example, <quote>company</quote>. + </para> + </listitem> + + <listitem> + <para> + Click the green tick next to the field name to confirm the + field name change. + </para> + </listitem> + + <listitem> + <para> + Double-click the corresponding <guilabel>Value</guilabel> + cell. + </para> + </listitem> + + <listitem> + <para> + Enter a company name, for example <quote>Example</quote>. + </para> + </listitem> + + <listitem> + <para> + Click the green tick next to the field value to confirm the + field value. + </para> + </listitem> + + <listitem> + <para> + The document is still not saved as this point. You must + explicitly save the document by clicking the <guibutton>Save + Document</guibutton> button at the top of the page. This + will save the document, and then display the new document + with the saved revision information (the + <literal>_rev</literal> field). + </para> + + <figure + id="fig-ccouchdb-single-introduction-futon-dbdocs-finaldoc"> + + <title>Edited Document</title> + + <mediaobject> + + <imageobject> + + <imagedata width="100%" contentdepth="100%" scalefit="1" +fileref="images/futon-editeddoc.png" +format="PNG" lang="en"/> + + </imageobject> + + <textobject> + + <phrase lang="en">Edited Document</phrase> + + </textobject> + + </mediaobject> + + </figure> + </listitem> + + </orderedlist> + + <para> + The same basic interface is used for all editng operations + within Futon. You <emphasis>must</emphasis> rememmbr to save the + individual element (fieldname, value) using the green tick + button, before then saving the document. + </para> + + </section> + + <section id="couchdb-single-introduction-futon-replication"> + + <title>Configuring Replication</title> + + <para> + When you click the <guibutton>Replicator</guibutton> option + within the <guilabel>Tools</guilabel> menu you are presented + with the Replicator screen. This allows you to start replication + between two databases by filling in or select the appropriate + options within the form provided. + </para> + + <figure + id="fig-ccouchdb-single-introduction-futon-replication-form"> + + <title>Replication Form</title> + + <mediaobject> + + <imageobject> + + <imagedata width="100%" contentdepth="100%" scalefit="1" +fileref="images/futon-replform.png" +format="PNG" lang="en"/> + + </imageobject> + + <textobject> + + <phrase lang="en">Replication Form</phrase> + + </textobject> + + </mediaobject> + + </figure> + + <para> + To start a replication process, either the select the local + database or enter a remote database name into the corresponding + areas of the form. Replication occurs from the database on the + left to the database on the right. + </para> + + <para> + If you are specifying a remote database name, you must specify + the full URL of the remote database (including the host, port + number and database name). If the remote instance requires + authentication, you can specify the username and password as + part of the URL, for example + <literal>http://username:pass@remotehost:5984/demo</literal>. + </para> + + <para> + To enable continuous replication, click the + <guilabel>Continuous</guilabel> checkbox. + </para> + + <para> + To start the replication process, click the + <guibutton>Replicate</guibutton> button. The replication process + should start and will continue in the background. If the + replication process will take a long time, you can monitor the + status of the replication using the + <guibutton>Status</guibutton> option under the + <guilabel>Tools</guilabel> menu. + </para> + + <para> + Once replication has been completed, the page will show the + information returned when the replication process completes by + the API. + </para> + + <para> + The <guilabel>Replicator</guilabel> tool is an interface to the + underlying replication API. For more information, see + <xref + linkend="couchdb-api-misc_replicate_post"/>. + For more information on replication, see + <xref linkend="couchdb-single-replication"/>. + </para> + + </section> + + </section> + + <section id="couchdb-single-introduction-curl"> + + <title>Using <command>curl</command></title> + + <para> + The <command>curl</command> utility is a command line tool + available on Unix, Linux, Mac OS X and Windows and many other + platforms. <command>curl</command> provides easy access to the + HTTP protocol (among others) directly from the command-line and is + therefore an ideal way of interacting with CouchDB + over the HTTP REST API. + </para> + + <para> + For simple <literal>GET</literal> requests you can supply the URL + of the request. For example, to get the database information: + </para> + +<programlisting> +shell> <userinput>curl http://127.0.0.1:5984</userinput> +</programlisting> + + <para> + This returns the database information (formatted in the output + below for clarity): + </para> + +<programlisting> +{ + "modules" : { + "geocouch" : "7fd793c10f3aa667a1088a937398bc5b51472b7f" + }, + "couchdb" : "Welcome", + "version" : "1.1.0", +} +</programlisting> + + <note> + <para> + For some URLs, especially those that include special characters + such as ampersand, exclamation mark, or question mark, you + should quote the URL you are specifying on the command line. For + example: + </para> + +<programlisting> +shell> <userinput>curl 'http://couchdb:5984/_uuids?count=5'</userinput> +</programlisting> + </note> + + <para> + You can explicitly set the HTTP command using the + <option>-X</option> command line option. For example, when + creating a database, you set the name of the database in the URL + you send using a PUT request: + </para> + +<programlisting> +shell> <userinput>curl -X PUT http://127.0.0.1:5984/demo</userinput> +{"ok":true} +</programlisting> + + <para> + But to obtain the database information you use a + <literal>GET</literal> request (with the return information + formatted for clarity): + </para> + +<programlisting> +shell> <userinput>curl -X GET http://127.0.0.1:5984/demo</userinput> +{ + "compact_running" : false, + "doc_count" : 0, + "db_name" : "demo", + "purge_seq" : 0, + "committed_update_seq" : 0, + "doc_del_count" : 0, + "disk_format_version" : 5, + "update_seq" : 0, + "instance_start_time" : "1306421773496000", + "disk_size" : 79 +} +</programlisting> + + <para> + For certain operations, you must specify the content type of + request, which you do by specifying the + <literal>Content-Type</literal> header using the + <option>-H</option> command-line option: + </para> + +<programlisting> +shell> <userinput>curl -H 'Content-type: application/json' http://127.0.0.1:5984/_uuids</userinput> +</programlisting> + + <para> + You can also submit 'payload' data, that is, data in the body of + the HTTP request using the <option>-d</option> option. This is + useful if you need to submit JSON structures, for example document + data, as part of the request. For example, to submit a simple + document to the <literal>demo</literal> database: + </para> + +<programlisting> +shell> <userinput>curl -H 'Content-type: application/json' \ + -X POST http://127.0.0.1:5984/demo \ + -d '{"company": "Example, Inc."}'</userinput> +{"ok":true,"id":"8843faaf0b831d364278331bc3001bd8", + "rev":"1-33b9fbce46930280dab37d672bbc8bb9"} +</programlisting> + + <para> + In the above example, the argument after the <option>-d</option> + option is the JSON of the document we want to submit. + </para> + + <para> + The document can be accessed by using the automatically generated + document ID that was returned: + </para> + +<programlisting> +shell> <userinput>curl -X GET http://127.0.0.1:5984/demo/8843faaf0b831d364278331bc3001bd8</userinput> +{"_id":"8843faaf0b831d364278331bc3001bd8", + "_rev":"1-33b9fbce46930280dab37d672bbc8bb9", + "company":"Example, Inc."} +</programlisting> + + <para> + The API samples in the <xref linkend="couchdb-api-basics"/> show + the HTTP command, URL and any payload information that needs to be + submitted (and the expected return value). All of these examples + can be reproduced using <command>curl</command> with the + command-line examples shown above. + </para> + + </section> + +</chapter>
