couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From robertkowal...@apache.org
Subject [13/47] couchdb commit: updated refs/heads/enable-csp-default to dbd38a1
Date Fri, 28 Nov 2014 21:00:15 GMT
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cdac7299/share/doc/src/intro/overview.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro/overview.rst b/share/doc/src/intro/overview.rst
deleted file mode 100644
index 7804cf9..0000000
--- a/share/doc/src/intro/overview.rst
+++ /dev/null
@@ -1,388 +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/overview:
-
-==================
-Technical Overview
-==================
-
-Document Storage
-================
-
-A CouchDB server hosts named databases, which store **documents**.
-Each document is uniquely named in the database, and CouchDB provides
-a `RESTful`_ :ref:`HTTP API <api/basics>` for reading and updating (add, edit,
-delete)  database documents.
-
-Documents are the primary unit of data in CouchDB and consist of any number
-of fields and attachments. Documents also include metadata that’s maintained
-by the database system. Document fields are uniquely named and contain values
-of :ref:`varying types <json>` (text, number, boolean, lists, etc),
-and there is no set limit to text size or element count.
-
-The CouchDB document update model is lockless and optimistic.
-Document edits are made by client applications loading documents,
-applying changes, and saving them back to the database. If another client
-editing the same document saves their changes first, the client gets an edit
-conflict error on save. To resolve the update conflict, the latest document
-version can be opened, the edits reapplied and the update tried again.
-
-Document updates (add, edit, delete) are all or nothing, either succeeding
-entirely or failing completely. The database never contains partially saved
-or edited documents.
-
-.. _RESTful: http://en.wikipedia.org/wiki/REST
-
-
-ACID Properties
-===============
-
-The CouchDB file layout and commitment system features all `Atomic Consistent
-Isolated Durable` (`ACID`_) properties. On-disk, CouchDB never overwrites
-committed data or associated structures, ensuring the database file is always
-in a consistent state. This is a "crash-only" design where the CouchDB
-server does not go through a shut down process, it's simply terminated.
-
-Document updates (add, edit, delete) are serialized, except for binary blobs
-which are written concurrently. Database readers are never locked out and
-never have to wait on writers or other readers. Any number of clients can be
-reading documents without being locked out or interrupted by concurrent
-updates, even on the same document. CouchDB read operations use a
-`Multi-Version Concurrency Control` (`MVCC`_) model where each client sees a
-consistent snapshot of the database from the beginning to the end of the read
-operation.
-
-Documents are indexed in `B-trees`_ by their name (DocID) and a Sequence ID.
-Each update to a database instance generates a new sequential number.
-Sequence IDs are used later for incrementally finding changes in a database.
-These B-tree indexes are updated simultaneously when documents are saved or
-deleted. The index updates always occur at the end of the file (append-only
-updates).
-
-Documents have the advantage of data being already conveniently packaged for
-storage rather than split out across numerous tables and rows in most
-database systems. When documents are committed to disk, the document fields
-and metadata are packed into buffers, sequentially one document after another
-(helpful later for efficient building of views).
-
-When CouchDB documents are updated, all data and associated indexes are
-flushed to disk and the transactional commit always leaves the database
-in a completely consistent state. Commits occur in two steps:
-
-#. All document data and associated index updates are synchronously flushed
-   to disk.
-
-#. The updated database header is written in two consecutive, identical chunks
-   to make up the first 4k of the file, and then synchronously flushed to disk.
-
-In the event of an OS crash or power failure during step 1,
-the partially flushed updates are simply forgotten on restart. If such a
-crash happens during step 2 (committing the header), a surviving copy of the
-previous identical headers will remain, ensuring coherency of all previously
-committed data. Excepting the header area, consistency checks or fix-ups
-after a crash or a power failure are never necessary.
-
-.. _ACID: http://en.wikipedia.org/wiki/ACID
-.. _MVCC: http://en.wikipedia.org/wiki/Multiversion_concurrency_control
-.. _B-trees: http://en.wikipedia.org/wiki/B-tree
-
-
-Compaction
-==========
-
-Wasted space is recovered by occasional compaction. On schedule, or when the
-database file exceeds a certain amount of wasted space, the compaction process
-clones all the active data to a new file and then discards the old file.
-The database remains completely online the entire time and all updates and
-reads are allowed to complete successfully. The old database file is deleted only when
-all the data has been copied and all users transitioned to the new file.
-
-
-Views
-=====
-
-ACID properties only deal with storage and updates, but we also need the ability
-to show our data in interesting and useful ways. Unlike SQL databases where
-data must be carefully decomposed into tables, data in CouchDB is stored in
-semi-structured documents. CouchDB documents are flexible and each has its
-own implicit structure, which alleviates the most difficult problems and
-pitfalls of bi-directionally replicating table schemas and their contained data.
-
-But beyond acting as a fancy file server, a simple document model for data
-storage and sharing is too simple to build real applications on -- it simply
-doesn't do enough of the things we want and expect. We want to slice and dice
-and see our data in many different ways. What is needed is a way to filter,
-organize and report on data that hasn't been decomposed into tables.
-
-.. seealso::
-
-   :ref:`views`
-
-
-View Model
-----------
-
-To address this problem of adding structure back to unstructured and
-semi-structured data, CouchDB integrates a view model. Views are the method
-of aggregating and reporting on the documents in a database, and are built
-on-demand to aggregate, join and report on database documents. Because views are built
-dynamically and don’t affect the underlying document, you can have as many
-different view representations of the same data as you like.
-
-View definitions are strictly virtual and only display the documents from the
-current database instance, making them separate from the data they display
-and compatible with replication. CouchDB views are defined inside special
-**design documents** and can replicate across database instances like
-regular documents, so that not only data replicates in CouchDB,
-but entire application designs replicate too.
-
-
-Javascript View Functions
--------------------------
-
-Views are defined using Javascript functions acting as the map part in a
-`map-reduce system`_. A :ref:`view function <viewfun>` takes a CouchDB document
-as an argument and then does whatever computation it needs to do to determine
-the data that is to be made available through the view, if any.
-It can add multiple rows to the view based on a single document,
-or it can add no rows at all.
-
-.. _map-reduce system: http://en.wikipedia.org/wiki/MapReduce
-
-.. seealso::
-
-  :ref:`viewfun`
-
-
-View Indexes
-------------
-
-Views are a dynamic representation of the actual document contents of a
-database, and CouchDB makes it easy to create useful views of data.
-But generating a view of a database with hundreds of thousands or millions of
-documents is time and resource consuming, it's not something the system
-should do from scratch each time.
-
-To keep view querying fast, the view engine maintains indexes of its views,
-and incrementally updates them to reflect changes in the database.
-CouchDB’s core design is largely optimized around the need for efficient,
-incremental creation of views and their indexes.
-
-Views and their functions are defined inside special "design" documents,
-and a design document may contain any number of uniquely named view functions.
-When a user opens a view and its index is automatically updated, all the views
-in the same design document are indexed as a single group.
-
-The view builder uses the database sequence ID to determine if the view group
-is fully up-to-date with the database. If not, the view engine examines the
-all database documents (in packed sequential order) changed since the last
-refresh. Documents are read in the order they occur in the disk file,
-reducing the frequency and cost of disk head seeks.
-
-The views can be read and queried simultaneously while also being refreshed.
-If a client is slowly streaming out the contents of a large view,
-the same view can be concurrently opened and refreshed for another client
-without blocking the first client. This is true for any number of
-simultaneous client readers, who can read and query the view while the index
-is concurrently being refreshed for other clients without causing problems
-for the readers.
-
-As documents are processed by the view engine through your 'map' and 'reduce'
-functions, their previous row values are removed from the view indexes, if
-they exist. If the document is selected by a view function, the function results
-are inserted into the view as a new row.
-
-When view index changes are written to disk, the updates are always appended
-at the end of the file, serving to both reduce disk head seek times during
-disk commits and to ensure crashes and power failures can not cause
-corruption of indexes. If a crash occurs while updating a view index,
-the incomplete index updates are simply lost and rebuilt incrementally from
-its previously committed state.
-
-
-Security and Validation
-=======================
-
-To protect who can read and update documents, CouchDB has a simple reader
-access and update validation model that can be extended to implement custom
-security models.
-
-.. seealso::
-
-   :ref:`api/db/security`
-
-
-Administrator Access
---------------------
-
-CouchDB database instances have administrator accounts. Administrator
-accounts can create other administrator accounts and update design documents.
-Design documents are special documents containing view definitions and other
-special formulas, as well as regular fields and blobs.
-
-
-Update Validation
------------------
-
-As documents written to disk, they can be validated dynamically by javascript
-functions for both security and data validation. When the document passes
-all the formula validation criteria, the update is allowed to continue.
-If the validation fails, the update is aborted and the user client gets an
-error response.
-
-Both the user's credentials and the updated document are given as inputs to
-the validation formula, and can be used to implement custom security models
-by validating a user's permissions to update a document.
-
-A basic "author only" update document model is trivial to implement,
-where document updates are validated to check if the user is listed in an
-"author" field in the existing document. More dynamic models are also possible,
-like checking a separate user account profile for permission settings.
-
-The update validations are enforced for both live usage and replicated
-updates, ensuring security and data validation in a shared, distributed system.
-
-.. seealso::
-
-   :ref:`vdufun`
-
-
-Distributed Updates and Replication
-===================================
-
-CouchDB is a peer-based distributed database system. It allows users and servers
-to access and update the same shared data while disconnected. Those changes can
-then be replicated bi-directionally later.
-
-The CouchDB document storage, view and security models are designed to work
-together to make true bi-directional replication efficient and reliable.
-Both documents and designs can replicate, allowing full database applications
-(including application design, logic and data) to be replicated to laptops
-for offline use, or replicated to servers in remote offices where slow or
-unreliable connections make sharing data difficult.
-
-The replication process is incremental. At the database level,
-replication only examines documents updated since the last replication.
-Then for each updated document, only fields and blobs that have changed are
-replicated across the network. If replication fails at any step, due to network
-problems or crash for example, the next replication restarts at the same
-document where it left off.
-
-Partial replicas can be created and maintained. Replication can be filtered
-by a javascript function, so that only particular documents or those meeting
-specific criteria are replicated. This can allow users to take subsets of a
-large shared database application offline for their own use, while maintaining
-normal interaction with the application and that subset of data.
-
-
-Conflicts
----------
-
-Conflict detection and management are key issues for any distributed edit
-system. The CouchDB storage system treats edit conflicts as a common state,
-not an exceptional one. The conflict handling model is simple and
-"non-destructive" while preserving single document semantics and allowing for
-decentralized conflict resolution.
-
-CouchDB allows for any number of conflicting documents to exist
-simultaneously in the database, with each database instance deterministically
-deciding which document is the "winner" and which are conflicts. Only the
-winning document can appear in views, while "losing" conflicts are still
-accessible and remain in the database until deleted or purged during
-database compaction. Because conflict documents are still regular documents,
-they replicate just like regular documents and are subject to the same
-security and validation rules.
-
-When distributed edit conflicts occur, every database replica sees the same
-winning revision and each has the opportunity to resolve the conflict.
-Resolving conflicts can be done manually or, depending on the nature of the
-data and the conflict, by automated agents. The system makes decentralized
-conflict resolution possible while maintaining single document database
-semantics.
-
-Conflict management continues to work even if multiple disconnected users or
-agents attempt to resolve the same conflicts. If resolved conflicts result in
-more conflicts, the system accommodates them in the same manner, determining
-the same winner on each machine and maintaining single document semantics.
-
-.. seealso::
-
-   :ref:`replication/conflicts`
-
-
-Applications
-------------
-
-Using just the basic replication model, many traditionally single server
-database applications can be made distributed with almost no extra work.
-CouchDB replication is designed to be immediately useful for basic database
-applications, while also being extendable for more elaborate and full-featured
-uses.
-
-With very little database work, it is possible to build a distributed
-document management application with granular security and full revision
-histories. Updates to documents can be implemented to exploit incremental
-field and blob replication, where replicated updates are nearly as efficient
-and incremental as the actual edit differences ("diffs").
-
-The CouchDB replication model can be modified for other distributed update
-models. If the storage engine is enhanced to allow multi-document update
-transactions, it is possible to perform Subversion-like "all or nothing"
-atomic commits when replicating with an upstream server, such that any single
-document conflict or validation failure will cause the entire update to fail.
-Like Subversion, conflicts would be resolved by doing a "pull" replication to
-force the conflicts locally, then merging and  re-replicating to the upstream
-server.
-
-
-Implementation
-==============
-
-CouchDB is built on the `Erlang OTP platform`_, a functional,
-concurrent programming language and development platform. Erlang was
-developed for real-time telecom applications with an extreme emphasis on
-reliability and availability.
-
-Both in syntax and semantics, Erlang is very different from conventional
-programming languages like C or Java. Erlang uses lightweight "processes" and
-message passing for concurrency, it has no shared state threading and all
-data is immutable. The robust, concurrent nature of Erlang is ideal for a
-database server.
-
-CouchDB is designed for lock-free concurrency, in the conceptual model and
-the actual Erlang implementation. Reducing bottlenecks and avoiding locks
-keeps the entire system working predictably under heavy loads. CouchDB can
-accommodate many clients replicating changes, opening and updating documents,
-and querying views whose indexes are simultaneously being refreshed for
-other clients, without needing locks.
-
-For higher availability and more concurrent users, CouchDB is designed for
-"shared nothing" clustering. In a "shared nothing" cluster, each machine
-is independent and replicates data with its cluster mates, allowing individual
-server failures with zero downtime. And because consistency scans
-and fix-ups aren’t needed on restart,
-if the entire cluster fails -- due to a power outage in a datacenter,
-for example -- the entire CouchDB distributed system becomes immediately
-available after a restart.
-
-CouchDB is built from the start with a consistent vision of a distributed
-document database system. Unlike cumbersome attempts to bolt distributed
-features on top of the same legacy models and databases,
-it is the result of careful ground-up design, engineering and integration.
-The document, view, security and replication models, the special purpose query
-language, the efficient and robust disk layout and the concurrent and reliable
-nature of the Erlang platform are all carefully integrated for a reliable
-and efficient system.
-
-.. _Erlang OTP platform: http://www.erlang.org/

