Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

file 293 lines (206 sloc) 9.179 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293
                           Welcome to Riak.
                           ================

Date: 2010-06-09 10:06:44 CDT



Table of Contents
=================
1 Overview
2 Quick Start
    2.1 Building Riak
    2.2 Starting Riak
    2.3 Connecting a client to Riak
    2.4 Clients for Other Languages
3 Server Management
    3.1 Configuration
    3.2 Server Control
        3.2.1 bin/riak
        3.2.2 bin/riak-admin


1 Overview
~~~~~~~~~~~
  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
  * apps/ the source tree for Riak and all its dependencies
  * doc/
    - admin.org: Riak Administration Guide
    - architecture.txt: details about the underlying design of Riak
    - basic-client.txt: slightly more detail on using Riak
    - basic-setup.txt: slightly more detail on setting up Riak
    - basic-mapreduce.txt: introduction to map/reduce on Riak
    - js-mapreduce.org: using Javascript with Riak map/reduce
    - man/riak.1.gz: manual page for the riak(1) command
    - man/riak-admin.1.gz manual page for the riak-admin(1) command
    - raw-http-howto.txt: using the Riak HTTP interface



2 Quick Start
~~~~~~~~~~~~~~

  This section assumes that you have copy of the Riak source tree. To get
  started, you need to:
  1. Build Riak
  2. Start the Riak server
  3. Connect a client and store/fetch data

2.1 Building Riak
==================

   Assuming you have a working Erlang (R13B04 or later) installation,
   building Riak should be as simple as:


  $ cd $RIAK
  $ make rel

2.2 Starting Riak
==================

   Once you have successfully built Riak, you can start the server with the
   following commands:


  $ cd $RIAK/rel/riak
  $ bin/riak start

   Now, verify that the server started up cleanly and is working:

   $ bin/riak-admin test

   Note that the $RIAK/rel/riak directory is a complete, self-contained instance
   of Riak and Erlang. It is strongly suggested that you move this directory
   outside the source tree if you plan to run a production instance.

2.3 Connecting a client to Riak
================================

   Now that you have a functional server, let's try storing some data in
   it. First, start up a erlang node using our embedded version of erlang:


  $ erts-<vsn>/bin/erl -name riaktest@127.0.0.1 -setcookie riak
  
  Eshell V5.7.4 (abort with ^G)
  (riaktest@127.0.0.1)1>

   Now construct the node name of Riak server and make sure we can talk to it:


  (riaktest@127.0.0.1)4> RiakNode = 'riak@127.0.0.1'.
  
  (riaktest@127.0.0.1)2> net_adm:ping(RiakNode).
  pong
  (riaktest@127.0.0.1)2>
   
   We are now ready to start the Riak client:


  (riaktest@127.0.0.1)2> {ok, C} = riak:client_connect(RiakNode).
  {ok,{riak_client,'riak@127.0.0.1',<<4,136,81,151>>}}

   Let's create a shopping list for bread at /groceries/mine:


  (riaktest@127.0.0.1)6> O0 = riak_object:new(<<"groceries">>, <<"mine">>, ["bread"]).
  O0 = riak_object:new(<<"groceries">>, <<"mine">>, ["bread"]).
  {r_object,<<"groceries">>,<<"mine">>,
         [{r_content,{dict,0,16,16,8,80,48,
                           {[],[],[],[],[],[],[],[],[],[],[],[],[],[],...},
                           {{[],[],[],[],[],[],[],[],[],[],[],[],...}}},
                     ["bread"]}],
         [],
         {dict,1,16,16,8,80,48,
               {[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],...},
               {{[],[],[],[],[],[],[],[],[],[],[],[],[],...}}},
         undefined}
  
   (riaktest@127.0.0.1)3> C:put(O0, 1).
    
    Now, read the list back from the Riak server and extract the value


  (riaktest@127.0.0.1)4> {ok, O1} = C:get(<<"groceries">>, <<"mine">>, 1).
  {ok,{r_object,<<"groceries">>,<<"mine">>,
            [{r_content,{dict,2,16,16,8,80,48,
                              {[],[],[],[],[],[],[],[],[],[],[],[],...},
                              {{[],[],[],[],[],[],
                                ["X-Riak-Last-Modified",87|...],
                                [],[],[],...}}},
                        ["bread"]}],
            [{"20090722191020-riaktest@127.0.0.1-riakdemo@127.0.0.1-266664",
              {1,63415509105}}],
            {dict,0,16,16,8,80,48,
                  {[],[],[],[],[],[],[],[],[],[],[],[],[],...},
                  {{[],[],[],[],[],[],[],[],[],[],[],...}}},
            undefined}}
  
   (riaktest@127.0.0.1)5> %% extract the value
   (riaktest@127.0.0.1)5> V = riak_object:get_value(O1).
   ["bread"]

     Add milk to our list of groceries and write the new value to Riak:


  (riaktest@127.0.0.1)6> %% add milk to the list
  (riaktest@127.0.0.1)6> O2 = riak_object:update_value(O1, ["milk" | V]).
  {r_object,<<"groceries">>,<<"mine">>,
       [{r_content,{dict,2,16,16,8,80,48,
                         {[],[],[],[],[],[],[],[],[],[],[],[],[],[],...},
                         {{[],[],[],[],[],[],
                           ["X-Riak-Last-Modified",87,101,100|...],
                           [],[],[],[],[],...}}},
                   ["bread"]}],
       [{"20090722191020-riaktest@127.0.0.1-riakdemo@127.0.0.1-266664",
         {1,63415509105}}],
       {dict,0,16,16,8,80,48,
             {[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],...},
             {{[],[],[],[],[],[],[],[],[],[],[],[],[],...}}},
       ["milk","bread"]}
  
  (riaktest@127.0.0.1)7> %% store the new list
  (riaktest@127.0.0.1)7> C:put(O2, 1).
  ok

     Finally, see what other keys are available in groceries bucket:


  (riaktest@127.0.0.1)8> C:list_keys(<<"groceries">>).
  {ok,[<<"mine">>]}

