Skip to content

HTTPS clone URL

Subversion checkout URL

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