Product tutorials, how-tos, and fully-documented APIs.

Basic Cluster Setup

    Configuration of a Riak cluster requires instructing a node to listen on a non-local interface (i.e., not, and then joining nodes together for cluster participation.

    Begin by editing the app.config file. The app.config file will be located in your rel/riak/etc/ directory if you compiled from source, and /etc/riak/ if you used a binary install of Riak.

    The commands below presume that you are running from a source install, but if you have installed Riak with a binary install, you can substitute the usage of bin/riak with sudo /usr/sbin/riak and bin/riak-admin with sudo /usr/sbin/riak-admin.

    Note on changing -name value

    If possible, you should avoid starting Riak prior to editing the -name parameter in vm.args as described below. If you have already started Riak with the default settings, you cannot change the -name setting and then successfully restart the node. You must either discard the existing ring metadata by removing the contents of the ring directory (which will require rejoining all nodes into a cluster again) or rename the node using the riak-admin cluster replace command.

    Configure the First Node

    First, stop your Riak node if it is currently running:

    bin/riak stop

    Change the default IP address located under http{} in the riak_core section of app.config . (The port, 8098, does not need to be changed.) Let’s say our machine’s IP address is (This is just an example IP address. Yours will be specific to your machine.)

    {http, [ {"", 8098 } ]},


    {http, [ {"", 8098 } ]},

    The same configuration should be changed for the Protocol Buffers interface if you intend on using it. Do the same as above for the line in the riak_kv section:

    {pb_ip,   "" },


    {pb_ip,   "" },

    Next edit the etc/vm.args file and change the -name to your new IP:

    -name riak@


    -name riak@
    Node Names

    Use fully qualified domain names (FQDNs) rather than IP addresses for the cluster member node names. For example, “” and “riak@” are both acceptable node naming schemes, but using the FQDN style is preferred.

    Once a node has been started, in order to change the name you must either remove ring files from the data directory, riak-admin reip the node, or riak-admin cluster force-replace the node.

    Start the Riak node:

    bin/riak start

    If the Riak node has been previously started, you must use riak-admin cluster replace to change the node name and update the node's ring file.

    bin/riak-admin cluster replace riak@ riak@

    As with all cluster changes, you need to view the plan riak-admin cluster plan, then run riak-admin cluster commit to finalize the changes.

    The node is now properly configured to join other nodes for cluster participation. Proceed to adding a second node to the cluster.

    Add a Second Node to Your Cluster

    Repeat the above steps for a second host on the same network. Once the second node has started, use riak-admin cluster join to join the second node to the first node, thereby creating an initial Riak cluster.

    bin/riak-admin cluster join riak@

    Output from the above should resemble:

    Success: staged join request for riak@ to riak@

    Next, plan and commit the changes:

    bin/riak-admin cluster plan
    bin/riak-admin cluster commit

    After the last command, you should see:

    Cluster changes committed

    If your output was similar, then the second Riak node is now part of the cluster and has begun syncing with the first node. Riak provides several ways to determine the cluster ring status; here are two ways to examine your Riak cluster's ring:

    Using the riak-admin command:

    bin/riak-admin status | grep ring_members

    With output resembling the following:

    ring_members : ['riak@','riak@']

    Using the riak attach command:

    riak attach
    1> {ok, R} = riak_core_ring_manager:get_my_ring().
    (riak@> riak_core_ring:all_members(R).

    To join additional nodes to your cluster, repeat the above steps. You can also find more detailed instructions about Adding and Removing Nodes from a cluster.

    Ring Creation Size

    All nodes in the cluster must have the same initial ring_creation_size setting in order to join, and participate in cluster activity. This setting can be adjusted in app.config.

    Check the value of all nodes if you receive a message like this:
    Failed: riak@ has a different ring_creation_size

    Running Multiple Nodes on One Host

    If you built Riak from source code, or if you are using the Mac OS X pre-built package, then you can easily run multiple Riak nodes on the same machine. The most common scenario for doing this is to experiment with running a Riak cluster. (Note: if you have installed the .deb or .rpm package, then you will need to download and build Riak source to follow the directions below.)

    To run multiple nodes, make copies of the riak directory.

    Presuming that you copied ./rel/riak into ./rel/riak1, ./rel/riak2, ./rel/riak3, and so on:

    Now, start the nodes, changing path names and nodes as appropriate:

    ./rel/riak1/bin/riak start
    ./rel/riak2/bin/riak start
    ./rel/riak3/bin/riak start

    Next, join the nodes into a cluster:

    ./rel/riak2/bin/riak-admin cluster join riak1@
    ./rel/riak3/bin/riak-admin cluster join riak1@
    ./rel/riak2/bin/riak-admin cluster plan
    ./rel/riak2/bin/riak-admin cluster commit

    Make a Developer Release

    Alternatively, you can run make devrel, which will create four copies of Riak under the directories ./dev/dev1, ./dev/dev2, ./dev/dev3, and ./dev/dev4 with the configuration pre-set to allow you to run the nodes simultaneously. (Note: The Web port for the three nodes is 8091, 8092, 8093 and 8094, which is different from the default of 8098 that you get when you run make all rel.)

    Once you have built the four nodes using make devrel can start each of them and join them together using the commands already covered above, substituting directory names as appropriate.

    Multiple Clusters on One Host

    Using the above technique it is possible to run multiple clusters on one computer. If a node hasn’t joined an existing cluster it will behave just as a cluster would. Running multiple clusters on one computer is simply a matter of having two or more distinct nodes or groups of clustered nodes.