couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From d..@apache.org
Subject [41/49] import CouchBase docs
Date Fri, 14 Sep 2012 10:17:00 GMT
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>
+    &nbsp;
+  </para>
+
+  <section id="couchdb-single-configuration-files">
+
+    <title>CouchDB Configuration Files</title>
+
+    <para>
+      &nbsp;
+    </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>
+      &nbsp;
+    </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&gt; <userinput>mkdir cert &amp;&amp; cd cert</userinput>
+shell&gt; <userinput>openssl genrsa > privkey.pem</userinput>
+shell&gt; <userinput>openssl req -new -x509 -key privkey.pem -out mycert.pem -days
1095</userinput>
+shell&gt; <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&gt; <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&gt; <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>
+    &nbsp;
+  </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>
+    &nbsp;
+  </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&gt; <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&gt; <userinput>curl -X PUT http://127.0.0.1:5984/test/doc/file.txt \
+    -H "Content-Type: application/octet-stream" -d@file.txt</userinput>
+{"ok":true,"id":"doc","rev":"1-287a28fa680ae0c7fb4729bf0c6e0cf2"}
+</programlisting>
+
+    <para>
+      Requesting the whole file works as normal:
+    </para>
+
+<programlisting>
+shell&gt; <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&gt; <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, &lt;&lt;"DESTINATION"&gt;&gt;}
+  </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&gt; <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&gt; <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&gt; <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&gt; <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&gt; <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&gt; <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&gt; <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>


Mime
View raw message