Riak Core Tutorial Part 1: Setup

The Easy Way

If you don't have Erlang installed or you don't have problem to install the latest one system wide you can try installing it with your package manager:

• For Homebrew on OS X: brew install erlang

• For MacPorts on OS X: port install erlang

• For Ubuntu and Debian: apt-get install erlang

• For Fedora: yum install erlang

• For FreeBSD: pkg install erlang

Please check that the package version is 20.x, if not, check for instructions on how to install the Erlang Solutions package for Ubuntu, CentOS, Mac OS X, Debian or Fedora here: https://www.erlang-solutions.com/resources/download.html

Setting up rebar3

Now we have Erlang, we need a build tool, we are going to use rebar3:

# download rebar3 to our bin directory
wget https://s3.amazonaws.com/rebar3/rebar3 -O $HOME/bin/rebar3

# set execution permissions for our user
chmod u+x rebar3

Just in case you have problems running the rebar3 commands with a different version, here's the version I'm using:

rebar3 version

Output:

rebar 3.5.0 on Erlang/OTP 20 Erts 9.2

Install Riak Core Rebar3 Template

To create a Riak Core project from scratch we will use a template called rebar3_template_riak_core.

we need to clone its repo in a place where rebar3 can see it:

mkdir -p ~/.config/rebar3/templates
git clone https://github.com/marianoguerra/rebar3_template_riak_core.git ~/.config/rebar3/templates/rebar3_template_riak_core

The Hard Way: Building Erlang with kerl

If you have or want to have more than one version running side by side you can use kerl, from its github README:

Easy building and installing of Erlang/OTP instances.

Kerl aims to be shell agnostic and its only dependencies, excluding what's
required to actually build Erlang/OTP, are curl and git.

First we need to fetch kerl:

# create bin folder in our home directory if it's not already there
mkdir -p ~/bin

# cd to it
cd ~/bin

# download kerl script
curl -O https://raw.githubusercontent.com/kerl/kerl/master/kerl

# set execution permitions for our user
chmod u+x kerl

You will need to add ~/bin to your PATH variable so your shell can find the kerl script, you can do it like this in your shell:

# set the PATH environment variable to the value it had before plus a colon
# (path separator) and a new path which points to the bin folder we just
# created
PATH=$PATH:$HOME/bin

If you want to make this work every time you start a shell you need to put it it the rc file of your shell of choice, for bash it's ~/.bashrc, for zsh it's ~/.zshrc, you will have to add a line like this:

export PATH=$PATH:$HOME/bin

After this, start a new shell or source your rc file so that it picks up your new PATH variable, you can check that it's set correctly by running:

echo $PATH

And checking in the output if $HOME/bin is there (notice that $HOME will be expanded to the actual path).

Building an Erlang release with kerl

We have kerl installed and available in our shell, now we need to build an Erlang release of our choice, for this we will need a compiler and other tools and libraries needed to compile it:

This are instructions on ubuntu 17.10, check the names for those packages on your distribution.

# required: basic tools and libraries needed
# (compiler, curses for the shell, ssl for crypto)
sudo apt-get -y install build-essential m4 libncurses5-dev libssl-dev

# optonal: if you want odbc support (database connectivity)
sudo apt-get install unixodbc-dev

# optonal: if you want pdf docs you need apache fop and xslt tools and java (fop is a java project)
sudo apt-get install -y fop xsltproc default-jdk

# optional: if you want to build jinterface you need a JDK
sudo apt-get install -y default-jdk

# optional: if you want wx (desktop GUI modules)
sudo apt-get install -y libwxgtk3.0-dev

Now that we have everything we need we can finally build our Erlang release.

First we fetch an updated list of releases:

kerl update releases

The output in my case:

The available releases are:

R10B-0 R10B-10 R10B-1a R10B-2 R10B-3 R10B-4 R10B-5 R10B-6 R10B-7 R10B-8
R10B-9 R11B-0 R11B-1 R11B-2 R11B-3 R11B-4 R11B-5 R12B-0 R12B-1 R12B-2 R12B-3
R12B-4 R12B-5 R13A R13B01 R13B02-1 R13B02 R13B03 R13B04 R13B R14A R14B01
R14B02 R14B03 R14B04 R14B_erts-5.8.1.1 R14B R15B01 R15B02
R15B02_with_MSVCR100_installer_fix R15B03-1 R15B03 R15B
R16A_RELEASE_CANDIDATE R16B01 R16B02 R16B03-1 R16B03 R16B 17.0-rc1 17.0-rc2
17.0 17.1 17.3 17.4 17.5 18.0 18.1 18.2.1 18.2 18.3 19.0 19.1 19.2 19.3
20.0 20.1 20.2 20.3

Let's build the 20.3 version:

# this will take a while
kerl build 20.3 20.3

And install it:

kerl install 20.3 ~/bin/erl-20.3

Now everytime we want to use this version of Erlang we need to run:

. $HOME/bin/erl-20.3/activate

Test that Everything Works

We have installed several tools:

kerl

Let's you install multiple Erlang releases that can live side by side

Erlang 20.3

The version of erlang we are going to be using

Rebar 3

Our build tool

rebar3_template_riak_core

Rebar 3 Template that will make it easy to setup fresh riak_core projects for experimentation

Now we need to check that everything is setup correctly, we will do that by creating a template and building it.

Remember to have $HOME/bin in your $PATH and Erlang 20.3 activated, cd to a folder of your choice to hold this project and run:

rebar3 new rebar3_riak_core name=akv

Output should be similar to this one:

===> Writing akv/apps/akv/src/akv.app.src
===> Writing akv/apps/akv/src/akv.erl
===> Writing akv/apps/akv/src/akv_app.erl
===> Writing akv/apps/akv/src/akv_sup.erl
===> Writing akv/apps/akv/src/akv_console.erl
===> Writing akv/apps/akv/src/akv_vnode.erl
===> Writing akv/rebar.config
===> Writing akv/.editorconfig
===> Writing akv/.gitignore
===> Writing akv/README.rst
===> Writing akv/Makefile
===> Writing akv/config/admin_bin
===> Writing akv/priv/01-akv.schema
===> Writing akv/config/advanced.config
===> Writing akv/config/vars.config
===> Writing akv/config/vars_dev1.config
===> Writing akv/config/vars_dev2.config
===> Writing akv/config/vars_dev3.config

Now let's try to build it:

cd akv
make

Output is to long to list, after it ends, near the end you should see this line:

===> release successfully created!

Now let's try to run it:

make console

Last lines should be:

Eshell V9.3  (abort with ^G)
(akv@127.0.0.1)1>

You can exit with q(). and pressing enter or hitting Ctrl-C twice.

We're ready to start!