Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 297 lines (206 sloc) 9.194 kb
f3a76f9 @beerriot mention basic-setup.txt in README
beerriot authored
1 Welcome to Riak.
2 ================
db66c33 import
justin authored
3
09eeb4c README updates for Erlang version
Grant Schofield authored
4 Date: 2010-06-09 10:06:44 CDT
db66c33 import
justin authored
5
6
7
7e4eca0 @dizzyd Revamping README via org; also updating for new build stuff
dizzyd authored
8 Table of Contents
9 =================
10 1 Overview
11 2 Quick Start
12 2.1 Building Riak
13 2.2 Starting Riak
14 2.3 Connecting a client to Riak
2e029d9 @argv0 re-render README from README.org
argv0 authored
15 2.4 Clients for Other Languages
60706d2 @dizzyd Updating README w/ server management section
dizzyd authored
16 3 Server Management
17 3.1 Configuration
18 3.2 Server Control
19 3.2.1 bin/riak
20 3.2.2 bin/riak-admin
db66c33 import
justin authored
21
22
7e4eca0 @dizzyd Revamping README via org; also updating for new build stuff
dizzyd authored
23 1 Overview
24 ~~~~~~~~~~~
25 Riak is a distributed, decentralized data storage system.
26
27 Below, you will find the "quick start" directions for setting up and
28 using Riak. For more information, browse the following files:
29
30 * README: this file
31 * TODO: a list of improvements planned for Riak
32 * LICENSE: the license under which Riak is released
33 * apps/ the source tree for Riak and all its dependencies
34 * doc/
8056115 @beerriot re-export README.org
beerriot authored
35 - admin.org: Riak Administration Guide
7e4eca0 @dizzyd Revamping README via org; also updating for new build stuff
dizzyd authored
36 - architecture.txt: details about the underlying design of Riak
8056115 @beerriot re-export README.org
beerriot authored
37 - basic-client.txt: slightly more detail on using Riak
38 - basic-setup.txt: slightly more detail on setting up Riak
39 - basic-mapreduce.txt: introduction to map/reduce on Riak
40 - js-mapreduce.org: using Javascript with Riak map/reduce
41 - man/riak.1.gz: manual page for the riak(1) command
42 - man/riak-admin.1.gz manual page for the riak-admin(1) command
43 - raw-http-howto.txt: using the Riak HTTP interface
44
db66c33 import
justin authored
45
46
7e4eca0 @dizzyd Revamping README via org; also updating for new build stuff
dizzyd authored
47 2 Quick Start
48 ~~~~~~~~~~~~~~
db66c33 import
justin authored
49
3f10857 @dizzyd Fix minor typo and ensure wrap at 80 cols
dizzyd authored
50 This section assumes that you have copy of the Riak source tree. To get
51 started, you need to:
7e4eca0 @dizzyd Revamping README via org; also updating for new build stuff
dizzyd authored
52 1. Build Riak
53 2. Start the Riak server
54 3. Connect a client and store/fetch data
db66c33 import
justin authored
55
7e4eca0 @dizzyd Revamping README via org; also updating for new build stuff
dizzyd authored
56 2.1 Building Riak
57 ==================
db66c33 import
justin authored
58
e8125be @jaredmorrow Update dependency on OTP R14B02 and change documentation accordingly
jaredmorrow authored
59 Assuming you have a working Erlang (R14B02 or later) installation,
7e4eca0 @dizzyd Revamping README via org; also updating for new build stuff
dizzyd authored
60 building Riak should be as simple as:
db66c33 import
justin authored
61
09eeb4c README updates for Erlang version
Grant Schofield authored
62
f3a76f9 @beerriot mention basic-setup.txt in README
beerriot authored
63 $ cd $RIAK
acdd472 Update README to use IP addresses in examples. (Bugzilla #65)
Rusty Klophaus authored
64 $ make rel
65
7e4eca0 @dizzyd Revamping README via org; also updating for new build stuff
dizzyd authored
66 2.2 Starting Riak
67 ==================
db66c33 import
justin authored
68
3f10857 @dizzyd Fix minor typo and ensure wrap at 80 cols
dizzyd authored
69 Once you have successfully built Riak, you can start the server with the
70 following commands:
db66c33 import
justin authored
71
09eeb4c README updates for Erlang version
Grant Schofield authored
72
f3a76f9 @beerriot mention basic-setup.txt in README
beerriot authored
73 $ cd $RIAK/rel/riak
74 $ bin/riak start
75
7e4eca0 @dizzyd Revamping README via org; also updating for new build stuff
dizzyd authored
76 Now, verify that the server started up cleanly and is working:
db66c33 import
justin authored
77
7e4eca0 @dizzyd Revamping README via org; also updating for new build stuff
dizzyd authored
78 $ bin/riak-admin test
db66c33 import
justin authored
79
3f10857 @dizzyd Fix minor typo and ensure wrap at 80 cols
dizzyd authored
80 Note that the $RIAK/rel/riak directory is a complete, self-contained instance
81 of Riak and Erlang. It is strongly suggested that you move this directory
82 outside the source tree if you plan to run a production instance.
60706d2 @dizzyd Updating README w/ server management section
dizzyd authored
83
7e4eca0 @dizzyd Revamping README via org; also updating for new build stuff
dizzyd authored
84 2.3 Connecting a client to Riak
85 ================================
db66c33 import
justin authored
86
3f10857 @dizzyd Fix minor typo and ensure wrap at 80 cols
dizzyd authored
87 Now that you have a functional server, let's try storing some data in
88 it. First, start up a erlang node using our embedded version of erlang:
db66c33 import
justin authored
89
09eeb4c README updates for Erlang version
Grant Schofield authored
90
acdd472 Update README to use IP addresses in examples. (Bugzilla #65)
Rusty Klophaus authored
91 $ erts-<vsn>/bin/erl -name riaktest@127.0.0.1 -setcookie riak
f3a76f9 @beerriot mention basic-setup.txt in README
beerriot authored
92
93 Eshell V5.7.4 (abort with ^G)
acdd472 Update README to use IP addresses in examples. (Bugzilla #65)
Rusty Klophaus authored
94 (riaktest@127.0.0.1)1>
f3a76f9 @beerriot mention basic-setup.txt in README
beerriot authored
95
8056115 @beerriot re-export README.org
beerriot authored
96 Now construct the node name of Riak server and make sure we can talk to it:
75a7053 Updated admin.org, added man files
Grant Schofield authored
97
09eeb4c README updates for Erlang version
Grant Schofield authored
98
acdd472 Update README to use IP addresses in examples. (Bugzilla #65)
Rusty Klophaus authored
99 (riaktest@127.0.0.1)4> RiakNode = 'riak@127.0.0.1'.
f3a76f9 @beerriot mention basic-setup.txt in README
beerriot authored
100
acdd472 Update README to use IP addresses in examples. (Bugzilla #65)
Rusty Klophaus authored
101 (riaktest@127.0.0.1)2> net_adm:ping(RiakNode).
f3a76f9 @beerriot mention basic-setup.txt in README
beerriot authored
102 pong
acdd472 Update README to use IP addresses in examples. (Bugzilla #65)
Rusty Klophaus authored
103 (riaktest@127.0.0.1)2>
04de242 @dizzyd Updating README
dizzyd authored
104
105 We are now ready to start the Riak client:
106
f3a76f9 @beerriot mention basic-setup.txt in README
beerriot authored
107
09eeb4c README updates for Erlang version
Grant Schofield authored
108 (riaktest@127.0.0.1)2> {ok, C} = riak:client_connect(RiakNode).
109 {ok,{riak_client,'riak@127.0.0.1',<<4,136,81,151>>}}
04de242 @dizzyd Updating README
dizzyd authored
110
8056115 @beerriot re-export README.org
beerriot authored
111 Let's create a shopping list for bread at /groceries/mine:
75a7053 Updated admin.org, added man files
Grant Schofield authored
112
09eeb4c README updates for Erlang version
Grant Schofield authored
113
114 (riaktest@127.0.0.1)6> O0 = riak_object:new(<<"groceries">>, <<"mine">>, ["bread"]).
115 O0 = riak_object:new(<<"groceries">>, <<"mine">>, ["bread"]).
116 {r_object,<<"groceries">>,<<"mine">>,
f3a76f9 @beerriot mention basic-setup.txt in README
beerriot authored
117 [{r_content,{dict,0,16,16,8,80,48,
118 {[],[],[],[],[],[],[],[],[],[],[],[],[],[],...},
119 {{[],[],[],[],[],[],[],[],[],[],[],[],...}}},
120 ["bread"]}],
121 [],
122 {dict,1,16,16,8,80,48,
123 {[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],...},
124 {{[],[],[],[],[],[],[],[],[],[],[],[],[],...}}},
125 undefined}
126
acdd472 Update README to use IP addresses in examples. (Bugzilla #65)
Rusty Klophaus authored
127 (riaktest@127.0.0.1)3> C:put(O0, 1).
04de242 @dizzyd Updating README
dizzyd authored
128
129 Now, read the list back from the Riak server and extract the value
db66c33 import
justin authored
130
09eeb4c README updates for Erlang version
Grant Schofield authored
131
132 (riaktest@127.0.0.1)4> {ok, O1} = C:get(<<"groceries">>, <<"mine">>, 1).
133 {ok,{r_object,<<"groceries">>,<<"mine">>,
f3a76f9 @beerriot mention basic-setup.txt in README
beerriot authored
134 [{r_content,{dict,2,16,16,8,80,48,
135 {[],[],[],[],[],[],[],[],[],[],[],[],...},
136 {{[],[],[],[],[],[],
137 ["X-Riak-Last-Modified",87|...],
138 [],[],[],...}}},
139 ["bread"]}],
acdd472 Update README to use IP addresses in examples. (Bugzilla #65)
Rusty Klophaus authored
140 [{"20090722191020-riaktest@127.0.0.1-riakdemo@127.0.0.1-266664",
f3a76f9 @beerriot mention basic-setup.txt in README
beerriot authored
141 {1,63415509105}}],
142 {dict,0,16,16,8,80,48,
143 {[],[],[],[],[],[],[],[],[],[],[],[],[],...},
144 {{[],[],[],[],[],[],[],[],[],[],[],...}}},
145 undefined}}
146
acdd472 Update README to use IP addresses in examples. (Bugzilla #65)
Rusty Klophaus authored
147 (riaktest@127.0.0.1)5> %% extract the value
148 (riaktest@127.0.0.1)5> V = riak_object:get_value(O1).
f3a76f9 @beerriot mention basic-setup.txt in README
beerriot authored
149 ["bread"]
150
8056115 @beerriot re-export README.org
beerriot authored
151 Add milk to our list of groceries and write the new value to Riak:
75a7053 Updated admin.org, added man files
Grant Schofield authored
152
09eeb4c README updates for Erlang version
Grant Schofield authored
153
acdd472 Update README to use IP addresses in examples. (Bugzilla #65)
Rusty Klophaus authored
154 (riaktest@127.0.0.1)6> %% add milk to the list
155 (riaktest@127.0.0.1)6> O2 = riak_object:update_value(O1, ["milk" | V]).
09eeb4c README updates for Erlang version
Grant Schofield authored
156 {r_object,<<"groceries">>,<<"mine">>,
f3a76f9 @beerriot mention basic-setup.txt in README
beerriot authored
157 [{r_content,{dict,2,16,16,8,80,48,
158 {[],[],[],[],[],[],[],[],[],[],[],[],[],[],...},
159 {{[],[],[],[],[],[],
160 ["X-Riak-Last-Modified",87,101,100|...],
161 [],[],[],[],[],...}}},
162 ["bread"]}],
acdd472 Update README to use IP addresses in examples. (Bugzilla #65)
Rusty Klophaus authored
163 [{"20090722191020-riaktest@127.0.0.1-riakdemo@127.0.0.1-266664",
f3a76f9 @beerriot mention basic-setup.txt in README
beerriot authored
164 {1,63415509105}}],
165 {dict,0,16,16,8,80,48,
166 {[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],...},
167 {{[],[],[],[],[],[],[],[],[],[],[],[],[],...}}},
168 ["milk","bread"]}
169
acdd472 Update README to use IP addresses in examples. (Bugzilla #65)
Rusty Klophaus authored
170 (riaktest@127.0.0.1)7> %% store the new list
171 (riaktest@127.0.0.1)7> C:put(O2, 1).
f3a76f9 @beerriot mention basic-setup.txt in README
beerriot authored
172 ok
173
8056115 @beerriot re-export README.org
beerriot authored
174 Finally, see what other keys are available in groceries bucket:
c3ec58c Adding my updates to js-mapreduce.org detailing named functions and pre-...
Kevin Smith authored
175
60706d2 @dizzyd Updating README w/ server management section
dizzyd authored
176
09eeb4c README updates for Erlang version
Grant Schofield authored
177 (riaktest@127.0.0.1)8> C:list_keys(<<"groceries">>).
178 {ok,[<<"mine">>]}
60706d2 @dizzyd Updating README w/ server management section
dizzyd authored
179
2e029d9 @argv0 re-render README from README.org
argv0 authored
180 2.4 Clients for Other Languages
181 ================================
182
183 Client libraries are available for many languages. Rather than
184 bundle them with the Riak server source code, we have given them
185 each their own source repository. Currently, official Riak
186 client language libraries include:
187
188 + Javascript
189 [http://bitbucket.org/basho/riak-javascript-client]
190
191 + Python
192 [http://bitbucket.org/basho/riak-python-client]
193
194 + Ruby
195 [http://bitbucket.org/basho/riak-ruby-client]
196 [http://github.com/seancribbs/ripple/]
197
198 + Java
199 [http://bitbucket.org/basho/riak-java-client]
200
201 + PHP
202 [http://bitbucket.org/basho/riak-php-client]
203
204 + Erlang
205 [http://bitbucket.org/basho/riak-erlang-client]
206 (using protocol buffers instead of distributed Erlang)
8056115 @beerriot re-export README.org
beerriot authored
207
60706d2 @dizzyd Updating README w/ server management section
dizzyd authored
208 3 Server Management
209 ~~~~~~~~~~~~~~~~~~~~
210
211 3.1 Configuration
212 ==================
3f10857 @dizzyd Fix minor typo and ensure wrap at 80 cols
dizzyd authored
213 Configuration for the Riak server is stored in $RIAK/rel/riak/etc
214 directory. There are two files:
215 - vm.args
216 This file contains the arguments that are passed to the Erlang VM
217 in which Riak runs. The default settings in this file shouldn't need to be
218 changed for most environments.
60706d2 @dizzyd Updating README w/ server management section
dizzyd authored
219
3f10857 @dizzyd Fix minor typo and ensure wrap at 80 cols
dizzyd authored
220 - app.config
221 This file contains the configuration for the Erlang applications
222 that run on the Riak server.
60706d2 @dizzyd Updating README w/ server management section
dizzyd authored
223
f3a76f9 @beerriot mention basic-setup.txt in README
beerriot authored
224 More information about this files is available in doc/basic-setup.txt.
225
60706d2 @dizzyd Updating README w/ server management section
dizzyd authored
226 3.2 Server Control
227 ===================
228
229 3.2.1 bin/riak
230 ---------------
3f10857 @dizzyd Fix minor typo and ensure wrap at 80 cols
dizzyd authored
231 This script is the primary interface for starting and stopping the Riak
232 server.
60706d2 @dizzyd Updating README w/ server management section
dizzyd authored
233
234 To start a daemonized (background) instance of Riak:
235
236 $ bin/riak start
237
3f10857 @dizzyd Fix minor typo and ensure wrap at 80 cols
dizzyd authored
238 Once a server is running in the background you can attach to the Erlang
239 console via:
60706d2 @dizzyd Updating README w/ server management section
dizzyd authored
240
241 $ bin/riak attach
242
3f10857 @dizzyd Fix minor typo and ensure wrap at 80 cols
dizzyd authored
243 Alternatively, if you want to run a foreground instance of Riak, start it
244 with:
60706d2 @dizzyd Updating README w/ server management section
dizzyd authored
245
246 $ bin/riak console
247
3f10857 @dizzyd Fix minor typo and ensure wrap at 80 cols
dizzyd authored
248 Stopping a foreground or background instance of Riak can be done from a
249 shell prompt via:
60706d2 @dizzyd Updating README w/ server management section
dizzyd authored
250
251 $ bin/riak stop
252
253 Or if you are attached/on the Erlang console:
254
acdd472 Update README to use IP addresses in examples. (Bugzilla #65)
Rusty Klophaus authored
255 (riak@127.0.0.1)1> q().
60706d2 @dizzyd Updating README w/ server management section
dizzyd authored
256
257 You can determine if the server is running by:
258
259 $ bin/riak ping
260
261 3.2.2 bin/riak-admin
262 ---------------------
263 This script provides access to general administration of the Riak server.
acdd472 Update README to use IP addresses in examples. (Bugzilla #65)
Rusty Klophaus authored
264 The below commands assume you are running a default configuration for
265 parameters such as cookie.
60706d2 @dizzyd Updating README w/ server management section
dizzyd authored
266
267 To join a new Riak node to an existing cluster:
268
09eeb4c README updates for Erlang version
Grant Schofield authored
269
f3a76f9 @beerriot mention basic-setup.txt in README
beerriot authored
270 $ bin/riak start # If a local server is not already running
271 $ bin/riak-admin join <node in cluster>
272
60706d2 @dizzyd Updating README w/ server management section
dizzyd authored
273 (Note that you must have a local node already running for this to work)
274
275 To verify that the local Riak node is able to read/write data:
276 $ bin/riak-admin test
277
acdd472 Update README to use IP addresses in examples. (Bugzilla #65)
Rusty Klophaus authored
278 To backup a node or cluster run the following:
279 $ bin/riak-admin backup riak@X.X.X.X riak <directory/backup_file> node
280 $ bin/riak-admin backup riak@X.X.X.X riak <directory/backup_file> all
281
282 Restores can function in two ways, if the backup file was of a node the
283 node will be restored and if the backup file contains the data for a
284 cluster all nodes in the cluster will be restored.
285
286 To restore from a backup file:
287 $ riak-admin restore riak@X.X.X.X riak <directory/backup_file>
288
289 To view the status of a node:
290 $ bin/riak-admin status
291
292 If you change the IP or node name you will need to use the reip command:
293 $ bin/riak-admin reip <old_nodename> <new_nodename>
60706d2 @dizzyd Updating README w/ server management section
dizzyd authored
294
295
296
Something went wrong with that request. Please try again.