http://git-wip-us.apache.org/repos/asf/couchdb/blob/cdac7299/share/doc/src/intro/security.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro/security.rst b/share/doc/src/intro/security.rst
deleted file mode 100644
index 77c95cb..0000000
--- a/share/doc/src/intro/security.rst
+++ /dev/null
@@ -1,603 +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/security:
-
-********
-Security
-********
-
-In this document, we'll look at the basic security mechanisms in CouchDB: the
-`Admin Party`, `Basic Authentication`, `Cookie Authentication`; how CouchDB
-handles users and protects their credentials.
-
-==============
-Authentication
-==============
-
-.. _intro/security/admin_party:
-
-The Admin Party
-===============
-
-When you start out fresh, CouchDB allows any request to be made by anyone.
-Create a database? No problem, here you go. Delete some documents? Same deal.
-CouchDB calls this the `Admin Party`. Everybody has privileges to do anything.
-Neat.
-
-While it is incredibly easy to get started with CouchDB that way,
-it should be obvious that putting a default installation into the wild is
-adventurous. Any rogue client could come along and delete a database.
-
-A note of relief: by default, CouchDB will listen only on your loopback
-network interface (``127.0.0.1`` or ``localhost``) and thus only you will be
-able to make requests to CouchDB, nobody else. But when you start to open up
-your CouchDB to the public (that is, by telling it to bind to your machine's
-public IP address), you will want to think about restricting access so that
-the next bad guy doesn't ruin your admin party.
-
-In our previous discussions, we dropped some keywords about how things
-without the `Admin Party` work. First, there's *admin* itself, which implies
-some sort of super user. Then there are *privileges*. Let's explore these terms
-a little more.
-
-CouchDB has the idea of an *admin user* (e.g. an administrator, a super user,
-or root) that is allowed to do anything to a CouchDB installation. By default,
-everybody is an admin. If you don't like that, you can create specific admin
-users with a username and password as their credentials.
-
-CouchDB also defines a set of requests that only admin users are allowed to
-do. If you have defined one or more specific admin users, CouchDB will ask for
-identification for certain requests:
-
-- Creating a database (:put:`PUT /database </{db}>`)
-- Deleting a database (:put:`DELETE /database </{db}>`)
-- Setup a database security (:put:`PUT /database/_security
-  </{db}/_security>`)
-- Creating a design document (:put:`PUT /database/_design/app
-  </{db}/_design/{ddoc}>`)
-- Updating a design document (:put:`PUT /database/_design/app?rev=1-4E2
-  </{db}/_design/{ddoc}>`)
-- Deleting a design document (:delete:`DELETE /database/_design/app?rev=2-6A7
-  </{db}/_design/{ddoc}>`)
-- Execute a temporary view (:post:`POST /database/_temp_view
-  </{db}/_temp_view>`)
-- Triggering compaction (:post:`POST /database/_compact </{db}/_compact>`)
-- Reading the task status list (:get:`GET /_active_tasks </_active_tasks>`)
-- Restarting the server (:post:`POST /_restart </_restart>`)
-- Reading the active configuration (:get:`GET /_config </_config>`)
-- Updating the active configuration (:put:`PUT /_config/section/key
-  </_config/{section}/{key}>`)
-
-
-Creating New Admin User
------------------------
-
-Let's do another walk through the API using `curl` to see how CouchDB behaves
-when you add admin users.
-
-::
-
-  > HOST="http://127.0.0.1:5984"
-  > curl -X PUT $HOST/database
-  {"ok":true}
-
-When starting out fresh, we can add a database. Nothing unexpected. Now let's
-create an admin user. We'll call her ``anna``, and her password is ``secret``.
-Note the double quotes in the following code; they are needed to denote a string
-value for the :ref:`configuration API <api/config>`::
-
-  > curl -X PUT $HOST/_config/admins/anna -d '"secret"'
-  ""
-
-As per the :ref:`_config <api/config>` API's behavior, we're getting
-the previous value for the config item we just wrote. Since our admin user
-didn't exist, we get an empty string.
-
-
-Hashing Passwords
------------------
-
-Seeing the plain-text password is scary, isn't it? No worries, CouchDB doesn't
-show up the plain-text password anywhere. It gets hashed right away. The hash
-is that big, ugly, long string that starts out with ``-hashed-``.
-How does that work?
-
-#. Creates a new 128-bit UUID. This is our *salt*.
-#. Creates a sha1 hash of the concatenation of the bytes of the plain-text
-   password and the salt ``(sha1(password + salt))``.
-#. Prefixes the result with ``-hashed-`` and appends ``,salt``.
-
-To compare a plain-text password during authentication with the stored hash,
-the same procedure is run and the resulting hash is compared to the stored
-hash. The probability of two identical hashes for different passwords is too
-insignificant to mention (c.f. `Bruce Schneier`_). Should the stored hash fall
-into the hands of an attacker, it is, by current standards, way too inconvenient
-(i.e., it'd take a lot of money and time) to find the plain-text password from
-the hash.
-
-.. _Bruce Schneier: http://en.wikipedia.org/wiki/Bruce_Schneier
-
-But what's with the ``-hashed-`` prefix? When CouchDB starts up, it reads a set
-of `.ini` files with config settings. It loads these settings into an internal
-data store (not a database). The config API lets you read the current
-configuration as well as change it and create new entries. CouchDB is writing
-any changes back to the `.ini` files.
-
-The `.ini` files can also be edited by hand when CouchDB is not running.
-Instead of creating the admin user as we showed previously, you could have
-stopped CouchDB, opened your `local.ini`, added ``anna = secret`` to the
-:config:section:`admins`, and restarted CouchDB. Upon reading the new line from
-`local.ini`, CouchDB would run the hashing algorithm and write back the hash to
-`local.ini`, replacing the plain-text password. To make sure CouchDB only hashes
-plain-text passwords and not an existing hash a second time, it prefixes
-the hash with ``-hashed-``, to distinguish between plain-text passwords and
-hashed passwords. This means your plain-text password can't start with the
-characters ``-hashed-``, but that's pretty unlikely to begin with.
-
-.. note::
-
-   Since :ref:`1.3.0 release <release/1.3.0>` CouchDB uses ``-pbkdf2-`` prefix
-   by default to sign about using `PBKDF2`_ hashing algorithm instead of `SHA1`.
-
-   .. _PBKDF2: http://en.wikipedia.org/wiki/PBKDF2
-
-
-.. _intro/security/basicauth:
-
-Basic Authentication
-====================
-
-Now that we have defined an admin, CouchDB will not allow us to create new
-databases unless we give the correct admin user credentials. Let's verify::
-
-  > curl -X PUT $HOST/somedatabase
-  {"error":"unauthorized","reason":"You are not a server admin."}
-
-That looks about right. Now we try again with the correct credentials::
-
-  > HOST="http://anna:secret@127.0.0.1:5984"
-  > curl -X PUT $HOST/somedatabase
-  {"ok":true}
-
-If you have ever accessed a website or FTP server that was password-protected,
-the ``username:password@`` URL variant should look familiar.
-
-If you are security conscious, the missing ``s`` in ``http://`` will make you
-nervous. We're sending our password to CouchDB in plain text. This is a bad
-thing, right? Yes, but consider our scenario: CouchDB listens on ``127.0.0.1``
-on a development box that we're the sole user of. Who could possibly sniff our
-password?
-
-If you are in a production environment, however, you need to reconsider. Will
-your CouchDB instance communicate over a public network? Even a LAN shared
-with other collocation customers is public. There are multiple ways to secure
-communication between you or your application and CouchDB that exceed the
-scope of this documentation. CouchDB as of version :ref:`1.1.0 <release/1.1.0>`
-comes with :ref:`SSL built in <config/ssl>`.
-
-.. seealso::
-
-   :ref:`Basic Authentication API Reference <api/auth/basic>`
-
-
-.. _intro/security/cookie:
-
-Cookie Authentication
-=====================
-
-Basic authentication that uses plain-text passwords is nice and convenient,
-but not very secure if no extra measures are taken. It is also a very poor
-user experience. If you use basic authentication to identify admins,
-your application's users need to deal with an ugly, unstylable browser modal
-dialog that says non-professional at work more than anything else.
-
-To remedy some of these concerns, CouchDB supports cookie authentication.
-With cookie authentication your application doesn't have to include the ugly
-login dialog that the users' browsers come with. You can use a regular HTML
-form to submit logins to CouchDB. Upon receipt, CouchDB will generate a
-one-time token that the client can use in its next request to CouchDB. When
-CouchDB sees the token in a subsequent request, it will authenticate the user
-based on the token without the need to see the password again. By default,
-a token is valid for 10 minutes.
-
-To obtain the first token and thus authenticate a user for the first time,
-the username and password must be sent to the :ref:`_session <api/auth/session>`
-API. The API is smart enough to decode HTML form submissions, so you don't have
-to resort to any smarts in your application.
-
-If you are not using HTML forms to log in, you need to send an HTTP request
-that looks as if an HTML form generated it. Luckily, this is super simple::
-
-  > HOST="http://127.0.0.1:5984"
-  > curl -vX POST $HOST/_session \
-         -H 'Content-Type:application/x-www-form-urlencoded' \
-         -d 'name=anna&password=secret'
-
-CouchDB replies, and we'll give you some more detail::
-
-  < HTTP/1.1 200 OK
-  < Set-Cookie: AuthSession=YW5uYTo0QUIzOTdFQjrC4ipN-D-53hw1sJepVzcVxnriEw;
-  < Version=1; Path=/; HttpOnly
-  > ...
-  <
-  {"ok":true}
-
-A :statuscode:`200` response code tells us all is well, a :header:`Set-Cookie`
-header includes the token we can use for the next request, and the standard JSON
-response tells us again that the request was successful.
-
-Now we can use this token to make another request as the same user without
-sending the username and password again::
-
-  > curl -vX PUT $HOST/mydatabase \
-         --cookie AuthSession=YW5uYTo0QUIzOTdFQjrC4ipN-D-53hw1sJepVzcVxnriEw \
-         -H "X-CouchDB-WWW-Authenticate: Cookie" \
-         -H "Content-Type:application/x-www-form-urlencoded"
-  {"ok":true}
-
-You can keep using this token for 10 minutes by default. After 10 minutes you
-need to authenticate your user again. The token lifetime can be configured
-with the timeout (in seconds) setting in the :ref:`couch_httpd_auth
-<config/couch_httpd_auth>` configuration section.
-
-.. seealso::
-
-   :ref:`Cookie Authentication API Reference <api/auth/cookie>`
-
-
-=======================
-Authentication Database
-=======================
-
-You may already note, that CouchDB administrators are defined within config file
-and you now wondering does regular users are also stored there. No, they don't.
-CouchDB has special `authentication database` -- ``_users`` by default -- that
-stores all registered users as JSON documents.
-
-CouchDB uses special database (called ``_users`` by default) to store
-information about registered users. This is a `system database` -- this means
-that while it shares common :ref:`database API <api/database>`, there are some
-special security-related constraints applied and used agreements on documents
-structure. So how `authentication database` is different from others?
-
-- Only administrators may browse list of all documents
-  (:get:`GET /_users/_all_docs </{db}/_all_docs>`)
-- Only administrators may listen :ref:`changes feed
-  <changes>` (:get:`GET /_users/_changes </{db}/_changes>`)
-- Only administrators may execute design functions like :ref:`views <viewfun>`,
-  :ref:`shows <showfun>` and :ref:`others <ddocs>`
-- Only administrators may :method:`GET`, :method:`PUT` or :method:`DELETE`
-  any document (to be honest, that they always can do)
-- There is special design document ``_auth`` that cannot be modified
-- Every document (of course, except `design documents`) represents registered
-  CouchDB users and belong to them
-- Users may only access (:get:`GET /_users/org.couchdb.user:Jan
-  </{db}/{docid}>`) or modify (:put:`PUT /_users/org.couchdb.user:Jan
-  </{db}/{docid}>`) documents that they owns
-
-These draconian rules are reasonable: CouchDB cares about user's personal
-information and doesn't discloses it for everyone. Often, users documents are
-contains not only system information like `login`, `password hash` and `roles`,
-but also sensitive personal information like: real name, email, phone, special
-internal identifications and more - this is not right information that you
-want to share with the World.
-
-
-Users Documents
-===============
-
-Each CouchDB user is stored in document format. These documents are contains
-several *mandatory* fields, that CouchDB handles for correct authentication
-process:
-
-- **_id** (*string*): Document ID. Contains user's login with special prefix
-  :ref:`org.couchdb.user`
-- **derived_key** (*string*): `PBKDF2`_ key
-- **name** (*string*): User's name aka login. **Immutable** e.g. you cannot
-  rename existed user - you have to create new one
-- **roles** (*array* of *string*): List of user roles. CouchDB doesn't provides
-  any builtin roles, so you're free to define your own depending on your needs.
-  However, you cannot set system roles like ``_admin`` there. Also, only
-  administrators may assign roles to users - by default all users have no roles
-- **password_sha** (*string*): Hashed password with salt. Used for ``simple``
-  `password_scheme`
-- **password_scheme** (*string*): Password hashing scheme. May be ``simple`` or
-  ``pbkdf2``
-- **salt** (*string*): Hash salt. Used for ``simple`` `password_scheme`
-- **type** (*string*): Document type. Constantly have value ``user``
-
-Additionally, you may specify any custom fields that are relates to the target
-user. This is good place to store user's private information because only the
-target user and CouchDB administrators may browse it.
-
-.. _org.couchdb.user:
-
-Why ``org.couchdb.user:`` prefix?
----------------------------------
-
-The reason to have special prefix before user's login name is to have
-namespaces which users are belongs to. This prefix is designed to prevent
-replication conflicts when you'll try to merge two `_user` databases or more.
-
-For current CouchDB releases, all users are belongs to the same
-``org.couchdb.user`` namespace and this cannot be changed, but we'd made
-such design decision for future releases.
-
-
-Creating New User
-=================
-
-Creating new user is a very trivial operation. You need just to send single
-:method:`PUT` request with user's data to CouchDB. Let's create user with login
-`jan` and password `apple`::
-
-  curl -X PUT http://localhost:5984/_users/org.couchdb.user:jan \
-       -H "Accept: application/json" \
-       -H "Content-Type: application/json" \
-       -d '{"name": "jan", "password": "apple", "roles": [], "type": "user"}'
-
-This `curl` command will produce next HTTP request:
-
-.. code-block:: http
-
-  PUT /_users/org.couchdb.user:jan HTTP/1.1
-  Accept: application/json
-  Content-Length: 62
-  Content-Type: application/json
-  Host: localhost:5984
-  User-Agent: curl/7.31.0
-
-And CouchDB responds with:
-
-.. code-block:: http
-
-  HTTP/1.1 201 Created
-  Cache-Control: must-revalidate
-  Content-Length: 83
-  Content-Type: application/json
-  Date: Fri, 27 Sep 2013 07:33:28 GMT
-  ETag: "1-e0ebfb84005b920488fc7a8cc5470cc0"
-  Location: http://localhost:5984/_users/org.couchdb.user:jan
-  Server: CouchDB (Erlang OTP)
-
-  {"ok":true,"id":"org.couchdb.user:jan","rev":"1-e0ebfb84005b920488fc7a8cc5470cc0"}
-
-Document successfully created what also means that user `jan` have created too!
-Let's check is this true::
-
-  curl -X POST http://localhost:5984/_session -d 'name=jan&password=apple'
-
-CouchDB should respond with:
-
-.. code-block:: javascript
-
-  {"ok":true,"name":"jan","roles":[]}
-
-Which means that username was recognized and password's hash matches with stored
-one. If we specify wrong login and/or password, CouchDB will notify us with
-the next error message:
-
-.. code-block:: javascript
-
-  {"error":"unauthorized","reason":"Name or password is incorrect."}
-
-
-Password Changing
-=================
-
-This is quite common situation: user had forgot their password, it was leaked
-somehow (via copy-paste, screenshot, or by typing in wrong chat window) or
-something else. Let's change password for our user `jan`.
-
-First of all, let's define what is the password changing from the point of
-CouchDB and the authentication database. Since "users" are "documents", this
-operation is nothing, but updating the document with special field ``password``
-which contains the *plain text password*. Scared? No need to: the authentication
-database has special internal hook on  document update which looks for this
-field and replaces it with the *secured hash*, depending on chosen
-``password_scheme``.
-
-Summarizing above, we need to get document content, add ``password`` field
-with new plain text password value and store JSON result to the authentication
-database.
-
-::
-
-  curl -X GET http://localhost:5984/_users/org.couchdb.user:jan
-
-.. code-block:: javascript
-
-  {
-    "_id": "org.couchdb.user:jan",
-    "_rev": "1-e0ebfb84005b920488fc7a8cc5470cc0",
-    "derived_key": "e579375db0e0c6a6fc79cd9e36a36859f71575c3",
-    "iterations": 10,
-    "name": "jan",
-    "password_scheme": "pbkdf2",
-    "roles": [],
-    "salt": "1112283cf988a34f124200a050d308a1",
-    "type": "user"
-  }
-
-Here is our user's document. We may strip hashes from stored document to reduce
-amount of posted data::
-
-  curl -X PUT http://localhost:5984/_users/org.couchdb.user:jan \
-       -H "Accept: application/json" \
-       -H "Content-Type: application/json" \
-       -H "If-Match: 1-e0ebfb84005b920488fc7a8cc5470cc0" \
-       -d '{"name":"jan", "roles":[], "type":"user", "password":"orange"}'
-
-.. code-block:: javascript
-
-  {"ok":true,"id":"org.couchdb.user:jan","rev":"2-ed293d3a0ae09f0c624f10538ef33c6f"}
-
-Updated! Now let's check that password was really changed::
-
-  curl -X POST http://localhost:5984/_session -d 'name=jan&password=apple'
-
-CouchDB should respond with:
-
-.. code-block:: javascript
-
-  {"error":"unauthorized","reason":"Name or password is incorrect."}
-
-Looks like the password ``apple`` is wrong, what about ``orange``?
-
-::
-
-  curl -X POST http://localhost:5984/_session -d 'name=jan&password=orange'
-
-CouchDB should respond with:
-
-.. code-block:: javascript
-
-  {"ok":true,"name":"jan","roles":[]}
-
-Hooray! You may wonder why so complex: need to retrieve user's document, add
-special field to it, post it back - where is one big button that changes the
-password without worry about document's content? Actually, :ref:`Futon
-<intro/futon>` has such at the right bottom corner if you have logged in -
-all implementation details are hidden from your sight.
-
-.. note::
-
-  There is no password confirmation for API request: you should implement it
-  on your application layer like Futon does.
-
-
-Users Public Information
-========================
-
-.. versionadded:: 1.4
-
-Sometimes users *wants* to share some information with the World. For instance,
-their contact email to let other users get in touch with them. To solve this
-problem, but still keep sensitive and private information secured there is
-special :ref:`configuration <config>` option :config:option:`public_fields
-<couch_httpd_auth/public_fields>`. In this options you may define comma
-separated list of users document fields that will be publicity available.
-
-Normally, if you request any user's document and you're not administrator or
-this document owner, CouchDB will respond with :statuscode:`404`::
-
-  curl http://localhost:5984/_users/org.couchdb.user:robert
-
-.. code-block:: javascript
-
-  {"error":"not_found","reason":"missing"}
-
-This response is constant for both cases when user exists or not exists - by
-security reasons.
-
-Now let's share field ``name``. First, setup the ``public_fields`` configuration
-option. Remember, that this action requires administrator's privileges and
-the next command will ask for password for user `admin`, assuming that they are
-the server administrator::
-
-  curl -X PUT http://localhost:5984/_config/couch_http_auth/public_fields \
-       -H "Content-Type: application/json" \
-       -d '"name"' \
-       -u admin
-
-What have changed? Let's check Robert's document once again::
-
-  curl http://localhost:5984/_users/org.couchdb.user:robert
-
-.. code-block:: javascript
-
-  {"_id":"org.couchdb.user:robert","_rev":"6-869e2d3cbd8b081f9419f190438ecbe7","name":"robert"}
-
-Good news! Now we may read field ``name`` from *every user's document without
-need to be an administrator*. That's important note: don't publish sensitive
-information, especially without user's acknowledge - they may not like such
-actions from your side.
-
-
-==============
-Authorization
-==============
-
-Now that you have a few users who can log in, you probably want to set up some
-restrictions on what actions they can perform based on their identity and their
-roles.  Each database on a CouchDB server can contain its own set of
-authorization rules that specify which users are allowed to read and write
-documents, create design documents, and change certain database configuration
-parameters.  The authorization rules are set up by a server admin and can be
-modified at any time.
-
-Database authorization rules assign a user into one of two classes:
-
-- `members`, who are allowed to read all documents and create and modify any
-  document except for design documents.
-- `admins`, who can read and write all types of documents, modify which users
-  are members or admins, and set certain per-database configuration options.
-
-Note that a database admin is not the same as a server admin -- the actions
-of a database admin are restricted to a specific database.
-
-When a database is first created, there are no members or admins.  HTTP
-requests that have no authentication credentials or have credentials for a
-normal user are treated as members, and those with server admin credentials
-are treated as database admins.  To change the default permissions, you must
-create a :ref:`_security <api/db/security>` document in the database::
-
-  > curl -X PUT http://localhost:5984/mydatabase/_security \
-       -u anna:secret \
-       -H "Content-Type: application/json" \
-       -d '{"admins": { "names": [], "roles": [] }, "members": { "names": ["jan"], "roles": [] } }'
-
-The HTTP request to create the `_security` document must contain the
-credentials of a server admin.  CouchDB will respond with:
-
-.. code-block:: javascript
-
-  {"ok":true}
-
-The database is now secured against anonymous reads and writes::
-
-  > curl http://localhost:5984/mydatabase/
-
-.. code-block:: javascript
-
-  {"error":"unauthorized","reason":"You are not authorized to access this db."}
-
-You declared user "jan" as a member in this database, so he is able to read and
-write normal documents::
-
-  > curl -u jan:apple http://localhost:5984/mydatabase/
-
-.. code-block:: javascript
-
-  {"db_name":"mydatabase","doc_count":1,"doc_del_count":0,"update_seq":3,"purge_seq":0,
-  "compact_running":false,"disk_size":12376,"data_size":272,"instance_start_time":"1397672867731570",
-  "disk_format_version":6,"committed_update_seq":3}
-
-If Jan attempted to create a design doc, however, CouchDB would return a
-401 Unauthorized error because the username "jan" is not in the list of
-admin names and the `/_users/org.couchdb.user:jan` document doesn't contain
-a role that matches any of the declared admin roles.  If you want to promote
-Jan to an admin, you can update the security document to add `"jan"` to
-the `names` array under `admin`.  Keeping track of individual database
-admin usernames is tedious, though, so you would likely prefer to create a
-database admin role and assign that role to the `org.couchdb.user:jan` user
-document::
-
-  > curl -X PUT http://localhost:5984/mydatabase/_security \
-       -u anna:secret \
-       -H "Content-Type: application/json" \
-       -d '{"admins": { "names": [], "roles": ["mydatabase_admin"] }, "members": { "names": [], "roles": [] } }'
-
-See the :ref:`_security document reference page <api/db/security>` for
-additional details about specifying database members and admins.

http://git-wip-us.apache.org/repos/asf/couchdb/blob/cdac7299/share/doc/src/intro/tour.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro/tour.rst b/share/doc/src/intro/tour.rst
deleted file mode 100644
index 3e2de8c..0000000
--- a/share/doc/src/intro/tour.rst
+++ /dev/null
@@ -1,542 +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/tour:
-
-===============
-Getting Started
-===============
-
-In this document, we'll take a quick tour of CouchDB's features,
-familiarizing ourselves with Futon, the built-in administration interface.
-We'll create our first document and experiment with CouchDB views.
-
-
-All Systems Are Go!
-===================
-
-We'll have a very quick look at CouchDB's bare-bones Application Programming
-Interface (API) by using the command-line utility curl. Please note that this
-is not the only way of talking to CouchDB. We will show you plenty more
-throughout the rest of the documents. What's interesting about curl is that it
-gives you control over raw HTTP requests, and you can see exactly what is
-going on "underneath the hood" of your database.
-
-Make sure CouchDB is still running, and then do::
-
-  curl http://127.0.0.1:5984/
-
-This issues a GET request to your newly installed CouchDB instance.
-
-The reply should look something like:
-
-.. code-block:: javascript
-
-  {
-    "couchdb": "Welcome",
-    "uuid": "85fb71bf700c17267fef77535820e371",
-    "version": "1.4.0",
-    "vendor": {
-        "version": "1.4.0",
-        "name": "The Apache Software Foundation"
-    }
-  }
-
-Not all that spectacular. CouchDB is saying "hello" with the running version
-number.
-
-Next, we can get a list of databases::
-
-  curl -X GET http://127.0.0.1:5984/_all_dbs
-
-All we added to the previous request is the _all_dbs string.
-
-The response should look like::
-
-  ["_replicator","_users"]
-
-Oh, that's right, we didn't create any databases yet! All we see is an empty
-list.
-
-.. note::
-
-  The curl command issues GET requests by default. You can issue POST requests
-  using ``curl -X POST``. To make it easy to work with our terminal history,
-  we usually use the ``-X`` option even when issuing GET requests.
-  If we want to send a POST next time, all we have to change is the method.
-
-  HTTP does a bit more under the hood than you can see in the examples here.
-  If you're interested in every last detail that goes over the wire,
-  pass in the ``-v`` option (e.g., ``curl -vX GET``), which will show you
-  the server curl tries to connect to, the request headers it sends,
-  and response headers it receives back. Great for debugging!
-
-Let's create a database::
-
-  curl -X PUT http://127.0.0.1:5984/baseball
-
-CouchDB will reply with::
-
-  {"ok":true}
-
-Retrieving the list of databases again shows some useful results this time::
-
-  curl -X GET http://127.0.0.1:5984/_all_dbs
-
-::
-
-  ["baseball"]
-
-.. note::
-
-  We should mention JavaScript Object Notation (JSON) here,
-  the data format CouchDB speaks. JSON is a lightweight data interchange format
-  based on JavaScript syntax. Because JSON is natively compatible with
-  JavaScript, your web browser is an ideal client for CouchDB.
-
-  Brackets (``[]``) represent ordered lists, and curly braces (``{}``) represent
-  key/value dictionaries. Keys must be strings, delimited by quotes (``"``),
-  and values can be strings, numbers, booleans, lists,
-  or key/value dictionaries. For a more detailed description of JSON,
-  see Appendix E, JSON Primer.
-
-Let's create another database::
-
-  curl -X PUT http://127.0.0.1:5984/baseball
-
-CouchDB will reply with::
-
-  {"error":"file_exists","reason":"The database could not be created,
-  the file already exists."}
-
-We already have a database with that name, so CouchDB will respond with an
-error. Let's try again with a different database name::
-
-  curl -X PUT http://127.0.0.1:5984/plankton
-
-CouchDB will reply with::
-
-  {"ok":true}
-
-Retrieving the list of databases yet again shows some useful results::
-
-  curl -X GET http://127.0.0.1:5984/_all_dbs
-
-CouchDB will respond with::
-
-  ["baseball", "plankton"]
-
-To round things off, let's delete the second database::
-
-  curl -X DELETE http://127.0.0.1:5984/plankton
-
-CouchDB will reply with::
-
-  {"ok":true}
-
-The list of databases is now the same as it was before::
-
-  curl -X GET http://127.0.0.1:5984/_all_dbs
-
-CouchDB will respond with::
-
-  ["baseball"]
-
-For brevity, we'll skip working with documents, as the next section covers a
-different and potentially easier way of working with CouchDB that should
-provide experience with this. As we work through the example,
-keep in mind that "under the hood" everything is being done by the
-application exactly as you have been doing here manually.
-Everything is done using GET, PUT, POST, and DELETE with a URI.
-
-
-Welcome to Futon
-================
-
-After having seen CouchDB's raw API, let's get our feet wet by playing with
-Futon, the built-in administration interface. Futon provides full access to
-all of CouchDB's features and makes it easy to work with some of the more
-complex ideas involved. With Futon we can create and destroy databases; view
-and edit documents; compose and run MapReduce views; and trigger replication
-between databases.
-
-To load Futon in your browser, visit::
-
-  http://127.0.0.1:5984/_utils/
-
-If you're running version 0.9 or later, you should see something similar to
-:ref:`intro/tour-01`. In later documents, we'll focus on using CouchDB from
-server-side languages such as Ruby and Python. As such, this document is a great
-opportunity to showcase an example of natively serving up a dynamic web
-application using nothing more than CouchDB's integrated web server, something
-you may wish to do with your own applications.
-
-The first thing we should do with a fresh installation of CouchDB is run the
-test suite to verify that everything is working properly. This assures us
-that any problems we may run into aren't due to bothersome issues with our
-setup. By the same token, failures in the Futon test suite are a red flag,
-telling us to double-check our installation before attempting to use a
-potentially broken database server, saving us the confusion when nothing
-seems to be working quite like we expect!
-
-
-.. _intro/tour-01:
-
-.. figure:: ../../images/intro-tour-01.png
-   :align: center
-   :alt: The Futon welcome screen
-
-   Figure 1. The Futon welcome screen
-
-
-Some common network configurations cause the replication test to fail when
-accessed via the localhost address. You can fix this by accessing CouchDB via
-127.0.0.1, e.g. http://127.0.0.1:5984/_utils/.
-
-Navigate to the test suite by clicking "Test Suite" on the Futon sidebar,
-then click "run all" at the top to kick things off. :ref:`intro/tour-02`
-shows the Futon test suite running some tests.
-
-
-.. _intro/tour-02:
-
-.. figure:: ../../images/intro-tour-02.png
-   :align: center
-   :alt: The Futon test suite running some tests
-
-   Figure 2. The Futon test suite running some tests
-
-
-Because the test suite is run from the browser, not only does it test that
-CouchDB is functioning properly, it also verifies that your browser's
-connection to the database is properly configured, which can be very handy
-for diagnosing misbehaving proxies or other HTTP middleware.
-
-If the test suite has an inordinate number of failures,
-you'll need to see the troubleshooting section in Appendix D,
-Installing from Source for the next steps to fix your installation.
-
-Now that the test suite is finished, you've verified that your CouchDB
-installation is successful and you're ready to see what else Futon has to offer.
-
-
-Your First Database and Document
-================================
-
-Creating a database in Futon is simple. From the overview page,
-click "Create Database." When asked for a name, enter hello-world and click
-the Create button.
-
-After your database has been created, Futon will display a list of all its
-documents. This list will start out empty (:ref:`intro/tour-03`), so let's
-create our first document. Click the "New Document" link and then the Create
-button in the pop up. Make sure to leave the document ID blank,
-and CouchDB will generate a UUID for you.
-
-For demoing purposes, having CouchDB assign a UUID is fine. When you write
-your first programs, we recommend assigning your own UUIDs. If your rely on
-the server to generate the UUID and you end up making two POST requests
-because the first POST request bombed out, you might generate two docs and
-never find out about the first one because only the second one will be
-reported back. Generating your own UUIDs makes sure that you'll never end up
-with duplicate documents.
-
-Futon will display the newly created document, with its _id and _rev as the
-only fields. To create a new field, click the "Add Field" button. We'll call
-the new field hello. Click the green check icon (or hit the Enter key) to
-finalize creating the hello field. Double-click the hello field's value
-(default null) to edit it.
-
-You can experiment with other JSON values; e.g., ``[1, 2, "c"]`` or
-``{"foo": "bar"}``. Once you've entered your values into the document,
-make a note of its ``_rev`` attribute and click "Save Document." The result
-should look like :ref:`intro/tour-04`.
-
-
-.. _intro/tour-03:
-
-.. figure:: ../../images/intro-tour-03.png
-   :align: center
-   :alt: An empty database in Futon
-
-   Figure 3. An empty database in Futon
-
-
-.. _intro/tour-04:
-
-.. figure:: ../../images/intro-tour-04.png
-   :align: center
-   :alt: A "hello world" document in Futon
-
-   Figure 4. A "hello world" document in Futon
-
-
-You'll notice that the document's _rev has changed. We'll go into more detail
-about this in later documents, but for now, the important thing to note is
-that _rev acts like a safety feature when saving a document. As long as you
-and CouchDB agree on the most recent _rev of a document, you can successfully 
-save your changes.
-
-Futon also provides a way to display the underlying JSON data,
-which can be more compact and easier to read, depending on what sort of data
-you are dealing with. To see the JSON version of our "hello world" document,
-click the Source tab. The result should look like :ref:`intro/tour-05`.
-
-
-.. _intro/tour-05:
-
-.. figure:: ../../images/intro-tour-05.png
-   :align: center
-   :alt: The JSON source of a "hello world" document in Futon
-
-   Figure 5. The JSON source of a "hello world" document in Futon
-
-
-Running a Query Using MapReduce
-===============================
-
-Traditional relational databases allow you to run any queries you like as
-long as your data is structured correctly. In contrast,
-CouchDB uses predefined map and reduce functions in a style known as
-MapReduce. These functions provide great flexibility because they can adapt
-to variations in document structure, and indexes for each document can be
-computed independently and in parallel. The combination of a map and a reduce
-function is called a view in CouchDB terminology.
-
-For experienced relational database programmers, MapReduce can take some
-getting used to. Rather than declaring which rows from which tables to
-include in a result set and depending on the database to determine the most
-efficient way to run the query, reduce queries are based on simple range
-requests against the indexes generated by your map functions.
-
-Map functions are called once with each document as the argument.
-The function can choose to skip the document altogether or emit one or more
-view rows as key/value pairs. Map functions may not depend on any information
-outside of the document. This independence is what allows CouchDB views to be
-generated incrementally and in parallel.
-
-CouchDB views are stored as rows that are kept sorted by key. This makes
-retrieving data from a range of keys efficient even when there are thousands
-or millions of rows. When writing CouchDB map functions,
-your primary goal is to build an index that stores related data under nearby
-keys.
-
-Before we can run an example MapReduce view, we'll need some data to run it
-on. We'll create documents carrying the price of various supermarket items as
-found at different shops. Let's create documents for apples, oranges,
-and bananas. (Allow CouchDB to generate the _id and _rev fields.) Use Futon
-to create documents that have a final JSON structure that looks like this:
-
-.. code-block:: javascript
-
-  {
-   "_id": "00a271787f89c0ef2e10e88a0c0001f4",
-   "_rev": "1-2628a75ac8c3abfffc8f6e30c9949fd6",
-   "item": "apple",
-   "prices": {
-       "Fresh Mart": 1.59,
-       "Price Max": 5.99,
-       "Apples Express": 0.79
-   }
-  }
-
-This document should look like :ref:`intro/tour-06` when entered into Futon.
-
-
-.. _intro/tour-06:
-
-.. figure:: ../../images/intro-tour-06.png
-   :align: center
-   :alt: An example document with apple prices in Futon
-
-   Figure 6. An example document with apple prices in Futon
-
-
-OK, now that that's done, let's create the document for oranges:
-
-.. code-block:: javascript
-
-  {
-   "_id": "00a271787f89c0ef2e10e88a0c0003f0",
-   "_rev": "1-e9680c5d9a688b4ff8dd68549e8e072c",
-   "item": "orange",
-   "prices": {
-       "Fresh Mart": 1.99,
-       "Price Max": 3.19,
-       "Citrus Circus": 1.09
-   }
-  }
-
-And finally, the document for bananas:
-
-.. code-block:: javascript
-
-  {
-   "_id": "00a271787f89c0ef2e10e88a0c00048b",
-   "_rev": "1-60e25d93dc12884676d037400a6fa189",
-   "item": "banana",
-   "prices": {
-       "Fresh Mart": 1.99,
-       "Price Max": 0.79,
-       "Banana Montana": 4.22
-   }
-  }
-
-Imagine we're catering a big luncheon, but the client is very price-sensitive.
-To find the lowest prices, we're going to create our first view,
-which shows each fruit sorted by price. Click "hello-world" to return to the
-hello-world overview, and then from the "select view" menu choose "Temporary
-view…" to create a new view.
-
-
-.. figure:: ../../images/intro-tour-07.png
-   :align: center
-   :alt: A temporary view in Futon
-
-   Figure 7. A temporary view in Futon
-
-
-Edit the map function, on the left, so that it looks like the following:
-
-.. code-block:: javascript
-
-  function(doc) {
-    var shop, price, value;
-    if (doc.item && doc.prices) {
-        for (shop in doc.prices) {
-            price = doc.prices[shop];
-            value = [doc.item, shop];
-            emit(price, value);
-        }
-    }
-  }
-
-This is a JavaScript function that CouchDB runs for each of our documents as
-it computes the view. We'll leave the reduce function blank for the time being.
-
-Click "Run" and you should see result rows like in :ref:`intro/tour-08`,
-with the various items sorted by price. This map function could be even more
-useful if it grouped the items by type so that all the prices for bananas were
-next to each other in the result set. CouchDB's key sorting system allows any
-valid JSON object as a key. In this case, we'll emit an array of [item, price]
-so that CouchDB groups by item type and price.
-
-
-.. _intro/tour-08:
-
-.. figure:: ../../images/intro-tour-08.png
-   :align: center
-   :alt: The results of running a view in Futon
-
-   Figure 8. The results of running a view in Futon
-
-
-Let's modify the view function so that it looks like this:
-
-.. code-block:: javascript
-
-  function(doc) {
-    var shop, price, key;
-    if (doc.item && doc.prices) {
-        for (shop in doc.prices) {
-            price = doc.prices[shop];
-            key = [doc.item, price];
-            emit(key, shop);
-        }
-    }
-  }
-
-Here, we first check that the document has the fields we want to use. CouchDB
-recovers gracefully from a few isolated map function failures,
-but when a map function fails regularly (due to a missing required field or
-other JavaScript exception), CouchDB shuts off its indexing to prevent any
-further resource usage. For this reason, it's important to check for the
-existence of any fields before you use them. In this case,
-our map function will skip the first "hello world" document we created
-without emitting any rows or encountering any errors. The result of this
-query should look like :ref:`intro/tour-09`.
-
-
-.. _intro/tour-09:
-
-.. figure:: ../../images/intro-tour-09.png
-   :align: center
-   :alt: The results of running a view after grouping by item type and price
-
-   Figure 9. The results of running a view after grouping by item type and price
-
-
-Once we know we've got a document with an item type and some prices,
-we iterate over the item's prices and emit key/values pairs. The key is an
-array of the item and the price, and forms the basis for CouchDB's sorted
-index. In this case, the value is the name of the shop where the item can be
-found for the listed price.
-
-View rows are sorted by their keys -- in this example, first by item,
-then by price. This method of complex sorting is at the heart of creating
-useful indexes with CouchDB.
-
-MapReduce can be challenging, especially if you've spent years working with
-relational databases. The important things to keep in mind are that map
-functions give you an opportunity to sort your data using any key you choose,
-and that CouchDB's design is focused on providing fast,
-efficient access to data within a range of keys.
-
-
-Triggering Replication
-======================
-
-Futon can trigger replication between two local databases,
-between a local and remote database, or even between two remote databases.
-We'll show you how to replicate data from one local database to another,
-which is a simple way of making backups of your databases as we're working
-through the examples.
-
-First we'll need to create an empty database to be the target of replication.
-Return to the overview and create a database called hello-replication.
-Now click "Replicator" in the sidebar and choose hello-world as the source
-and hello-replication as the target. Click "Replicate" to replicate your
-database. The result should look something like :ref:`intro/tour-10`.
-
-
-.. _intro/tour-10:
-
-.. figure:: ../../images/intro-tour-10.png
-   :align: center
-   :alt: Running database replication in Futon
-
-   Figure 10. Running database replication in Futon
-
-
-.. note::
-
-  For larger databases, replication can take much longer. It is important to
-  leave the browser window open while replication is taking place.
-  As an alternative, you can trigger replication via curl or some other HTTP
-  client that can handle long-running connections. If your client closes the
-  connection before replication finishes, you'll have to retrigger it.
-  Luckily, CouchDB's replication can take over from where it left off
-  instead of starting from scratch.
-
-
-Wrapping Up
-===========
-
-Now that you've seen most of Futon's features, you'll be prepared to dive in
-and inspect your data as we build our example application in the next few
-documents. Futon's pure JavaScript approach to managing CouchDB shows how it's
-possible to build a fully featured web application using only CouchDB's HTTP
-API and integrated web server.
-
-But before we get there, we'll have another look at CouchDB's HTTP API -- now
-with a magnifying glass. Let's curl up on the couch and relax.

http://git-wip-us.apache.org/repos/asf/couchdb/blob/cdac7299/share/doc/src/intro/why.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro/why.rst b/share/doc/src/intro/why.rst
deleted file mode 100644
index 8a76c48..0000000
--- a/share/doc/src/intro/why.rst
+++ /dev/null
@@ -1,315 +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/why:
-
-============
-Why CouchDB?
-============
-
-Apache CouchDB is one of a new breed of database management systems.
-This topic explains why there's a need for new systems as well as the
-motivations behind building CouchDB.
-
-As CouchDB developers, we're naturally very excited to be using CouchDB.
-In this topic we'll share with you the reasons for our enthusiasm.
-We'll show you how CouchDB's schema-free document model is a better fit
-for common applications, how the built-in query engine is a powerful way
-to use and process your data, and how CouchDB's design lends itself
-to modularization and scalability.
-
-
-Relax
-=====
-
-If there's one word to describe CouchDB, it is *relax*. It is the byline 
-to CouchDB's official logo and when you start CouchDB, you see::
-
-  Apache CouchDB has started. Time to relax.
-
-Why is relaxation important? Developer productivity roughly doubled in the
-last five years. The chief reason for the boost is more powerful tools that
-are easier to use. Take Ruby on Rails as an example. It is an infinitely
-complex framework, but it's easy to get started with. Rails is a success
-story because of the core design focus on ease of use. This is one reason why
-CouchDB is relaxing: learning CouchDB and understanding its core concepts
-should feel natural to most everybody who has been doing any work on the Web.
-And it is still pretty easy to explain to non-technical people.
-
-Getting out of the way when creative people try to build specialized
-solutions is in itself a core feature and one thing that CouchDB aims to get
-right. We found existing tools too cumbersome to work with during development
-or in production, and decided to focus on making CouchDB easy, even a pleasure,
-to use.
-
-Another area of relaxation for CouchDB users is the production setting.
-If you have a live running application, CouchDB again goes out of its way
-to avoid troubling you. Its internal architecture is fault-tolerant,
-and failures occur in a controlled environment and are dealt with gracefully.
-Single problems do not cascade through an entire server system but stay
-isolated in single requests.
-
-CouchDB's core concepts are simple (yet powerful) and well understood.
-Operations teams (if you have a team; otherwise, that's you) do not have to
-fear random behavior and untraceable errors. If anything should go wrong,
-you can easily find out what the problem is, but these situations are rare.
-
-CouchDB is also designed to handle varying traffic gracefully. For instance,
-if a website is experiencing a sudden spike in traffic, CouchDB will generally
-absorb a lot of concurrent requests without falling over. It may take a little
-more time for each request, but they all get answered. When the spike is over,
-CouchDB will work with regular speed again.
-
-The third area of relaxation is growing and shrinking the underlying hardware
-of your application. This is commonly referred to as scaling. CouchDB enforces
-a set of limits on the programmer. On first look, CouchDB might seem
-inflexible, but some features are left out by design for the simple reason
-that if CouchDB supported them, it would allow a programmer to create
-applications that couldn't deal with scaling up or down.
-
-.. note::
-  CouchDB doesn't let you do things that would get you in trouble later on.
-  This sometimes means you'll have to unlearn best practices you might have
-  picked up in your current or past work.
-
-
-A Different Way to Model Your Data
-==================================
-
-We believe that CouchDB will drastically change the way you build
-document-based applications. CouchDB combines an intuitive document storage
-model with a powerful query engine in a way that's so simple you'll probably
-be tempted to ask, “Why has no one built something like this before?”
-
-    Django may be built for the Web, but CouchDB is built of the Web. I've
-    never seen software that so completely embraces the philosophies behind
-    HTTP. CouchDB makes Django look old-school in the same way that Django
-    makes ASP look outdated.
-
-    -- Jacob Kaplan-Moss, Django developer
-
-CouchDB's design borrows heavily from web architecture and the concepts of
-resources, methods, and representations. It augments this with powerful ways
-to query, map, combine, and filter your data. Add fault tolerance, extreme
-scalability, and incremental replication, and CouchDB defines a sweet spot
-for document databases.
-
-
-A Better Fit for Common Applications
-====================================
-
-We write software to improve our lives and the lives of others. Usually this
-involves taking some mundane information such as contacts, invoices,
-or receipts and manipulating it using a computer application. CouchDB is a
-great fit for common applications like this because it embraces the natural
-idea of evolving, self-contained documents as the very core of its data model.
-
-
-Self-Contained Data
--------------------
-
-An invoice contains all the pertinent information about a single transaction
-the seller, the buyer, the date, and a list of the items or services sold.
-As shown in :ref:`intro/why-01`, there's no abstract reference on this
-piece of paper that points to some other piece of paper with the seller's
-name and address. Accountants appreciate the simplicity of having everything
-in one place. And given the choice, programmers appreciate that, too.
-
-
-.. _intro/why-01:
-
-.. figure:: ../../images/intro-why-01.png
-   :align: center
-   :alt: Self-contained documents
-
-   Figure 1. Self-contained documents
-
-
-Yet using references is exactly how we model our data in a relational
-database! Each invoice is stored in a table as a row that refers to other
-rows in other tables one row for seller information, one for the buyer,
-one row for each item billed, and more rows still to describe the item
-details, manufacturer details, and so on and so forth.
-
-This isn't meant as a detraction of the relational model, which is widely
-applicable and extremely useful for a number of reasons. Hopefully, though, it
-illustrates the point that sometimes your model may not “fit” your data
-in the way it occurs in the real world.
-
-Let's take a look at the humble contact database to illustrate a different
-way of modeling data, one that more closely “fits” its real-world counterpart
--- a pile of business cards. Much like our invoice example, a business card
-contains all the important information, right there on the cardstock.
-We call this “self-contained” data, and it's an important concept
-in understanding document databases like CouchDB.
-
-
-Syntax and Semantics
---------------------
-
-Most business cards contain roughly the same information -- someone's identity,
-an affiliation, and some contact information. While the exact form of this
-information can vary between business cards, the general information being
-conveyed remains the same, and we're easily able to recognize it as a
-business card. In this sense, we can describe a business card as a *real-world
-document*.
-
-Jan's business card might contain a phone number but no fax number,
-whereas J. Chris's business card contains both a phone and a fax number. Jan
-does not have to make his lack of a fax machine explicit by writing something
-as ridiculous as “Fax: None” on the business card. Instead, simply omitting
-a fax number implies that he doesn't have one.
-
-We can see that real-world documents of the same type, such as business cards,
-tend to be very similar in *semantics* -- the sort of information they carry,
-but can vary hugely in *syntax*, or how that information is structured. As human
-beings, we're naturally comfortable dealing with this kind of variation.
-
-While a traditional relational database requires you to model your data
-*up front*, CouchDB's schema-free design unburdens you with a powerful way to
-aggregate your data *after the fact*, just like we do with real-world
-documents. We'll look in depth at how to design applications with this
-underlying storage paradigm.
-
-
-Building Blocks for Larger Systems
-==================================
-
-CouchDB is a storage system useful on its own. You can build many applications
-with the tools CouchDB gives you. But CouchDB is designed with a bigger picture
-in mind. Its components can be used as building blocks that solve storage
-problems in slightly different ways for larger and more complex systems.
-
-Whether you need a system that's crazy fast but isn't too concerned with
-reliability (think logging), or one that guarantees storage in two or more
-physically separated locations for reliability, but you're willing to take a
-performance hit, CouchDB lets you build these systems.
-
-There are a multitude of knobs you could turn to make a system work better in
-one area, but you'll affect another area when doing so. One example would be
-the CAP theorem discussed in :ref:`intro/consistency`. To give you an idea of other
-things that affect storage systems, see :ref:`Figure 2 <intro/why-figure-02>`
-and :ref:`Figure 3 <intro/why-figure-03>`.
-
-By reducing latency for a given system (and that is true not only for storage
-systems), you affect concurrency and throughput capabilities.
-
-
-.. _intro/why-figure-02:
-
-.. figure:: ../../images/intro-why-02.png
-   :align: center
-   :alt: Throughput, latency, or concurrency
-
-   Figure 2. Throughput, latency, or concurrency
-
-
-.. _intro/why-figure-03:
-
-.. figure:: ../../images/intro-why-03.png
-   :align: center
-   :alt: Scaling: read requests, write requests, or data
-
-   Figure 3. Scaling: read requests, write requests, or data
-
-
-When you want to scale out, there are three distinct issues to deal with:
-scaling read requests, write requests, and data. Orthogonal to all three and
-to the items shown in :ref:`Figure 2 <intro/why-figure-02>` and :ref:`Figure 3
-<intro/why-figure-03>` are many more attributes like reliability or simplicity.
-You can draw many of these graphs that show how different features or attributes
-pull into different directions and thus shape the system they describe.
-
-CouchDB is very flexible and gives you enough building blocks to create a
-system shaped to suit your exact problem. That's not saying that CouchDB can
-be bent to solve any problem -- CouchDB is no silver bullet -- but in the
-area of data storage, it can get you a long way.
-
-
-CouchDB Replication
-===================
-
-CouchDB replication is one of these building blocks. Its fundamental function
-is to synchronize two or more CouchDB databases. This may sound simple,
-but the simplicity is key to allowing replication to solve a number of
-problems: reliably synchronize databases between multiple machines for
-redundant data storage; distribute data to a cluster of CouchDB instances
-that share a subset of the total number of requests that hit the cluster
-(load balancing); and distribute data between physically distant locations,
-such as one office in New York and another in Tokyo.
-
-CouchDB replication uses the same REST API all clients use. HTTP is
-ubiquitous and well understood. Replication works incrementally; that is,
-if during replication anything goes wrong, like dropping your network
-connection, it will pick up where it left off the next time it runs. It also
-only transfers data that is needed to synchronize databases.
-
-A core assumption CouchDB makes is that things can go wrong,
-like network connection troubles, and it is designed for graceful error
-recovery instead of assuming all will be well. The replication system's
-incremental design shows that best. The ideas behind “things that can go
-wrong” are embodied in the `Fallacies of Distributed Computing`_:
-
-- The network is reliable.
-- Latency is zero.
-- Bandwidth is infinite.
-- The network is secure.
-- Topology doesn't change.
-- There is one administrator.
-- Transport cost is zero.
-- The network is homogeneous.
-
-Existing tools often try to hide the fact that there is a network and that
-any or all of the previous conditions don't exist for a particular system.
-This usually results in fatal error scenarios when something finally goes
-wrong. In contrast, CouchDB doesn't try to hide the network; it just handles
-errors gracefully and lets you know when actions on your end are required.
-
-.. _Fallacies of Distributed Computing: http://en.wikipedia.org/wiki/Fallacies_of_Distributed_Computing
-
-
-Local Data Is King
-==================
-
-CouchDB takes quite a few lessons learned from the Web,
-but there is one thing that could be improved about the Web: latency.
-Whenever you have to wait for an application to respond or a website to
-render, you almost always wait for a network connection that isn't as fast as
-you want it at that point. Waiting a few seconds instead of milliseconds
-greatly affects user experience and thus user satisfaction.
-
-What do you do when you are offline? This happens all the time -- your DSL or
-cable provider has issues, or your iPhone, G1, or Blackberry has no bars,
-and no connectivity means no way to get to your data.
-
-CouchDB can solve this scenario as well, and this is where scaling is
-important again. This time it is scaling down. Imagine CouchDB installed on
-phones and other mobile devices that can synchronize data with centrally
-hosted CouchDBs when they are on a network. The synchronization is not bound
-by user interface constraints like subsecond response times. It is easier to
-tune for high bandwidth and higher latency than for low bandwidth and very
-low latency. Mobile applications can then use the local CouchDB to fetch
-data, and since no remote networking is required for that,
-latency is low by default.
-
-Can you really use CouchDB on a phone? Erlang, CouchDB's implementation
-language has been designed to run on embedded devices magnitudes smaller and
-less powerful than today's phones.
-
-
-Wrapping Up
-===========
-
-The next document :ref:`intro/consistency` further explores the distributed nature 
-of CouchDB. We should have given you enough bites to whet your interest. 
-Let's go!


Mime
View raw message