riak / www / basic-setup.html

justin 1c37b76 










































Bryan Fink ba2d9df 
justin 1c37b76 








Bryan Fink ba2d9df 



justin 1c37b76 


Bryan Fink ba2d9df 


justin 1c37b76 



Bryan Fink ba2d9df 


justin 1c37b76 

Bryan Fink ba2d9df 


justin 1c37b76 




Bryan Fink ba2d9df 


justin 1c37b76 




Bryan Fink ba2d9df 


justin 1c37b76 

Bryan Fink ba2d9df 


justin 1c37b76 






Bryan Fink ba2d9df 


justin 1c37b76 






Bryan Fink ba2d9df 


justin 1c37b76 



Bryan Fink ba2d9df 


justin 1c37b76 

Bryan Fink ba2d9df 


justin 1c37b76 

Bryan Fink ba2d9df 



justin 1c37b76 


Bryan Fink ba2d9df 
justin 1c37b76 












Bryan Fink ba2d9df 
justin 1c37b76 





Bryan Fink ba2d9df 
justin 1c37b76 






Bryan Fink ba2d9df 
justin 1c37b76 



Bryan Fink ba2d9df 
justin 1c37b76 







Bryan Fink ba2d9df 
justin 1c37b76 













Bryan Fink ba2d9df 
justin 1c37b76 

Bryan Fink ba2d9df 
justin 1c37b76 


Bryan Fink ba2d9df 
justin 1c37b76 






Bryan Fink ba2d9df 
justin 1c37b76 







Bryan Fink ba2d9df 
justin 1c37b76 







Bryan Fink ba2d9df 
justin 1c37b76 

Bryan Fink ba2d9df 
justin 1c37b76 







Bryan Fink ba2d9df 
justin 1c37b76 





Bryan Fink ba2d9df 
justin 1c37b76 



































<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
	<meta name="author" content="Basho Technologies" />
	<meta name="description" content="riak - a decentralized key value store - basho technologies" />
	<meta name="keywords" content="riak nosql decentralized distributed key value store" />
    <meta http-equiv="content-type" content="text/html;charset=utf-8" />
	<link rel="stylesheet" href="css/style-1c.css" type="text/css" />
	<title>Riak - Setup</title>
</head>
<body>
	<div id="content">
		<h1><span class="hr"></span><a href="/">riak</a></h1>
		<ul id="top">
			<li><a href="/">Home</a></li>
			<li><a href="http://bitbucket.org/justin/riak/">Source Code</a></li>
                        <li><a href="edoc/index.html">API Docs</a></li>
			<li><a href="faq.html">FAQ</a></li>
			<li><a href="contact.html">Contact</a></li>
		</ul>
		
		<div id="intro">
			<p>Setting up a Riak cluster</p>
		</div>
		<div id="left">
			
			<h3>Cluster Setup Overview</h3>
<p>This document explains how to set up a Riak cluster.  It assumes that
you have already downloaded and successfully built Riak.  For help with
those steps, please refer to the README at the top level of the
source directory.</p>

<p>
Riak has many knobs to tweak, affecting everything from distribution
to disk storage.  This document will attempt to give a description of
the common configuration parameters, then describe two typical setups,
one small, one large.
</p>

<h3>configuration file format</h3>
<p>
Riak node configurations are stored in simple text files.  Users familiar with
Erlang's file:consult/1 function will recognize the format:
</p>

<pre>
{ParameterName1, Setting1}.
{ParameterName2, Setting2}.
...
</pre>

<p>
The following are some useful parameters:
</p>
<dl>
<dt><code>cluster_name: string</code></dt>
<dd>
  The name of the cluster.  Can be anything.  Used mainly in saving
  ring configuration.  All nodes in a cluster should have the same
  cluster name.  This parameter is required.
</dd>
<dt><code>doorbell_port: integer</code></dt>
<dd>
  Network port (UDP) on which this node will listen for connections from
  clients and other nodes.  If this parameter is not specified, the node
  cannot be used to service client requests, but can still participate
  in storage.
</dd>
<dt><code>riak_cookie: atom</code></dt>
<dd>
  The Erlang cookie for the riak cluster.  All nodes in a cluster
  must have the same cookie.  This parameter is required.
</dd>
<dt><code>riak_heart_command: string</code></dt>
<dd>
  The command that heart should use to restart this node.  This
  usually takes the form of:
  "(cd /riak; ./start-restart.sh /riak/config/riak.erlenv)".
  If this parameter is missing or malformed, heart will not auto-restart
  crashed Riak nodes.
</dd>
<dt><code>riak_hostname: string</code></dt>
<dd>
  The host on which this node is running.  This is used to construct
  the long-name form of the Erlang node.  On a developer machine, this
  might be "127.0.0.1".  If other nodes cannot reach this node's host
  by use of this hostname, the cluster will fail to connect.
  This parameter is required.
</dd>
<dt><code>riak_nodename: atom</code></dt>
<dd>
  The short-name form of the Erlang node.  This is used to construct
  the long-name form.  This parameter is required.
</dd>
<dt><code>ring_creation_size: integer</code></dt>
<dd>
  The number of partitions to divide the keyspace into.  This can be
  any number, but you probably don't want to go lower than 16, and
  production deployments will probably want something like 1024 or
  greater.  In any case, it should be much larger than your intended
  number of nodes.  This can be a very difficult parameter to change
  after your ring has been created, so choose a number that allows
  for growth.  This parameter defaults to 1024.