2.4 Clients for Other Languages
================================

   Client libraries are available for many languages. Rather than
   bundle them with the Riak server source code, we have given them
   each their own source repository. Currently, official Riak
   client language libraries include:

   + Javascript
     [http://bitbucket.org/basho/riak-javascript-client]

   + Python
     [http://bitbucket.org/basho/riak-python-client]

   + Ruby
     [http://bitbucket.org/basho/riak-ruby-client]
     [http://github.com/seancribbs/ripple/]

   + Java
     [http://bitbucket.org/basho/riak-java-client]

   + PHP
     [http://bitbucket.org/basho/riak-php-client]

   + Erlang
     [http://bitbucket.org/basho/riak-erlang-client]
     (using protocol buffers instead of distributed Erlang)

3 Server Management
~~~~~~~~~~~~~~~~~~~~

3.1 Configuration
==================
   Configuration for the Riak server is stored in $RIAK/rel/riak/etc
   directory. There are two files:
   - vm.args
     This file contains the arguments that are passed to the Erlang VM
     in which Riak runs. The default settings in this file shouldn't need to be
     changed for most environments.

   - app.config
     This file contains the configuration for the Erlang applications
     that run on the Riak server.

   More information about this files is available in doc/basic-setup.txt.

3.2 Server Control
===================

3.2.1 bin/riak
---------------
    This script is the primary interface for starting and stopping the Riak
    server.

    To start a daemonized (background) instance of Riak:

    $ bin/riak start

    Once a server is running in the background you can attach to the Erlang
    console via:

    $ bin/riak attach

    Alternatively, if you want to run a foreground instance of Riak, start it
    with:

    $ bin/riak console

    Stopping a foreground or background instance of Riak can be done from a
    shell prompt via:

    $ bin/riak stop

    Or if you are attached/on the Erlang console:

    (riak@127.0.0.1)1> q().

    You can determine if the server is running by:

    $ bin/riak ping

3.2.2 bin/riak-admin
---------------------
    This script provides access to general administration of the Riak server.
    The below commands assume you are running a default configuration for
    parameters such as cookie.

    To join a new Riak node to an existing cluster:


  $ bin/riak start # If a local server is not already running
  $ bin/riak-admin join <node in cluster>

    (Note that you must have a local node already running for this to work)
    
    To verify that the local Riak node is able to read/write data:
    $ bin/riak-admin test

    To backup a node or cluster run the following:
    $ bin/riak-admin backup riak@X.X.X.X riak <directory/backup_file> node
    $ bin/riak-admin backup riak@X.X.X.X riak <directory/backup_file> all
    
    Restores can function in two ways, if the backup file was of a node the
    node will be restored and if the backup file contains the data for a
    cluster all nodes in the cluster will be restored.
    
    To restore from a backup file:
    $ riak-admin restore riak@X.X.X.X riak <directory/backup_file>
    
    To view the status of a node:
    $ bin/riak-admin status
    
    If you change the IP or node name you will need to use the reip command:
    $ bin/riak-admin reip <old_nodename> <new_nodename>
Something went wrong with that request. Please try again.