http://git-wip-us.apache.org/repos/asf/couchdb/blob/5cb488bf/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 deleted file mode 100644 index ef1fd2b..0000000 --- a/share/docs/couchdb-manual-1.1/couchdb-configuration.xml +++ /dev/null @@ -1,328 +0,0 @@ -<?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/5cb488bf/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 deleted file mode 100644 index bdd4184..0000000 --- a/share/docs/couchdb-manual-1.1/couchdb-dbmaint.xml +++ /dev/null @@ -1,15 +0,0 @@ -<?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/5cb488bf/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 deleted file mode 100644 index 3c7edc3..0000000 --- a/share/docs/couchdb-manual-1.1/couchdb-features.xml +++ /dev/null @@ -1,301 +0,0 @@ -<?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/5cb488bf/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 deleted file mode 100644 index 15c123b..0000000 --- a/share/docs/couchdb-manual-1.1/couchdb-introduction.xml +++ /dev/null @@ -1,578 +0,0 @@ -<?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>
