You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by kx...@apache.org on 2014/10/16 11:09:18 UTC
[06/14] Documentation was moved to couchdb-documentation repository
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cdac7299/share/doc/src/install/unix.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/install/unix.rst b/share/doc/src/install/unix.rst
deleted file mode 100644
index 76fe922..0000000
--- a/share/doc/src/install/unix.rst
+++ /dev/null
@@ -1,272 +0,0 @@
-.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
-.. use this file except in compliance with the License. You may obtain a copy of
-.. the License at
-..
-.. http://www.apache.org/licenses/LICENSE-2.0
-..
-.. Unless required by applicable law or agreed to in writing, software
-.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-.. License for the specific language governing permissions and limitations under
-.. the License.
-
-
-.. _install/unix:
-
-=================================
-Installation on Unix-like systems
-=================================
-
-A high-level guide to Unix-like systems, inc. Mac OS X and Ubuntu.
-
-This document is the canonical source of installation information. However, many
-systems have gotchas that you need to be aware of. In addition, dependencies
-frequently change as distributions update their archives. If you're running into
-trouble, be sure to check out the wiki. If you have any tips to share, please
-also update the wiki so that others can benefit from your experience.
-
-.. seealso::
-
- `Community installation guides`_
-
-.. _Community installation guides: http://wiki.apache.org/couchdb/Installation
-
-Troubleshooting
----------------
-
-* There is a `troubleshooting guide`_.
-* There is a `wiki`_ for general documentation.
-* There are collection of `friendly mailing lists`_.
-
-Please work through these in order if you experience any problems.
-
-.. _troubleshooting guide: http://wiki.apache.org/couchdb/Troubleshooting
-.. _wiki: http://wiki.apache.org/couchdb
-.. _friendly mailing lists: http://couchdb.apache.org/community/lists.html
-
-
-.. _install/unix/dependencies:
-
-Dependencies
-------------
-
-You should have the following installed:
-
-* `Erlang OTP (>=R14B01, =<R17) <http://erlang.org/>`_
-* `ICU <http://icu-project.org/>`_
-* `OpenSSL <http://www.openssl.org/>`_
-* `Mozilla SpiderMonkey (1.8.5) <http://www.mozilla.org/js/spidermonkey/>`_
-* `GNU Make <http://www.gnu.org/software/make/>`_
-* `GNU Compiler Collection <http://gcc.gnu.org/>`_
-* `libcurl <http://curl.haxx.se/libcurl/>`_
-* `help2man <http://www.gnu.org/s/help2man/>`_
-* `Python (>=2.7) for docs <http://python.org/>`_
-* `Python Sphinx (>=1.1.3) <http://pypi.python.org/pypi/Sphinx>`_
-
-It is recommended that you install Erlang OTP R13B-4 or above where possible.
-You will only need libcurl if you plan to run the JavaScript test suite. And
-help2man is only need if you plan on installing the CouchDB man pages.
-Python and Sphinx are only required for building the online documentation.
-
-Debian-based Systems
-~~~~~~~~~~~~~~~~~~~~
-
-You can install the dependencies by running::
-
- sudo apt-get install build-essential
- sudo apt-get install erlang-base-hipe
- sudo apt-get install erlang-dev
- sudo apt-get install erlang-manpages
- sudo apt-get install erlang-eunit
- sudo apt-get install erlang-nox
- sudo apt-get install libicu-dev
- sudo apt-get install libmozjs-dev
- sudo apt-get install libcurl4-openssl-dev
-
-There are lots of Erlang packages. If there is a problem with your install, try
-a different mix. There is more information on the wiki. Additionally, you might
-want to install some of the optional Erlang tools which may also be useful.
-
-Be sure to update the version numbers to match your system's available packages.
-
-Unfortunately, it seems that installing dependencies on Ubuntu is troublesome.
-
-.. seealso::
-
- * `Installing on Debian <http://wiki.apache.org/couchdb/Installing_on_Debian>`_
- * `Installing on Ubuntu <http://wiki.apache.org/couchdb/Installing_on_Ubuntu>`_
-
-
-RedHat-based (Fedora, Centos, RHEL) Systems
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You can install the dependencies by running::
-
- sudo yum install autoconf
- sudo yum install autoconf-archive
- sudo yum install automake
- sudo yum install curl-devel
- sudo yum install erlang-asn1
- sudo yum install erlang-erts
- sudo yum install erlang-eunit
- sudo yum install erlang-os_mon
- sudo yum install erlang-xmerl
- sudo yum install help2man
- sudo yum install js-devel
- sudo yum install libicu-devel
- sudo yum install libtool
- sudo yum install perl-Test-Harness
-
-While CouchDB builds against the default js-devel-1.7.0 included in some
-distributions, it's recommended to use a more recent js-devel-1.8.5.
-
-Mac OS X
-~~~~~~~~
-
-Follow :ref:`install/mac/homebrew` reference till `brew install couchdb` step.
-
-
-Installing
-----------
-
-Once you have satisfied the dependencies you should run::
-
- ./configure
-
-This script will configure CouchDB to be installed into `/usr/local` by default.
-
-If you wish to customise the installation, pass `--help` to this script.
-
-If everything was successful you should see the following message::
-
- You have configured Apache CouchDB, time to relax.
-
-Relax.
-
-To install CouchDB you should run::
-
- make && sudo make install
-
-You only need to use `sudo` if you're installing into a system directory.
-
-Try `gmake` if `make` is giving you any problems.
-
-If everything was successful you should see the following message::
-
- You have installed Apache CouchDB, time to relax.
-
-Relax.
-
-First Run
----------
-
-You can start the CouchDB server by running::
-
- sudo -i -u couchdb couchdb
-
-This uses the `sudo` command to run the `couchdb` command as the `couchdb` user.
-
-When CouchDB starts it should eventually display the following message::
-
- Apache CouchDB has started, time to relax.
-
-Relax.
-
-To check that everything has worked, point your web browser to::
-
- http://127.0.0.1:5984/_utils/index.html
-
-From here you should verify your installation by pointing your web browser to::
-
- http://localhost:5984/_utils/verify_install.html
-
-Security Considerations
------------------------
-
-You should create a special `couchdb` user for CouchDB.
-
-On many Unix-like systems you can run::
-
- adduser --system \
- --home /usr/local/var/lib/couchdb \
- --no-create-home \
- --shell /bin/bash \
- --group --gecos \
- "CouchDB Administrator" couchdb
-
-On Mac OS X you can use the `Workgroup Manager`_ to create users.
-
-You must make sure that:
-
-* The user has a working POSIX shell
-* The user's home directory is `/usr/local/var/lib/couchdb`
-
-You can test this by:
-
-* Trying to log in as the `couchdb` user
-* Running `pwd` and checking the present working directory
-
-Change the ownership of the CouchDB directories by running::
-
- chown -R couchdb:couchdb /usr/local/etc/couchdb
- chown -R couchdb:couchdb /usr/local/var/lib/couchdb
- chown -R couchdb:couchdb /usr/local/var/log/couchdb
- chown -R couchdb:couchdb /usr/local/var/run/couchdb
-
-Change the permission of the CouchDB directories by running::
-
- chmod 0770 /usr/local/etc/couchdb
- chmod 0770 /usr/local/var/lib/couchdb
- chmod 0770 /usr/local/var/log/couchdb
- chmod 0770 /usr/local/var/run/couchdb
-
-.. _Workgroup Manager: http://www.apple.com/support/downloads/serveradmintools1047.html
-
-
-Running as a Daemon
--------------------
-
-SysV/BSD-style Systems
-~~~~~~~~~~~~~~~~~~~~~~
-
-You can use the `couchdb` init script to control the CouchDB daemon.
-
-On SysV-style systems, the init script will be installed into::
-
- /usr/local/etc/init.d
-
-On BSD-style systems, the init script will be installed into::
-
- /usr/local/etc/rc.d
-
-We use the `[init.d|rc.d]` notation to refer to both of these directories.
-
-You can control the CouchDB daemon by running::
-
- /usr/local/etc/[init.d|rc.d]/couchdb [start|stop|restart|status]
-
-If you wish to configure how the init script works, you can edit::
-
- /usr/local/etc/default/couchdb
-
-Comment out the `COUCHDB_USER` setting if you're running as a non-superuser.
-
-To start the daemon on boot, copy the init script to::
-
- /etc/[init.d|rc.d]
-
-You should then configure your system to run the init script automatically.
-
-You may be able to run::
-
- sudo update-rc.d couchdb defaults
-
-If this fails, consult your system documentation for more information.
-
-A `logrotate` configuration is installed into::
-
- /usr/local/etc/logrotate.d/couchdb
-
-Consult your `logrotate` documentation for more information.
-
-It is critical that the CouchDB logs are rotated so as not to fill your disk.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cdac7299/share/doc/src/install/windows.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/install/windows.rst b/share/doc/src/install/windows.rst
deleted file mode 100644
index b7b66af..0000000
--- a/share/doc/src/install/windows.rst
+++ /dev/null
@@ -1,275 +0,0 @@
-.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
-.. use this file except in compliance with the License. You may obtain a copy of
-.. the License at
-..
-.. http://www.apache.org/licenses/LICENSE-2.0
-..
-.. Unless required by applicable law or agreed to in writing, software
-.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-.. License for the specific language governing permissions and limitations under
-.. the License.
-
-
-.. _install/windows:
-
-=======================
-Installation on Windows
-=======================
-
-There are two ways to install CouchDB on Windows.
-
-Installation from binaries
-==========================
-
-This is the simplest way to go.
-
-#. Get `the latest Windows binaries`_ from `CouchDB web site`_.
- Old releases are available at `archive`_.
-
-#. Follow the installation wizard steps:
-
- - Next on "Welcome" screen
- - Accept the License agreement
- - Select the installation directory
- - Specify "Start Menu" group name
- - Approve that you'd like to install CouchDB as service and let it be
- started automatically after installation (probably, you'd like so)
- - Verify installation settings
- - Install CouchDB
-
-#. `Open up Futon`_ (if you hadn't selected autostart CouchDB after
- installation, you have to start it first manually)
-
-#. It's time to Relax!
-
-.. note::
- In some cases you might been asked to reboot Windows to complete
- installation process, because of using on different Microsoft Visual C++
- runtimes by CouchDB.
-
-.. note:: **Upgrading note**
-
- It's recommended to uninstall previous CouchDB version before upgrading,
- especially if the new one is built against different Erlang release.
- The reason is simple: there may be leftover libraries with alternative or
- incompatible versions from old Erlang release that may create conflicts,
- errors and weird crashes.
-
- In this case, make sure you backup of your `local.ini` config and CouchDB
- database/index files.
-
-.. _Open up Futon: http://localhost:5984/_utils
-.. _CouchDB web site: http://couchdb.org/
-.. _archive: http://archive.apache.org/dist/couchdb/binary/win/
-.. _the latest Windows binaries: http://couchdb.org/#download
-
-
-Installation from sources
-=========================
-
-If you're Windows geek, this section is for you!
-
-Troubleshooting
----------------
-
-* There is a `troubleshooting guide`_.
-* There is a `wiki`_ for general documentation.
-* And some `Windows-specific tips`_.
-* There are collection of `friendly mailing lists`_.
-
-Please work through these in order if you experience any problems.
-
-.. _troubleshooting guide: http://wiki.apache.org/couchdb/Troubleshooting
-.. _wiki: http://wiki.apache.org/couchdb
-.. _friendly mailing lists: http://couchdb.apache.org/community/lists.html
-.. _Windows-specific tips: http://wiki.apache.org/couchdb/Quirks_on_Windows
-
-Dependencies
-------------
-
-You should have the following installed:
-
-* `Erlang OTP (>=14B01, <R17) <http://erlang.org/>`_
-* `ICU (>=4.*) <http://icu-project.org/>`_
-* `OpenSSL (>0.9.8r) <http://www.openssl.org/>`_
-* `Mozilla SpiderMonkey (=1.8.5) <http://www.mozilla.org/js/spidermonkey/>`_
-* `Cygwin <http://www.cygwin.com/>`_
-* `Microsoft SDK 7.0 or 7.1 <http://www.microsoft.com/en-us/download/details.aspx?id=8279>`_
-* `libcurl (>=7.20) <http://curl.haxx.se/libcurl/>`_
-* `help2man <http://www.gnu.org/s/help2man/>`_
-* `Python (>=2.7) for docs <http://python.org/>`_
-* `Python Sphinx (>=1.1.3) <http://pypi.python.org/pypi/Sphinx>`_
-
-You will only need libcurl if you plan to run the JavaScript test suite. And
-help2man is only need if you plan on installing the CouchDB man pages.
-Python and Sphinx are only required for building the online documentation.
-
-General Notes
--------------
-
-* When installing Cygwin, be sure to select all the `development` tools.
-
-* When installing Erlang, you must build it from source.
-
-* The CouchDB build requires a number of the Erlang build scripts.
-
-* All dependent libraries should be built with the same version of
- Microsoft SDK.
-
-* Do not try to link against libraries built with, or included in,
- Cygwin or MingW. They are not compatible with the Erlang/OTP or CouchDB
- build scripts.
-
-* ICU version 4.6 and later will build cleanly using MSBuild.
-
-* Python and Sphinx are optional for building the online documentation.
- Use cygwin-provided Python and install Sphinx via easy_install or pip.
- Further information is here http://pypi.python.org/pypi/setuptools#id4
-
-Setting Up Cygwin
------------------
-
-Before starting any Cygwin terminals, run::
-
- set CYGWIN=nontsec
-
-To set up your environment, run::
-
- [VS_BIN]/vcvars32.bat
-
-Replace ``[VS_BIN]`` with the path to your Visual Studio `bin` directory.
-
-You must check that:
-
-* The ``which link`` command points to the Microsoft linker.
-
-* The ``which cl`` command points to the Microsoft compiler.
-
-* The ``which mc`` command points to the Microsoft message compiler.
-
-* The ``which mt`` command points to the Microsoft manifest tool.
-
-* The ``which nmake`` command points to the Microsoft make tool.
-
-If you do not do this, the build may fail due to Cygwin ones found in `/usr/bin`
-being used instead.
-
-Building Erlang
----------------
-
-You must include Win32 OpenSSL, built statically from source. Use
-exactly the same version as required by the Erlang/OTP build process.
-
-However, you can skip the GUI tools by running::
-
- echo "skipping gs" > lib/gs/SKIP
-
- echo "skipping ic" > lib/ic/SKIP
-
- echo "skipping jinterface" > lib/jinterface/SKIP
-
-Follow the rest of the Erlang instructions as described.
-
-After running::
-
- ./otp_build release -a
-
-You should run::
-
- ./release/win32/Install.exe -s
-
-This will set up the release/win32/bin directory correctly. The CouchDB
-installation scripts currently write their data directly into this
-location.
-
-To set up your environment for building CouchDB, run::
-
- eval `./otp_build env_win32`
-
-To set up the `ERL_TOP` environment variable, run::
-
- export ERL_TOP=[ERL_TOP]
-
-Replace ``[ERL_TOP]`` with the Erlang source directory name.
-
-Remember to use `/cygdrive/c/` instead of `c:/` as the directory prefix.
-
-To set up your path, run::
-
- export PATH=$ERL_TOP/release/win32/erts-5.8.5/bin:$PATH
-
-If everything was successful, you should be ready to build CouchDB.
-
-Relax.
-
-Building CouchDB
-----------------
-
-Note that `win32-curl` is only required if you wish to run the developer
-tests.
-
-The documentation step may be skipped using ``--disable-docs`` if you wish.
-
-Once you have satisfied the dependencies you should run::
-
- ./configure \
- --with-js-include=/cygdrive/c/path_to_spidermonkey_include \
- --with-js-lib=/cygdrive/c/path_to_spidermonkey_lib \
- --with-win32-icu-binaries=/cygdrive/c/path_to_icu_binaries_root \
- --with-erlang=$ERL_TOP/release/win32/usr/include \
- --with-win32-curl=/cygdrive/c/path/to/curl/root/directory \
- --with-openssl-bin-dir=/cygdrive/c/openssl/bin \
- --with-msvc-redist-dir=/cygdrive/c/dir/with/vcredist_platform_executable \
- --disable-init \
- --disable-launchd \
- --prefix=$ERL_TOP/release/win32
-
-This command could take a while to complete.
-
-If everything was successful you should see the following message::
-
- You have configured Apache CouchDB, time to relax.
-
-Relax.
-
-To install CouchDB you should run::
-
- make install
-
-If everything was successful you should see the following message::
-
- You have installed Apache CouchDB, time to relax.
-
-Relax.
-
-To build the .exe installer package, you should run::
-
- make dist
-
-Alternatively, you may run CouchDB directly from the build tree, but
-to avoid any contamination do not run `make dist` after this.
-
-First Run
----------
-
-You can start the CouchDB server by running::
-
- $ERL_TOP/release/win32/bin/couchdb.bat
-
-When CouchDB starts it should eventually display the following message::
-
- Apache CouchDB has started, time to relax.
-
-Relax.
-
-To check that everything has worked, point your web browser to::
-
- http://127.0.0.1:5984/_utils/index.html
-
-From here you should run the verification tests in Firefox.
-
-
-.. seealso::
-
- `Glazier: Automate building of CouchDB from source on Windows <https://github.com/dch/glazier>`_
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cdac7299/share/doc/src/intro/api.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro/api.rst b/share/doc/src/intro/api.rst
deleted file mode 100644
index d68f6e6..0000000
--- a/share/doc/src/intro/api.rst
+++ /dev/null
@@ -1,783 +0,0 @@
-.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
-.. use this file except in compliance with the License. You may obtain a copy of
-.. the License at
-..
-.. http://www.apache.org/licenses/LICENSE-2.0
-..
-.. Unless required by applicable law or agreed to in writing, software
-.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-.. License for the specific language governing permissions and limitations under
-.. the License.
-
-
-.. _intro/api:
-
-============
-The Core API
-============
-
-This document explores the CouchDB in minute detail. It shows all the
-nitty-gritty and clever bits. We show you best practices and guide you around
-common pitfalls.
-
-We start out by revisiting the basic operations we ran in the previous document
-:ref:`intro/tour`, looking behind the scenes. We also show what Futon needs to
-do behind its user interface to give us the nice features we saw earlier.
-
-This document is both an introduction to the core CouchDB API as well as a
-reference. If you can't remember how to run a particular request or why some
-parameters are needed, you can always come back here and look things up (we
-are probably the heaviest users of this document).
-
-While explaining the API bits and pieces, we sometimes need to take a larger
-detour to explain the reasoning for a particular request. This is a good
-opportunity for us to tell you why CouchDB works the way it does.
-
-The API can be subdivided into the following sections. We'll explore them
-individually:
-
-.. contents::
- :depth: 1
- :local:
-
-
-Server
-======
-
-This one is basic and simple. It can serve as a sanity check to see if
-CouchDB is running at all. It can also act as a safety guard for libraries
-that require a certain version of CouchDB. We're using the `curl`_ utility
-again::
-
- curl http://127.0.0.1:5984/
-
-CouchDB replies, all excited to get going:
-
-.. code-block:: javascript
-
- {
- "couchdb": "Welcome",
- "uuid": "85fb71bf700c17267fef77535820e371",
- "vendor": {
- "name": "The Apache Software Foundation",
- "version": "1.5.0"
- },
- "version": "1.5.0"
- }
-
-You get back a JSON string, that, if parsed into a native object or data
-structure of your programming language, gives you access to the welcome
-string and version information.
-
-This is not terribly useful, but it illustrates nicely the way CouchDB
-behaves. You send an HTTP request and you receive a JSON string in the HTTP
-response as a result.
-
-.. _curl: http://curl.haxx.se/
-
-
-Databases
-=========
-
-Now let's do something a little more useful: *create databases*.
-For the strict, CouchDB is a *database management system* (DMS). That means it
-can hold multiple databases. A database is a bucket that holds "related data".
-We'll explore later what that means exactly. In practice, the terminology is
-overlapping -- often people refer to a DMS as "a database" and also a database
-within the DMS as "a database." We might follow that slight oddity, so don't
-get confused by it. In general, it should be clear from the context if we are
-talking about the whole of CouchDB or a single database within CouchDB.
-
-Now let's make one! We want to store our favorite music albums,
-and we creatively give our database the name albums. Note that we're now
-using the ``-X`` option again to tell curl to send a :method:`PUT` request
-instead of the default :method:`GET` request::
-
- curl -X PUT http://127.0.0.1:5984/albums
-
-CouchDB replies:
-
-.. code-block:: javascript
-
- {"ok":true}
-
-That's it. You created a database and CouchDB told you that all went well.
-What happens if you try to create a database that already exists? Let's try
-to create that database again::
-
- curl -X PUT http://127.0.0.1:5984/albums
-
-CouchDB replies:
-
-.. code-block:: javascript
-
- {"error":"file_exists","reason":"The database could not be created, the file already exists."}
-
-We get back an error. This is pretty convenient. We also learn a little bit
-about how CouchDB works. CouchDB stores each database in a single file.
-Very simple.
-
-Let's create another database, this time with curl's ``-v`` (for "verbose")
-option. The verbose option tells curl to show us not only the essentials --
-the HTTP response body -- but all the underlying request and response details::
-
- curl -vX PUT http://127.0.0.1:5984/albums-backup
-
-curl elaborates::
-
- * About to connect() to 127.0.0.1 port 5984 (#0)
- * Trying 127.0.0.1... connected
- * Connected to 127.0.0.1 (127.0.0.1) port 5984 (#0)
- > PUT /albums-backup HTTP/1.1
- > User-Agent: curl/7.16.3 (powerpc-apple-darwin9.0) libcurl/7.16.3 OpenSSL/0.9.7l zlib/1.2.3
- > Host: 127.0.0.1:5984
- > Accept: */*
- >
- < HTTP/1.1 201 Created
- < Server: CouchDB (Erlang/OTP)
- < Date: Sun, 05 Jul 2009 22:48:28 GMT
- < Content-Type: text/plain;charset=utf-8
- < Content-Length: 12
- < Cache-Control: must-revalidate
- <
- {"ok":true}
- * Connection #0 to host 127.0.0.1 left intact
- * Closing connection #0
-
-What a mouthful. Let's step through this line by line to understand what's
-going on and find out what's important. Once you've seen this output a few
-times, you'll be able to spot the important bits more easily.
-
-::
-
- * About to connect() to 127.0.0.1 port 5984 (#0)
-
-This is curl telling us that it is going to establish a TCP connection to the
-CouchDB server we specified in our request URI. Not at all important,
-except when debugging networking issues.
-
-::
-
- * Trying 127.0.0.1... connected
- * Connected to 127.0.0.1 (127.0.0.1) port 5984 (#0)
-
-curl tells us it successfully connected to CouchDB. Again,
-not important if you aren't trying to find problems with your network.
-
-The following lines are prefixed with ``>`` and ``<`` characters.
-The ``>`` means the line was sent to CouchDB verbatim (without the actual
-``>``). The ``<`` means the line was sent back to curl by CouchDB.
-
-::
-
- > PUT /albums-backup HTTP/1.1
-
-This initiates an HTTP request. Its *method* is :method:`PUT`, the *URI* is
-``/albums-backup``, and the HTTP version is ``HTTP/1.1``. There is also
-``HTTP/1.0``, which is simpler in some cases, but for all practical reasons
-you should be using ``HTTP/1.1``.
-
-Next, we see a number of *request headers*. These are used to provide
-additional details about the request to CouchDB.
-
-::
-
- > User-Agent: curl/7.16.3 (powerpc-apple-darwin9.0) libcurl/7.16.3 OpenSSL/0.9.7l zlib/1.2.3
-
-The User-Agent header tells CouchDB which piece of client software is doing
-the HTTP request. We don't learn anything new: it's curl. This header is
-often useful in web development when there are known errors in client
-implementations that a server might want to prepare the response for.
-It also helps to determine which platform a user is on. This information
-can be used for technical and statistical reasons. For CouchDB, the
-:header:`User-Agent` header is irrelevant.
-
-::
-
- > Host: 127.0.0.1:5984
-
-The :header:`Host` header is required by ``HTTP 1.1``. It tells the server
-the hostname that came with the request.
-
-::
-
- > Accept: */*
-
-The :header:`Accept` header tells CouchDB that curl accepts any media type.
-We'll look into why this is useful a little later.
-
-::
-
- >
-
-An empty line denotes that the request headers are now finished and the rest
-of the request contains data we're sending to the server. In this case,
-we're not sending any data, so the rest of the curl output is dedicated to
-the HTTP response.
-
-::
-
- < HTTP/1.1 201 Created
-
-The first line of CouchDB's HTTP response includes the HTTP version
-information (again, to acknowledge that the requested version could be
-processed), an HTTP *status code*, and a *status code message*.
-Different requests trigger different response codes. There's a whole range of
-them telling the client (curl in our case) what effect the request had on the
-server. Or, if an error occurred, what kind of error. :rfc:`2616` (the HTTP 1.1
-specification) defines clear behavior for response codes. CouchDB fully
-follows the RFC.
-
-The :statuscode:`201` status code tells the client that the resource
-the request was made against was successfully created. No surprise here,
-but if you remember that we got an error message when we tried to create this
-database twice, you now know that this response could include a different
-response code. Acting upon responses based on response codes is a common
-practice. For example, all response codes of :statuscode:`400` or larger
-tell you that some error occurred. If you want to shortcut your logic and
-immediately deal with the error, you could just check a >= ``400`` response
-code.
-
-::
-
- < Server: CouchDB (Erlang/OTP)
-
-The :header:`Server` header is good for diagnostics. It tells us which
-CouchDB version and which underlying Erlang version we are talking to.
-In general, you can ignore this header, but it is good to know it's there if
-you need it.
-
-::
-
- < Date: Sun, 05 Jul 2009 22:48:28 GMT
-
-The :header:`Date` header tells you the time of the server. Since client
-and server time are not necessarily synchronized, this header is purely
-informational. You shouldn't build any critical application logic on top
-of this!
-
-::
-
- < Content-Type: text/plain;charset=utf-8
-
-The :header:`Content-Type` header tells you which MIME type
-the HTTP response body is and its encoding. We already know CouchDB returns
-JSON strings. The appropriate :header:`Content-Type` header is
-:mimetype:`application/json`. Why do we see :mimetype:`text/plain`?
-This is where pragmatism wins over purity. Sending an
-:mimetype:`application/json` :header:`Content-Type` header will make
-a browser offer you the returned JSON for download instead of
-just displaying it. Since it is extremely useful to be able to test CouchDB
-from a browser, CouchDB sends a :mimetype:`text/plain` content type, so all
-browsers will display the JSON as text.
-
-.. note::
-
- There are some extensions that make your browser JSON-aware,
- but they are not installed by default. For more information, look at
- the popular `JSONView`_ extension, available for both Firefox and Chrome.
-
- .. _JSONView: http://jsonview.com/
-
-Do you remember the :header:`Accept` request header and how it is set to
-``*/*`` to express interest in any MIME type? If you send ``Accept:
-application/json`` in your request, CouchDB knows that you can deal with a pure
-JSON response with the proper :header:`Content-Type` header and will
-use it instead of :mimetype:`text/plain`.
-
-::
-
- < Content-Length: 12
-
-The :header:`Content-Length` header simply tells us how many bytes
-the response body has.
-
-::
-
- < Cache-Control: must-revalidate
-
-This :header:`Cache-Control` header tells you, or any proxy server between
-CouchDB and you, not to cache this response.
-
-::
-
- <
-
-This empty line tells us we're done with the response headers and what
-follows now is the response body.
-
-.. code-block:: javascript
-
- {"ok":true}
-
-We've seen this before.
-
-::
-
- * Connection #0 to host 127.0.0.1 left intact
- * Closing connection #0
-
-The last two lines are curl telling us that it kept the TCP connection it
-opened in the beginning open for a moment, but then closed it after it
-received the entire response.
-
-Throughout the documents, we'll show more requests with the ``-v`` option,
-but we'll omit some of the headers we've seen here and include only those
-that are important for the particular request.
-
-Creating databases is all fine, but how do we get rid of one? Easy -- just
-change the HTTP method::
-
- > curl -vX DELETE http://127.0.0.1:5984/albums-backup
-
-This deletes a CouchDB database. The request will remove the file that the
-database contents are stored in. There is no *"Are you sure?"* safety net or
-any *"Empty the trash"* magic you've got to do to delete a database. Use this
-command with care. Your data will be deleted without a chance to bring it
-back easily if you don't have a backup copy.
-
-This section went knee-deep into HTTP and set the stage for discussing the
-rest of the core CouchDB API. Next stop: documents.
-
-
-Documents
-=========
-
-.. _GUID: http://en.wikipedia.org/wiki/Globally_unique_identifier
-.. _UUID: http://en.wikipedia.org/wiki/Universally_unique_identifier
-
-Documents are CouchDB's central data structure. The idea behind a document
-is, unsurprisingly, that of a real-world document -- a sheet of paper such as
-an invoice, a recipe, or a business card. We already learned that CouchDB uses
-the JSON format to store documents. Let's see how this storing works at the
-lowest level.
-
-Each document in CouchDB has an *ID*. This ID is unique per database. You are
-free to choose any string to be the ID, but for best results we recommend a
-`UUID`_ (or `GUID`_), i.e., a Universally (or Globally) Unique IDentifier.
-UUIDs are random numbers that have such a low collision probability that
-everybody can make thousands of UUIDs a minute for millions of years without
-ever creating a duplicate. This is a great way to ensure two independent people
-cannot create two different documents with the same ID. Why should you care
-what somebody else is doing? For one, that somebody else could be you at a
-later time or on a different computer; secondly, CouchDB replication lets you
-share documents with others and using UUIDs ensures that it all works.
-But more on that later; let's make some documents::
-
- curl -X PUT http://127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af -d '{"title":"There is Nothing Left to Lose","artist":"Foo Fighters"}'
-
-CouchDB replies:
-
-.. code-block:: javascript
-
- {"ok":true,"id":"6e1295ed6c29495e54cc05947f18c8af","rev":"1-2902191555"}
-
-The curl command appears complex, but let's break it down.
-First, ``-X PUT`` tells curl to make a :method:`PUT` request.
-It is followed by the URL that specifies your CouchDB IP address and port.
-The resource part of the URL ``/albums/6e1295ed6c29495e54cc05947f18c8af``
-specifies the location of a document inside our albums database.
-The wild collection of numbers and characters is a UUID. This UUID is your
-document's ID. Finally, the ``-d`` flag tells curl to use the following
-string as the body for the :method:`PUT` request. The string is a simple JSON
-structure including ``title`` and ``artist`` attributes with their respective
-values.
-
-.. note::
-
- If you don't have a UUID handy, you can ask CouchDB to give you one (in fact,
- that is what we did just now without showing you). Simply send a
- :get:`/_uuids` request::
-
- curl -X GET http://127.0.0.1:5984/_uuids
-
- CouchDB replies:
-
- .. code-block:: javascript
-
- {"uuids":["6e1295ed6c29495e54cc05947f18c8af"]}
-
- Voilà, a UUID. If you need more than one, you can pass in the ``?count=10`` HTTP
- parameter to request 10 UUIDs, or really, any number you need.
-
-To double-check that CouchDB isn't lying about having saved your document (it
-usually doesn't), try to retrieve it by sending a GET request::
-
- curl -X GET http://127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af
-
-We hope you see a pattern here. Everything in CouchDB has an address, a URI,
-and you use the different HTTP methods to operate on these URIs.
-
-CouchDB replies:
-
-.. code-block:: javascript
-
- {"_id":"6e1295ed6c29495e54cc05947f18c8af","_rev":"1-2902191555","title":"There is Nothing Left to Lose","artist":"Foo Fighters"}
-
-This looks a lot like the document you asked CouchDB to save, which is good.
-But you should notice that CouchDB added two fields to your JSON structure.
-The first is ``_id``, which holds the UUID we asked CouchDB to save our document
-under. We always know the ID of a document if it is included, which is very
-convenient.
-
-The second field is ``_rev``. It stands for *revision*.
-
-Revisions
----------
-
-If you want to change a document in CouchDB, you don't tell it to go and find
-a field in a specific document and insert a new value. Instead, you load
-the full document out of CouchDB, make your changes in the JSON structure
-(or object, when you are doing actual programming), and save the entire new
-revision (or version) of that document back into CouchDB. Each revision is
-identified by a new ``_rev`` value.
-
-If you want to update or delete a document, CouchDB expects you to include
-the ``_rev`` field of the revision you wish to change. When CouchDB accepts
-the change, it will generate a new revision number. This mechanism ensures that,
-in case somebody else made a change without you knowing before you got to
-request the document update, CouchDB will not accept your update because you
-are likely to overwrite data you didn't know existed. Or simplified: whoever
-saves a change to a document first, wins. Let's see what happens if we don't
-provide a ``_rev`` field (which is equivalent to providing a outdated value)::
-
- curl -X PUT http://127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af \
- -d '{"title":"There is Nothing Left to Lose","artist":"Foo Fighters","year":"1997"}'
-
-CouchDB replies:
-
-.. code-block:: javascript
-
- {"error":"conflict","reason":"Document update conflict."}
-
-If you see this, add the latest revision number of your document to the JSON
-structure::
-
- curl -X PUT http://127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af \
- -d '{"_rev":"1-2902191555","title":"There is Nothing Left to Lose","artist":"Foo Fighters","year":"1997"}'
-
-Now you see why it was handy that CouchDB returned that ``_rev`` when we made
-the initial request. CouchDB replies:
-
-.. code-block:: javascript
-
- {"ok":true,"id":"6e1295ed6c29495e54cc05947f18c8af","rev":"2-8aff9ee9d06671fa89c99d20a4b3ae"}
-
-CouchDB accepted your write and also generated a new revision number.
-The revision number is the *MD5 hash* of the transport representation of a
-document with an ``N-`` prefix denoting the number of times a document got
-updated. This is useful for replication. See :ref:`replication/conflicts` for
-more information.
-
-There are multiple reasons why CouchDB uses this revision system,
-which is also called Multi-Version Concurrency Control (`MVCC`_). They all work
-hand-in-hand, and this is a good opportunity to explain some of them.
-
-.. _MVCC: http://en.wikipedia.org/wiki/Multiversion_concurrency_control
-
-One of the aspects of the HTTP protocol that CouchDB uses is that it is
-stateless. What does that mean? When talking to CouchDB you need to make
-requests. Making a request includes opening a network connection to CouchDB,
-exchanging bytes, and closing the connection. This is done every time you
-make a request. Other protocols allow you to open a connection, exchange bytes,
-keep the connection open, exchange more bytes later -- maybe depending on the
-bytes you exchanged at the beginning -- and eventually close the connection.
-Holding a connection open for later use requires the server to do extra work.
-One common pattern is that for the lifetime of a connection, the client has
-a consistent and static view of the data on the server. Managing huge amounts
-of parallel connections is a significant amount of work. HTTP connections are
-usually short-lived, and making the same guarantees is a lot easier.
-As a result, CouchDB can handle many more concurrent connections.
-
-Another reason CouchDB uses MVCC is that this model is simpler conceptually
-and, as a consequence, easier to program. CouchDB uses less code to make this
-work, and less code is always good because the ratio of defects per lines of
-code is static.
-
-The revision system also has positive effects on replication and storage
-mechanisms, but we'll explore these later in the documents.
-
-.. warning::
-
- The terms *version* and *revision* might sound familiar (if you are
- programming without version control, stop reading this guide right now and start
- learning one of the popular systems). Using new versions for document changes
- works a lot like version control, but there's an important difference:
- **CouchDB does not guarantee that older versions are kept around**.
-
-
-Documents in Detail
--------------------
-
-Now let's have a closer look at our document creation requests with the curl
-``-v`` flag that was helpful when we explored the database API earlier.
-This is also a good opportunity to create more documents that we can use in
-later examples.
-
-We'll add some more of our favorite music albums. Get a fresh UUID from the
-``/_uuids`` resource. If you don't remember how that works, you can look it up
-a few pages back.
-
-::
-
- curl -vX PUT http://127.0.0.1:5984/albums/70b50bfa0a4b3aed1f8aff9e92dc16a0 \
- -d '{"title":"Blackened Sky","artist":"Biffy Clyro","year":2002}'
-
-.. note::
-
- By the way, if you happen to know more information about your favorite
- albums, don't hesitate to add more properties. And don't worry about not
- knowing all the information for all the albums. CouchDB's schema-less
- documents can contain whatever you know. After all, you should relax and not
- worry about data.
-
-Now with the ``-v`` option, CouchDB's reply (with only the important bits shown)
-looks like this::
-
- > PUT /albums/70b50bfa0a4b3aed1f8aff9e92dc16a0 HTTP/1.1
- >
- < HTTP/1.1 201 Created
- < Location: http://127.0.0.1:5984/albums/70b50bfa0a4b3aed1f8aff9e92dc16a0
- < ETag: "1-e89c99d29d06671fa0a4b3ae8aff9e"
- <
- {"ok":true,"id":"70b50bfa0a4b3aed1f8aff9e92dc16a0","rev":"1-e89c99d29d06671fa0a4b3ae8aff9e"}
-
-We're getting back the :statuscode:`201` HTTP status code in the response
-headers, as we saw earlier when we created a database. The :header:`Location`
-header gives us a full URL to our newly created document. And there's a new
-header. An :header:`ETag` in HTTP-speak identifies a specific version of a
-resource. In this case, it identifies a specific version (the first one) of our
-new document. Sound familiar? Yes, conceptually, an :header:`ETag` is the same
-as a CouchDB document revision number, and it shouldn't come as a surprise that
-CouchDB uses revision numbers for ETags. ETags are useful for caching
-infrastructures.
-
-
-Attachments
------------
-
-CouchDB documents can have attachments just like an email message can have
-attachments. An attachment is identified by a name and includes its MIME type
-(or :header:`Content-Type`) and the number of bytes the attachment
-contains. Attachments can be any data. It is easiest to think about attachments
-as files attached to a document. These files can be text, images, Word
-documents, music, or movie files. Let's make one.
-
-Attachments get their own URL where you can upload data. Say we want to add
-the album artwork to the ``6e1295ed6c29495e54cc05947f18c8af`` document
-(*"There is Nothing Left to Lose"*), and let's also say the artwork is in a file
-`artwork.jpg` in the current directory::
-
- curl -vX PUT http://127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af/artwork.jpg?rev=2-2739352689 \
- --data-binary @artwork.jpg -H "Content-Type:image/jpg"
-
-.. note::
-
- The ``--data-binary`` ``@`` option tells curl to read a file's contents into
- the HTTP request body. We're using the ``-H`` option to tell CouchDB that
- we're uploading a JPEG file. CouchDB will keep this information around and
- will send the appropriate header when requesting this attachment; in case of
- an image like this, a browser will render the image instead of offering you
- the data for download. This will come in handy later. Note that you need
- to provide the current revision number of the document you're attaching
- the artwork to, just as if you would update the document. Because, after all,
- attaching some data is changing the document.
-
-You should now see your artwork image if you point your browser to
-http://127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af/artwork.jpg
-
-If you request the document again, you'll see a new member::
-
- curl http://127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af
-
-CouchDB replies:
-
-.. code-block:: javascript
-
- {
- "_id": "6e1295ed6c29495e54cc05947f18c8af",
- "_rev": "3-131533518",
- "title": "There is Nothing Left to Lose",
- "artist": "Foo Fighters",
- "year": "1997",
- "_attachments": {
- "artwork.jpg": {
- "stub": true,
- "content_type": "image/jpg",
- "length": 52450
- }
- }
- }
-
-``_attachments`` is a list of keys and values where the values are JSON objects
-containing the attachment metadata. ``stub=true`` tells us that this entry is
-just the metadata. If we use the ``?attachments=true`` HTTP option when
-requesting this document, we'd get a `Base64`_ encoded string containing the
-attachment data.
-
-.. _Base64: http://en.wikipedia.org/wiki/Base64
-
-We'll have a look at more document request options later as we explore more
-features of CouchDB, such as replication, which is the next topic.
-
-
-Replication
-===========
-
-CouchDB replication is a mechanism to synchronize databases. Much like `rsync`_
-synchronizes two directories locally or over a network, replication synchronizes
-two databases locally or remotely.
-
-.. _rsync: http://en.wikipedia.org/wiki/Rsync
-
-In a simple :method:`POST` request, you tell CouchDB the *source* and the
-*target* of a replication and CouchDB will figure out which documents and new
-document revisions are on *source* that are not yet on *target*, and will
-proceed to move the missing documents and revisions over.
-
-We'll take an in-depth look at replication in the document :ref:`replication/intro`;
-in this document, we'll just show you how to use it.
-
-First, we'll create a target database. Note that CouchDB won't automatically
-create a target database for you, and will return a replication failure if
-the target doesn't exist (likewise for the source, but that mistake isn't as
-easy to make)::
-
- curl -X PUT http://127.0.0.1:5984/albums-replica
-
-Now we can use the database `albums-replica` as a replication target::
-
- curl -vX POST http://127.0.0.1:5984/_replicate \
- -d '{"source":"albums","target":"albums-replica"}' \
- -H "Content-Type: application/json"
-
-.. note::
-
- CouchDB supports the option ``"create_target":true`` placed in the JSON POSTed
- to the :ref:`_replicate <api/server/replicate>` URL. It implicitly creates
- the target database if it doesn't exist.
-
-CouchDB replies (this time we formatted the output so you can read it more
-easily):
-
-.. code-block:: javascript
-
- {
- "history": [
- {
- "start_last_seq": 0,
- "missing_found": 2,
- "docs_read": 2,
- "end_last_seq": 5,
- "missing_checked": 2,
- "docs_written": 2,
- "doc_write_failures": 0,
- "end_time": "Sat, 11 Jul 2009 17:36:21 GMT",
- "start_time": "Sat, 11 Jul 2009 17:36:20 GMT"
- }
- ],
- "source_last_seq": 5,
- "session_id": "924e75e914392343de89c99d29d06671",
- "ok": true
- }
-
-CouchDB maintains a *session history* of replications. The response for a
-replication request contains the history entry for this *replication session*.
-It is also worth noting that the request for replication will stay open until
-replication closes. If you have a lot of documents, it'll take a while until
-they are all replicated and you won't get back the replication response
-until all documents are replicated. It is important to note that
-replication replicates the database only as it was at the point in time
-when replication was started. So, any additions, modifications,
-or deletions subsequent to the start of replication will not be replicated.
-
-We'll punt on the details again -- the ``"ok": true`` at the end tells us all
-went well. If you now have a look at the albums-replica database,
-you should see all the documents that you created in the albums database.
-Neat, eh?
-
-What you just did is called local replication in CouchDB terms. You created a
-local copy of a database. This is useful for backups or to keep snapshots of
-a specific state of your data around for later. You might want to do this
-if you are developing your applications but want to be able to roll back to
-a stable version of your code and data.
-
-There are more types of replication useful in other situations. The source
-and target members of our replication request are actually links (like in
-HTML) and so far we've seen links relative to the server we're working on
-(hence local). You can also specify a remote database as the target::
-
- curl -vX POST http://127.0.0.1:5984/_replicate \
- -d '{"source":"albums","target":"http://example.org:5984/albums-replica"}' \
- -H "Content-Type:application/json"
-
-Using a *local source* and a *remote target* database is called *push
-replication*. We're pushing changes to a remote server.
-
-.. note::
-
- Since we don't have a second CouchDB server around just yet, we'll just use
- the absolute address of our single server, but you should be able to infer
- from this that you can put any remote server in there.
-
-This is great for sharing local changes with remote servers or buddies next
-door.
-
-You can also use a *remote source* and a *local target* to do a *pull
-replication*. This is great for getting the latest changes from a server that
-is used by others::
-
- curl -vX POST http://127.0.0.1:5984/_replicate \
- -d '{"source":"http://example.org:5984/albums-replica","target":"albums"}' \
- -H "Content-Type:application/json"
-
-Finally, you can run remote replication, which is mostly useful for management
-operations::
-
- curl -vX POST http://127.0.0.1:5984/_replicate \
- -d '{"source":"http://example.org:5984/albums","target":"http://example.org:5984/albums-replica"}' \
- -H"Content-Type: application/json"
-
-.. note::
-
- **CouchDB and REST**
-
- CouchDB prides itself on having a `RESTful`_ API, but these replication
- requests don't look very RESTy to the trained eye. What's up with that?
- While CouchDB's core database, document, and attachment API are RESTful,
- not all of CouchDB's API is. The replication API is one example. There are
- more, as we'll see later in the documents.
-
- Why are there RESTful and non-RESTful APIs mixed up here? Have the developers
- been too lazy to go REST all the way? Remember, REST is an architectural
- style that lends itself to certain architectures (such as the CouchDB
- document API). But it is not a one-size-fits-all. Triggering an event like
- replication does not make a whole lot of sense in the REST world. It is more
- like a traditional remote procedure call. And there is nothing wrong with
- this.
-
- We very much believe in the "use the right tool for the job" philosophy,
- and REST does not fit every job. For support, we refer to Leonard Richardson
- and Sam Ruby who wrote `RESTful Web Services`_ (O'Reilly), as they share our
- view.
-
- .. _RESTful: http://en.wikipedia.org/wiki/Representational_state_transfer
- .. _RESTful Web Services: http://oreilly.com/catalog/9780596529260
-
-
-Wrapping Up
-===========
-
-This is still not the full CouchDB API, but we discussed the essentials in
-great detail. We're going to fill in the blanks as we go. For now, we believe
-you're ready to start building CouchDB applications.
-
-.. seealso::
-
- :ref:`Complete HTTP API Reference <api>`:
-
- - :ref:`Server API Reference <api/server>`
- - :ref:`Database API Reference <api/database>`
- - :ref:`Document API Reference <api/document>`
- - :ref:`Replication API <api/server/replicate>`
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cdac7299/share/doc/src/intro/consistency.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro/consistency.rst b/share/doc/src/intro/consistency.rst
deleted file mode 100644
index c104ded..0000000
--- a/share/doc/src/intro/consistency.rst
+++ /dev/null
@@ -1,465 +0,0 @@
-.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
-.. use this file except in compliance with the License. You may obtain a copy of
-.. the License at
-..
-.. http://www.apache.org/licenses/LICENSE-2.0
-..
-.. Unless required by applicable law or agreed to in writing, software
-.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-.. License for the specific language governing permissions and limitations under
-.. the License.
-
-
-.. _intro/consistency:
-
-====================
-Eventual Consistency
-====================
-
-In the previous document :ref:`intro/why`, we saw that CouchDB's flexibility allows us to
-evolve our data as our applications grow and change. In this topic,
-we'll explore how working "with the grain" of CouchDB promotes simplicity in
-our applications and helps us naturally build scalable, distributed systems.
-
-
-Working with the Grain
-======================
-
-A *distributed system* is a system that operates robustly over a wide network.
-A particular feature of network computing is that network links can
-potentially disappear, and there are plenty of strategies for managing this
-type of network segmentation. CouchDB differs from others by accepting
-eventual consistency, as opposed to putting absolute consistency ahead of raw
-availability, like `RDBMS`_ or `Paxos`_. What these systems have in common is
-an awareness that data acts differently when many people are accessing it
-simultaneously. Their approaches differ when it comes to which aspects of
-*consistency*, *availability*, or *partition* tolerance they prioritize.
-
-Engineering distributed systems is tricky. Many of the caveats and "gotchas"
-you will face over time aren't immediately obvious. We don't have all the
-solutions, and CouchDB isn't a panacea, but when you work with CouchDB's
-grain rather than against it, the path of least resistance leads you to
-naturally scalable applications.
-
-Of course, building a distributed system is only the beginning. A website
-with a database that is available only half the time is next to worthless.
-Unfortunately, the traditional relational database approach to consistency
-makes it very easy for application programmers to rely on global state,
-global clocks, and other high availability no-nos, without even realizing
-that they're doing so. Before examining how CouchDB promotes scalability,
-we'll look at the constraints faced by a distributed system. After we've seen
-the problems that arise when parts of your application can't rely on being
-in constant contact with each other, we'll see that CouchDB provides an
-intuitive and useful way for modeling applications around high availability.
-
-.. _RDBMS: http://en.wikipedia.org/wiki/Relational_database_management_system
-.. _Paxos: http://en.wikipedia.org/wiki/Paxos_%28computer_science%29
-
-
-.. _cap:
-
-The CAP Theorem
-===============
-
-The CAP theorem describes a few different strategies for distributing
-application logic across networks. CouchDB's solution uses replication to
-propagate application changes across participating nodes. This is a
-fundamentally different approach from consensus algorithms and relational
-databases, which operate at different intersections of consistency,
-availability, and partition tolerance.
-
-The CAP theorem, shown in :ref:`intro/consistency-01`,
-identifies three distinct concerns:
-
-- **Consistency**:
- All database clients see the same data, even with concurrent updates.
-- **Availability**:
- All database clients are able to access some version of the data.
-- **Partition tolerance**:
- The database can be split over multiple servers.
-
-Pick two.
-
-.. _intro/consistency-01:
-
-.. figure:: ../../images/intro-consistency-01.png
- :align: center
- :alt: The CAP theorem
-
- Figure 1. The CAP theorem
-
-When a system grows large enough that a single database node is unable to
-handle the load placed on it, a sensible solution is to add more servers.
-When we add nodes, we have to start thinking about how to partition data
-between them. Do we have a few databases that share exactly the same data?
-Do we put different sets of data on different database servers?
-Do we let only certain database servers write data and let others handle
-the reads?
-
-Regardless of which approach we take, the one problem we'll keep bumping into
-is that of keeping all these database servers in sync. If you write some
-information to one node, how are you going to make sure that a read request
-to another database server reflects this newest information? These events
-might be milliseconds apart. Even with a modest collection of database
-servers, this problem can become extremely complex.
-
-When it's absolutely critical that all clients see a consistent view of the
-database, the users of one node will have to wait for any other nodes to come
-into agreement before being able to read or write to the database.
-In this instance, we see that availability takes a backseat to consistency.
-However, there are situations where availability trumps consistency:
-
- Each node in a system should be able to make decisions purely based on
- local state. If you need to do something under high load with failures
- occurring and you need to reach agreement, you're lost. If you're
- concerned about scalability, any algorithm that forces you to run
- agreement will eventually become your bottleneck. Take that as a given.
-
- -- Werner Vogels, Amazon CTO and Vice President
-
-If availability is a priority, we can let clients write data to one node of
-the database without waiting for other nodes to come into agreement.
-If the database knows how to take care of reconciling these operations between
-nodes, we achieve a sort of "eventual consistency" in exchange for high
-availability. This is a surprisingly applicable trade-off for many applications.
-
-Unlike traditional relational databases, where each action performed is
-necessarily subject to database-wide consistency checks,
-CouchDB makes it really simple to build applications that sacrifice immediate
-consistency for the huge performance improvements that come with simple
-distribution.
-
-
-Local Consistency
-=================
-
-Before we attempt to understand how CouchDB operates in a cluster,
-it's important that we understand the inner workings of a single CouchDB node.
-The CouchDB API is designed to provide a convenient but thin wrapper around
-the database core. By taking a closer look at the structure of the database
-core, we'll have a better understanding of the API that surrounds it.
-
-
-The Key to Your Data
---------------------
-
-At the heart of CouchDB is a powerful *B-tree* storage engine.
-A B-tree is a sorted data structure that allows for searches, insertions,
-and deletions in logarithmic time. As :ref:`intro/consistency-02`
-illustrates, CouchDB uses this B-tree storage engine for all internal data,
-documents, and views. If we understand one, we will understand them all.
-
-
-.. _intro/consistency-02:
-
-.. figure:: ../../images/intro-consistency-02.png
- :align: center
- :alt: Anatomy of a view request
-
- Figure 2. Anatomy of a view request
-
-
-CouchDB uses MapReduce to compute the results of a view. MapReduce makes use
-of two functions, "map" and "reduce", which are applied to each document in
-isolation. Being able to isolate these operations means that view computation
-lends itself to parallel and incremental computation. More important,
-because these functions produce key/value pairs, CouchDB is able to insert
-them into the B-tree storage engine, sorted by key. Lookups by key,
-or key range, are extremely efficient operations with a B-tree,
-described in `big O` notation as ``O(log N)`` and ``O(log N + K)``,
-respectively.
-
-In CouchDB, we access documents and view results by key or key range.
-This is a direct mapping to the underlying operations performed on CouchDB's
-B-tree storage engine. Along with document inserts and updates,
-this direct mapping is the reason we describe CouchDB's API as being a thin
-wrapper around the database core.
-
-Being able to access results by key alone is a very important restriction
-because it allows us to make huge performance gains. As well as the massive
-speed improvements, we can partition our data over multiple nodes,
-without affecting our ability to query each node in isolation.
-`BigTable`_, `Hadoop`_, `SimpleDB`_, and `memcached`_ restrict object lookups
-by key for exactly these reasons.
-
-.. _BigTable: http://en.wikipedia.org/wiki/BigTable
-.. _Hadoop: http://hadoop.apache.org
-.. _SimpleDB: http://aws.amazon.com/simpledb/
-.. _memcached: http://memcached.org
-
-
-No Locking
-----------
-
-A table in a relational database is a single data structure. If you want to
-modify a table -- say, update a row -- the database system must ensure
-that nobody else is trying to update that row and that nobody can read from
-that row while it is being updated. The common way to handle this uses what's
-known as a lock. If multiple clients want to access a table, the first client
-gets the lock, making everybody else wait. When the first client's request is
-processed, the next client is given access while everybody else waits,
-and so on. This serial execution of requests, even when they arrived in
-parallel, wastes a significant amount of your server's processing power.
-Under high load, a relational database can spend more time figuring out who
-is allowed to do what, and in which order, than it does doing any actual work.
-
-.. note::
- Modern relational databases avoid locks by implementing MVCC under
- the hood, but hide it from the end user, requiring them to coordinate
- concurrent changes of single rows or fields.
-
-Instead of locks, CouchDB uses `Multi-Version Concurrency Control` (MVCC) to
-manage concurrent access to the database. :ref:`intro/consistency-03`
-illustrates the differences between MVCC and traditional locking mechanisms.
-MVCC means that CouchDB can run at full speed, all the time,
-even under high load. Requests are run in parallel, making excellent use of
-every last drop of processing power your server has to offer.
-
-
-.. _intro/consistency-03:
-
-.. figure:: ../../images/intro-consistency-03.png
- :align: center
- :alt: MVCC means no locking
-
- Figure 3. MVCC means no locking
-
-
-Documents in CouchDB are versioned, much like they would be in a regular
-version control system such as `Subversion`_. If you want to change
-a value in a document, you create an entire new version of that document
-and save it over the old one. After doing this, you end up with two versions
-of the same document, one old and one new.
-
-How does this offer an improvement over locks? Consider a set of requests
-wanting to access a document. The first request reads the document.
-While this is being processed, a second request changes the document.
-Since the second request includes a completely new version of the document,
-CouchDB can simply append it to the database without having to wait for the
-read request to finish.
-
-When a third request wants to read the same document, CouchDB will point it
-to the new version that has just been written. During this whole process,
-the first request could still be reading the original version.
-
-A read request will always see the most recent snapshot of your database at
-the time of the beginning of the request.
-
-.. _Subversion: http://subversion.apache.org/
-
-
-Validation
-==========
-
-As application developers, we have to think about what sort of input we
-should accept and what we should reject. The expressive power to do this type
-of validation over complex data within a traditional relational database
-leaves a lot to be desired. Fortunately, CouchDB provides a powerful way to
-perform per-document validation from within the database.
-
-CouchDB can validate documents using JavaScript functions similar to those
-used for MapReduce. Each time you try to modify a document,
-CouchDB will pass the validation function a copy of the existing document,
-a copy of the new document, and a collection of additional information,
-such as user authentication details. The validation function now has the
-opportunity to approve or deny the update.
-
-By working with the grain and letting CouchDB do this for us,
-we save ourselves a tremendous amount of CPU cycles that would otherwise have
-been spent serializing object graphs from SQL, converting them into domain
-objects, and using those objects to do application-level validation.
-
-
-Distributed Consistency
-=======================
-
-Maintaining consistency within a single database node is relatively easy for
-most databases. The real problems start to surface when you try to maintain
-consistency between multiple database servers. If a client makes a write
-operation on server `A`, how do we make sure that this is consistent with
-server `B`, or `C`, or `D`? For relational databases, this is a very complex
-problem with entire books devoted to its solution. You could use
-multi-master, single-master, partitioning, sharding, write-through caches,
-and all sorts of other complex techniques.
-
-
-Incremental Replication
-=======================
-
-CouchDB's operations take place within the context of a single document.
-As CouchDB achieves eventual consistency between multiple databases by using
-incremental replication you no longer have to worry about your database
-servers being able to stay in constant communication. Incremental replication
-is a process where document changes are periodically copied between servers.
-We are able to build what's known as a *shared nothing* cluster of databases
-where each node is independent and self-sufficient, leaving no single point
-of contention across the system.
-
-Need to scale out your CouchDB database cluster? Just throw in another server.
-
-As illustrated in :ref:`intro/consistency-04`, with CouchDB's incremental
-replication, you can synchronize your data between any two databases however
-you like and whenever you like. After replication, each database is able
-to work independently.
-
-You could use this feature to synchronize database servers within a cluster
-or between data centers using a job scheduler such as cron,
-or you could use it to synchronize data with your laptop for offline work as
-you travel. Each database can be used in the usual fashion,
-and changes between databases can be synchronized later in both directions.
-
-
-.. _intro/consistency-04:
-
-.. figure:: ../../images/intro-consistency-04.png
- :align: center
- :alt: Incremental replication between CouchDB nodes
-
- Figure 4. Incremental replication between CouchDB nodes
-
-
-What happens when you change the same document in two different databases and
-want to synchronize these with each other? CouchDB's replication system
-comes with automatic conflict detection and resolution. When CouchDB detects
-that a document has been changed in both databases, it flags this document
-as being in conflict, much like they would be in a regular version control
-system.
-
-This isn't as troublesome as it might first sound. When two versions of a
-document conflict during replication, the winning version is saved as the
-most recent version in the document's history. Instead of throwing the losing
-version away, as you might expect, CouchDB saves this as a previous version
-in the document's history, so that you can access it if you need to. This
-happens automatically and consistently, so both databases will make exactly
-the same choice.
-
-It is up to you to handle conflicts in a way that makes sense for your
-application. You can leave the chosen document versions in place,
-revert to the older version, or try to merge the two versions and save the
-result.
-
-
-Case Study
-==========
-
-Greg Borenstein, a friend and coworker, built a small library for converting
-Songbird playlists to JSON objects and decided to store these in CouchDB as
-part of a backup application. The completed software uses CouchDB's MVCC and
-document revisions to ensure that Songbird playlists are backed up robustly
-between nodes.
-
-.. note::
- `Songbird`_ is a free software media player with an integrated web browser,
- based on the Mozilla XULRunner platform. Songbird is available for Microsoft
- Windows, Apple Mac OS X, Solaris, and Linux.
-
- .. _Songbird: http://en.wikipedia.org/wiki/Songbird_%28software%29
-
-Let's examine the workflow of the Songbird backup application,
-first as a user backing up from a single computer, and then using Songbird to
-synchronize playlists between multiple computers. We'll see how document
-revisions turn what could have been a hairy problem into something that *just
-works*.
-
-The first time we use this backup application, we feed our playlists to the
-application and initiate a backup. Each playlist is converted to a JSON
-object and handed to a CouchDB database. As illustrated in
-:ref:`intro/consistency-05`, CouchDB hands back the document ID and
-revision of each playlist as it's saved to the database.
-
-
-.. _intro/consistency-05:
-
-.. figure:: ../../images/intro-consistency-05.png
- :align: center
- :alt: Backing up to a single database
-
- Figure 5. Backing up to a single database
-
-
-After a few days, we find that our playlists have been updated and we want to
-back up our changes. After we have fed our playlists to the backup
-application, it fetches the latest versions from CouchDB,
-along with the corresponding document revisions. When the application hands
-back the new playlist document, CouchDB requires that the document revision
-is included in the request.
-
-CouchDB then makes sure that the document revision handed to it in the
-request matches the current revision held in the database. Because CouchDB
-updates the revision with every modification, if these two are out of sync it
-suggests that someone else has made changes to the document between the time
-we requested it from the database and the time we sent our updates. Making
-changes to a document after someone else has modified it without first
-inspecting those changes is usually a bad idea.
-
-Forcing clients to hand back the correct document revision is the heart of
-CouchDB's optimistic concurrency.
-
-We have a laptop we want to keep synchronized with our desktop computer.
-With all our playlists on our desktop, the first step is to
-"restore from backup" onto our laptop. This is the first time we've done this,
-so afterward our laptop should hold an exact replica of our desktop playlist
-collection.
-
-After editing our Argentine Tango playlist on our laptop to add a few new
-songs we've purchased, we want to save our changes. The backup application
-replaces the playlist document in our laptop CouchDB database and a new
-document revision is generated. A few days later, we remember our new songs
-and want to copy the playlist across to our desktop computer. As illustrated
-in :ref:`intro/consistency-06`, the backup application copies the new document
-and the new revision to the desktop CouchDB database. Both CouchDB databases
-now have the same document revision.
-
-
-.. _intro/consistency-06:
-
-.. figure:: ../../images/intro-consistency-06.png
- :align: center
- :alt: Synchronizing between two databases
-
- Figure 6. Synchronizing between two databases
-
-
-Because CouchDB tracks document revisions, it ensures that updates like these
-will work only if they are based on current information. If we had made
-modifications to the playlist backups between synchronization,
-things wouldn't go as smoothly.
-
-We back up some changes on our laptop and forget to synchronize. A few days
-later, we're editing playlists on our desktop computer, make a backup,
-and want to synchronize this to our laptop. As illustrated in
-:ref:`intro/consistency-07`, when our backup application tries to replicate
-between the two databases, CouchDB sees that the changes being sent from our
-desktop computer are modifications of out-of-date documents and helpfully
-informs us that there has been a conflict.
-
-Recovering from this error is easy to accomplish from an application
-perspective. Just download CouchDB's version of the playlist and provide an
-opportunity to merge the changes or save local modifications into a new
-playlist.
-
-
-.. _intro/consistency-07:
-
-.. figure:: ../../images/intro-consistency-07.png
- :align: center
- :alt: Synchronization conflicts between two databases
-
- Figure 7. Synchronization conflicts between two databases
-
-
-Wrapping Up
-===========
-
-CouchDB's design borrows heavily from web architecture and the lessons
-learned deploying massively distributed systems on that architecture.
-By understanding why this architecture works the way it does,
-and by learning to spot which parts of your application can be easily
-distributed and which parts cannot, you'll enhance your ability to design
-distributed and scalable applications, with CouchDB or without it.
-
-We've covered the main issues surrounding CouchDB's consistency model and
-hinted at some of the benefits to be had when you work *with* CouchDB and not
-against it. But enough theory -- let's get up and running and see what all the
-fuss is about!
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cdac7299/share/doc/src/intro/curl.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro/curl.rst b/share/doc/src/intro/curl.rst
deleted file mode 100644
index 06b62b5..0000000
--- a/share/doc/src/intro/curl.rst
+++ /dev/null
@@ -1,122 +0,0 @@
-.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
-.. use this file except in compliance with the License. You may obtain a copy of
-.. the License at
-..
-.. http://www.apache.org/licenses/LICENSE-2.0
-..
-.. Unless required by applicable law or agreed to in writing, software
-.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-.. License for the specific language governing permissions and limitations under
-.. the License.
-
-.. _intro/curl:
-
-==============================
-cURL: Your Command Line Friend
-==============================
-
-The ``curl`` utility is a command line tool available on Unix, Linux,
-Mac OS X and Windows and many other platforms. ``curl`` 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.
-
-For simple ``GET`` requests you can supply the URL of the request. For
-example, to get the database information:
-
-.. code-block:: bash
-
- shell> curl http://127.0.0.1:5984
-
-This returns the database information (formatted in the output below for
-clarity):
-
-.. code-block:: json
-
- {
- "couchdb": "Welcome",
- "uuid": "85fb71bf700c17267fef77535820e371",
- "vendor": {
- "name": "The Apache Software Foundation",
- "version": "1.4.0"
- },
- "version": "1.4.0"
- }
-
-
-.. note:: 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:
-
- .. code-block:: bash
-
- shell> curl 'http://couchdb:5984/_uuids?count=5'
-
-You can explicitly set the HTTP command using the ``-X`` 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:
-
-.. code-block:: bash
-
- shell> curl -X PUT http://127.0.0.1:5984/demo
- {"ok":true}
-
-But to obtain the database information you use a ``GET`` request (with
-the return information formatted for clarity):
-
-.. code-block:: bash
-
- shell> curl -X GET http://127.0.0.1:5984/demo
- {
- "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
- }
-
-For certain operations, you must specify the content type of request,
-which you do by specifying the ``Content-Type`` header using the ``-H``
-command-line option:
-
-.. code-block:: bash
-
- shell> curl -H 'Content-Type: application/json' http://127.0.0.1:5984/_uuids
-
-You can also submit 'payload' data, that is, data in the body of the
-HTTP request using the ``-d`` 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 ``demo``
-database:
-
-.. code-block:: bash
-
- shell> curl -H 'Content-Type: application/json' \
- -X POST http://127.0.0.1:5984/demo \
- -d '{"company": "Example, Inc."}'
- {"ok":true,"id":"8843faaf0b831d364278331bc3001bd8",
- "rev":"1-33b9fbce46930280dab37d672bbc8bb9"}
-
-In the above example, the argument after the ``-d`` option is the JSON
-of the document we want to submit.
-
-The document can be accessed by using the automatically generated
-document ID that was returned:
-
-.. code-block:: bash
-
- shell> curl -X GET http://127.0.0.1:5984/demo/8843faaf0b831d364278331bc3001bd8
- {"_id":"8843faaf0b831d364278331bc3001bd8",
- "_rev":"1-33b9fbce46930280dab37d672bbc8bb9",
- "company":"Example, Inc."}
-
-The API samples in the :ref:`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 ``curl`` with the
-command-line examples shown above.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cdac7299/share/doc/src/intro/futon.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro/futon.rst b/share/doc/src/intro/futon.rst
deleted file mode 100644
index 3f93f5e..0000000
--- a/share/doc/src/intro/futon.rst
+++ /dev/null
@@ -1,186 +0,0 @@
-.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
-.. use this file except in compliance with the License. You may obtain a copy of
-.. the License at
-..
-.. http://www.apache.org/licenses/LICENSE-2.0
-..
-.. Unless required by applicable law or agreed to in writing, software
-.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-.. License for the specific language governing permissions and limitations under
-.. the License.
-
-.. _intro/futon:
-
-===================================
-Futon: Web GUI Administration Panel
-===================================
-
-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.
-
-The default view is the Overview 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:
-
-.. figure:: ../../images/futon-overview.png
- :align: center
- :alt: Futon Overview
-
- Futon Overview
-
-The main sections are:
-
-- Overview
-
- 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 :ref:`futon-management`.
-
-- Configuration
-
- 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 :ref:`config` section.
-
-- Replicator
-
- An interface to the replication system, enabling you to initiate
- replication between local and remote databases. See
- :ref:`futon-replication`.
-
-- Status
-
- Displays a list of the running background tasks on the server.
- Background tasks include view index building, compaction and
- replication. The Status page is an interface to the
- :ref:`Active Tasks <api/server/active_tasks>` API call.
-
-- Verify Installation
-
- The Verify Installation allows you to check whether all of the
- components of your CouchDB installation are correctly installed.
-
-- Test Suite
-
- The Test Suite 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 Run All
- button. This will execute all the tests, which may take some time.
-
-
-.. _futon-management:
-
-Managing Databases and Documents
-================================
-
-You can manage databases and documents within Futon using the main
-Overview section of the Futon interface.
-
-To create a new database, click the Create Database ELLIPSIS button. You
-will be prompted for the database name, as shown in the figure below.
-
-.. figure:: ../../images/futon-createdb.png
- :align: center
- :alt: Creating a Database
-
- Creating a Database
-
-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.
-
-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.
-
-For example, the figure below shows the editor for a single document, a
-newly created document with a single ID, the document ``_id`` field.
-
-.. figure:: ../../images/futon-editdoc.png
- :align: center
- :alt: Editing a Document
-
- Editing a Document
-
-To add a field to the document:
-
-1. Click Add Field.
-
-2. In the fieldname box, enter the name of the field you want to create.
- For example, “company”.
-
-3. Click the green tick next to the field name to confirm the field name
- change.
-
-4. Double-click the corresponding Value cell.
-
-5. Enter a company name, for example “Example”.
-
-6. Click the green tick next to the field value to confirm the field
- value.
-
-7. The document is still not saved as this point. You must explicitly
- save the document by clicking the Save Document button at the top of
- the page. This will save the document, and then display the new
- document with the saved revision information (the ``_rev`` field).
-
- .. figure:: ../../images/futon-editeddoc.png
- :align: center
- :alt: Edited Document
-
- Edited Document
-
-The same basic interface is used for all editing operations within Futon.
-You *must* remember to save the individual element (fieldname, value)
-using the green tick button, before then saving the document.
-
-
-.. _futon-replication:
-
-Configuring Replication
-=======================
-
-When you click the Replicator option within the Tools 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.
-
-.. figure:: ../../images/futon-replform.png
- :align: center
- :alt: Replication Form
-
- Replication Form
-
-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.
-
-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
-``http://username:pass@remotehost:5984/demo``.
-
-To enable continuous replication, click the Continuous checkbox.
-
-To start the replication process, click the Replicate 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 Status option under the Tools menu.
-
-Once replication has been completed, the page will show the information
-returned when the replication process completes by the API.
-
-The Replicator tool is an interface to the underlying replication API.
-For more information, see :ref:`api/server/replicate`. For more information on
-replication, see :ref:`replication`.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cdac7299/share/doc/src/intro/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro/index.rst b/share/doc/src/intro/index.rst
deleted file mode 100644
index 1c1088b..0000000
--- a/share/doc/src/intro/index.rst
+++ /dev/null
@@ -1,56 +0,0 @@
-.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
-.. use this file except in compliance with the License. You may obtain a copy of
-.. the License at
-..
-.. http://www.apache.org/licenses/LICENSE-2.0
-..
-.. Unless required by applicable law or agreed to in writing, software
-.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-.. License for the specific language governing permissions and limitations under
-.. the License.
-
-
-.. _intro:
-
-============
-Introduction
-============
-
-CouchDB is a database that completely embraces the web. Store your data with
-JSON documents. Access your documents with your web browser, :ref:`via HTTP
-<api/basics>`. :ref:`Query <api/doc>`, :ref:`combine <views>`,
-and :ref:`transform <listfun>` your documents with :ref:`JavaScript
-<query-server/js>`. CouchDB works well with modern web and mobile apps. You can
-even serve web apps directly out of CouchDB. And you can distribute your data,
-or your apps, efficiently using CouchDB’s :ref:`incremental replication
-<replication/intro>`. CouchDB supports master-master setups with
-:ref:`automatic conflict <replication/conflicts>` detection.
-
-CouchDB comes with a suite of features, such as on-the-fly document
-transformation and real-time :ref:`change notifications <changes>`, that makes
-:ref:`web app <couchapp>` development a breeze. It even comes with an easy
-to use :ref:`web administration console <intro/futon>`. You guessed it,
-served up directly out of CouchDB! We care a lot about `distributed scaling`_.
-CouchDB is highly available and partition tolerant, but is also :ref:`eventually
-consistent <intro/consistency>`. And we care *a lot* about your data.
-CouchDB has a fault-tolerant storage engine that puts the safety of your data
-first.
-
-In this section you'll learn about every basic bit of CouchDB, see upon what
-conceptions and technologies it built and walk through short tutorial that
-teach how to use CouchDB.
-
-.. _distributed scaling: http://en.wikipedia.org/wiki/CAP_theorem
-
-.. toctree::
- :maxdepth: 2
-
- overview
- why
- consistency
- tour
- api
- security
- futon
- curl