riak-0.9.2 / README

Welcome to Riak.

Riak is a distributed, decentralized data storage system.

Below, you will find the "quick start" directions for setting up and
using Riak.  For more information, browse the following files:

 README:  this file
 TODO:    a list of improvements planned for Riak
 LICENSE: the license under which Riak is released
 *.sh:    various startup scripts
 riak_demo.escript:  demo for a base level of Riak functionality
   basic-setup.txt:  slightly more detail on setting up Riak
   basic-client.txt: slightly more detail on using Riak
   architecture.txt: details about the underlying design of Riak,
                     and how this affects applications using it
   index.html:       the root of the edoc output of 'make docs'
   *.erl:            the source for Riak (it's friendly)
   *.erlenv:         example configuration files

Quick Start

This section assumes that you have copy of the Riak source tree at
$RIAK.  You should have created this by cloning a repo or expanding
a tarball from somewhere.

The quick start goes like this:

1. Build Riak
2. Start the Riak server
3. Connect a client and store/fetch data

1. Build Riak
Assuming you have a working Erlang (R13 or later) installation,
building Riak should be as simple as:

$ cd $RIAK
$ make

2. Start the Riak server - Assuming no errors were generated in the
build step, $RIAK/config/riak-demo.erlenv and replace all instances of
$RIAK with the directory in which $RIAK is installed.  For example,

{riak_heart_command, "(cd $RIAK; ./ $RIAK/config/riak-demo.erlenv)"}.


{riak_heart_command, "(cd /usr/local/riak; ./ /usr/local/riak/config/riak-demo.erlenv)"}.

Then start riak:

$ cd $RIAK
$ ./ config/riak-demo.erlenv

The server should start, then background itself, leaving you at a
command prompt.

At this point, you can use riak_demo.escript to ensure that Riak is

$ ./riak_demo.escript config/riak-demo.erlenv
Attempting to connect to with cookie riak_demo_cookie...
Connected successfully
Looking for pre-existing object at {riak_demo, "demo"}...
  No pre-existing object found, creating new
Storing object with new value...
  Written successfully
Fetching object at {riak_demo, "demo"}...
  Fetched successfully
  Object contained correct value

If riak_demo prints no "Error: ..." messages, and instead prints
"SUCCESS", then Riak is working.

3. Connect a client
Assuming no errors were generated during the server start step, a
simple client interaction will look like:

$ erl -name riaktest@ -pa $RIAK/ebin

(riaktest@> %% connect to Riak
(riaktest@> {ok, C} = riak:client_connect("", 9000, riak_demo_cookie).

riaktest@> %% Create a shopping list for bread at /groceries/mine
riaktest@> O0 = riak_object:new(<<"groceries">>, <<"mine">>, ["bread"]).

(riaktest@> %% store the list
(riaktest@> C:put(O0, 1).

(riaktest@> %% retrieve the list
(riaktest@> {ok, O1} = C:get(<<"groceries">>, <<"mine">>, 1).

(riaktest@> %% extract the value
(riaktest@> V = riak_object:get_value(O1).

(riaktest@> %% add milk to the list
(riaktest@> O2 = riak_object:update_value(O1, ["milk"|V]).

(riaktest@> %% store the new list
(riaktest@> C:put(O2, 1).

(riaktest@> %% find out what else is in the groceries bucket
(riaktest@> C:list_keys(<<"groceries">>).