Skip to content

HTTPS clone URL

Subversion checkout URL

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