</dd>
<dt><code>storage_backend: atom</code></dt>
<dd>
  Name of the module that implements the storage for all vnodes
  on this Riak node.  The four backends that ship with Riak are
  riak_fs_backend, riak_ets_backend, riak_dets_backend, and
  riak_osmos_backend. Some backends have their own set of
  configuration parameters which should also be set.  This parameter
  does not have a default, but unless you have a very unusual cluster
  setup you must set it to a valid storage backend on every node.
<dl>
<dt><code>riak_fs_backend_root: string</code></dt>
<dd>
    If you have set the storage_backend to riak_fs_backend, then
    you must set this parameter to determine where data will be stored.
    Note that riak_fs_backend performs poorly when there is a large
    amount of data per vnode, and is primarily used for testing.
</dd>
<dt><code>riak_dets_backend_root: string</code></dt>
<dd>
    If you have set storage_backend to riak_dets_backend, you should
    use this parameter to determine where this backend will store its files.
</dd>
<dt><code>riak_osmos_backend_root: string</code></dt>
<dd>
    If you have set storage_backend to riak_osmos_backend, you should
    use this parameter to determine where this backend will store its files.
</dd>
</dl>
</dd>
</dl>
<h3>small (developer laptop) configuration</h3>
<p>
A configuration like this one may serve well for a very small cluster such as that used by an individual developer:
</p>
<pre>
{cluster_name, "default"}.
{ring_creation_size, 16}.
{doorbell_port, 9000}.
{storage_backend, riak_dets_backend}.
{riak_dets_backend_root, "/var/riak/store"}.
{riak_cookie, default_riak_cookie}.
{riak_heart_command,
 "(cd /usr/local/riak; ./start-restart.sh /usr/local/riak/config/riak.erlenv)"}.
{riak_nodename, riak}.
{riak_hostname, "127.0.0.1"}.
</pre>

<p>
This configuration assumes that you'll be connecting to the cluster
from localhost, and that Riak is installed at /usr/local/riak.  The
cluster will store its data in /var/riak/store.
</p>
<p>
To start the first node of this cluster:
</p>

<ol>
<li>Save the configuration to /usr/local/riak/config/riak.erlenv</li>
<li>cd /usr/local/riak</li>
<li>./start-fresh.sh config/riak.erlenv</li>
</ol>

<p>
The node will start and background itself.  Your cluster should now be
ready to accept requests.  See the
<a href="dev.html">developer documentation</a>
for simple instructions on connecting and storing and fetching data.
</p>

<h3>larger (production) configuration</h3>
<p>
If you're running any sort of cluster that could be labeled
"production", "deployment", "scalable", "enterprise", or any other
word implying that the cluster will be running interminably with
on-going maintenance needs, then you will want a different
configuration.  Something like this will work:
</p>

<pre>
{cluster_name, "default"}.
{ring_creation_size, 1024}.
{doorbell_port, 9000}.
{storage_backend, riak_dets_backend}.
{riak_dets_backend_root, "/var/riak/store"}.
{riak_cookie, default_riak_cookie}.
{riak_heart_command,
 "(cd /usr/local/riak; ./start-restart.sh /usr/local/riak/config/riak.erlenv)"}.
{riak_nodename, riak}.
{riak_hostname, "yourhost0.yourdomain.example.com"}.
</pre>

<p>
(the most notable changes are to ring_creation_size and riak_hostname)
</p>

<p>
Starting the first node in this cluster is just like starting the
first node in the dev cluster:
</p>

<ol>
<li> Save the configuration to /usr/local/riak/config/riak.erlenv </li>
<li> cd /usr/local/riak </li>
<li> ./start-fresh.sh config/riak.erlenv </li>
</ol>

<p>
The node will start and background itself.  Your cluster should now be
ready to accept requests.  See the
<a href="dev.html">developer documentation</a>
for simple instructions on connecting and storing and fetching data.
</p>

<p>
Starting more nodes in production is just as easy:
</p>

<ol>
<li> Install Riak on another host. </li>
<li> Copy riak.erlenv from your original host to the new host. </li>
<li> Edit riak.erlenv and change riak_hostname to match the new host's name. </li>
<li> ./start-join config/riak.erlenv yourhost0.yourdomain.example.com 9000 </li>
</ol>

<p>
That node will also start and background itself.  You cluster will
still be ready to accept requests, with no further changes.
</p>

<h3>what about logging?</h3>
<p>
Riak doesn't do any persistent logging in the default configuration.
Instead, logging can be enabled and disabled by connecting and
disconnecting an "eventer".  Eventers are described more fully
<a href="eventer.html">here</a>, but these simple steps for starting the default
logging eventer are:
</p>

<ol>
<li> cd /usr/local/riak </li>
<li> ./start-eventer.sh default default_riak_cookie 127.0.0.1 9000 evt riak_event_logger /tmp/riakevt.log</li>
</ol>

<p>
That command will start an Erlang node named 'evt' that will stay
running.  It will connect to the cluster "default" at 127.0.0.1:9000,
with Erlang cookie 'default_riak_cookie'.  It will then begin spewing
data into /tmp/riakevt.log.  Use 'tail -f /tmp/riakevt.log' to watch
it fly by.  Note that it is not recommended that you connect this
particular logger to an active production cluster, as it generates a
*lot* of data, and has no provision for things like log file rollover.
</p>
<p>
More focused logs can easily be produced by a logger that pattern-matches
to log only specific events, and performance can be managed by running
the logger/eventer on a machine that is not running a storage node.
</p>


			<br />
			
			
		</div>
		<div id="right">
			
		</div>
		<div id="footer">

		</div>
	</div>
<script type="text/javascript">
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script>
<script type="text/javascript">
try {
var pageTracker = _gat._getTracker("UA-10051263-1");
pageTracker._trackPageview();
} catch(err) {}</script>
</body>
</html>
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.