Permalink
Newer
Older
100644 126 lines (75 sloc) 5.8 KB
1
## cloudant-dbcore
2
3
### Overview
4
5
Cloudant-dbcore is a highly available, fault-tolerant, clustered, fully api-compliant version of [Apache CouchDB][1]. While it appears to the end-user as one CouchDB instance, it is in fact one or more nodes in an elastic cluster, acting in concert to store and retrieve documents, index and serve views, and serve CouchApps. Dbcore has been developed and is continually maintained by [Cloudant][2] who offer hosted CouchDB as a service.
6
7
Clusters behave according to concepts outlined in [Amazon's Dynamo paper][4], namely that each node can accept requests, data is placed on partitions based on a consistent hashing algorithm, and quorum protocols are for read/write operations.
8
9
### Contents
10
11
* README.md this file
12
* LICENSE open-source license governing dbcore
13
14
### Getting Started
15
16
#### Prerequisites
17
18
Cloudant Core has the same dependencies as CouchDB:
19
20
* Erlang (R13B03 or higher)
21
* ICU (4.2 is preferable)
22
* Spidermonkey (1.9.2 preferable, [https://launchpad.net/~commonjs/+archive/ppa/][6])
23
* LibCurl
24
* OpenSSL
25
* make
26
* Python (2.4 or higher)
27
28
#### Installing prerequisites on Ubuntu
29
30
sudo apt-get install erlang libicu42 libcurl-openssl-dev
31
32
To install Spidermonkey 1.9.2 from PPA:
33
34
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 74EE6429
35
sudo echo "deb http://ppa.launchpad.net/commonjs/ppa/ubuntu karmic main" >> /etc/apt/sources.list
36
sudo apt-get update
37
sudo apt-get install libmozjs-1.9.2 libmozjs-1.9.2-dev
38
39
#### Installing prerequisites on Mac OS X with (Homebrew)[7]
40
41
brew install erlang icu4c spidermonkey
42
43
#### Building and installing dbcore
44
45
`$CLOUDANT_SRC` is the directory holding your downloaded source files, while `$CLOUDANT_PREFIX` is the prefix to which the software is installed (defaults to `/opt`):
46
47
$ cd $CLOUDANT_SRC
48
$ ./configure -p $CLOUDANT_PREFIX
49
$ make
50
$ sudo make install
51
52
#### Starting dbcore
53
54
$ $CLOUDANT_PREFIX/dbcore/bin/dbcore
55
56
Now, visit http://localhost:5984/_utils in a browser to verify the CouchDB node is operational.
57
58
Note: see the rel/sv/README file for information on using runit to stop/start dbcore.
59
60
#### Joining a new node to the cluster
61
62
First, dbcore listens on two ports. Defaults and explanations:
63
64
* 5984 - front door, cluster-aware port, appears as a standalone CouchDB.
65
* 5986 - back door, single-node port, used for admin functions
66
67
Next, once the first node is started, and assuming its hostname is 'node1_host' start dbcore on another node, with hostname 'node2_host'. Once it's started successfully, on node1_host, join the new node:
68
$ curl -X PUT http://localhost:5986/nodes/dbcore@node2_host -d {}
69
70
To verify the two-node cluster has been linked properly, on either node, try:
71
$ curl http://locahost:5984/_membership
72
73
You should see something similar to this:
74
{"all_nodes":["dbcore@node1_host","dbcore@node2_host"],"cluster_nodes":["dbcore@node1_host","dbcore@node2_host"]}
75
76
#### Now What?
77
78
If the above steps were successful, you should have a running dbcore cluster that looks just like a standalone CouchDB. You may interact with it the same way you would a standalone CouchDB, via the HTTP REST interface.
79
80
Because every node can handle requests equally, you may want to put a load balancer in front of the cluster and set up a round-robin strategy for distributing incoming requests across all of your cluster's nodes.
81
82
##### Create a database:
83
84
curl -X PUT http://loadbalancer:5984/test_db
85
86
Also note that 'q' and 'n' are query string arguments that may be specified. These are Cloudant-specific options, and their values and defaults are discussed in the Configuration section below. Ex: &q=12 or &n=4.
87
88
##### Create a document:
89
90
curl -X PUT http://loadbalancer:5984/test_db/doc_1 -d '{"a":1,"b":2}'
91
92
You may also provide 'r' and 'w' on the GET and PUT/POST document operations respectively. Their values and defaults are discussed in the Configuration section below. Ex: &r=3 for high consistency reads, or &w=1 for higher throughput writes.
93
94
##### Check out Futon, CouchDB's web UI:
95
96
* [http://loadbalancer:5984/_utils][5]
97
98
### Configuration
99
100
#### Cluster constants
101
102
_Q_ - number of partitions per database. Q is specified in the default.ini file, but may be provided as a URL parameter when creating a database. Default value is 8, query parameter is &q=12 or similar.
103
104
_N_ - replication constant. N defaults to 3, but can vary by database just as Q can vary. N copies of each document will be written to the data store, on N different nodes.
105
106
_R_ - read quorum constant. N writes have occurred for each document, as noted above. When reads are requested, N reads are sent to the N nodes that store the particular document. The system will return to the requesting client with the document when R successful reads have returned, and agree on versioning. R defaults to 2. Lower R values often result in faster reads at the expense of consistency. Higher R values usually result in slower reads, but more consistent, or agreed-upon data values returning.
107
108
_W_ - write quorum constant. When writing the N copies, the data store will respond to the write client after W successful writes have completed. The remaining N-W writes are still being attempted in the background, but the client receives a 201 Created status and can resume execution. W defaults to 2. Lower W values mean more write throughput, and higher W values mean more data durability.
109
110
### Contact
111
112
Cloudant folks are usually hanging out in IRC. Freenode, channel #cloudant. We may also be reached:
113
114
* [http://cloudant.com][2]
115
* [info@cloudant.com][3]
116
117
----
118
119
[1]: http://couchdb.apache.org
120
[2]: http://cloudant.com
121
[3]: mailto:info@cloudant.com
122
[4]: http://www.allthingsdistributed.com/2007/10/amazons_dynamo.html
123
[5]: http://loadbalancer:5984/_utils
124
[6]: https://launchpad.net/~commonjs/+archive/ppa/
125
[7]: http://mxcl.github.com/homebrew/