This document describes the installation of SPLAY on Ubuntu linux version 9.10 or 10.04 LTS.

Comments, questions and suggestions are welcome: info@splay-project.org

NOTE: a far more convenient automatic packaged installer of the SPLAY daemon (splayd) and associated libraries for Ubuntu is available in the download section.

This document is composed of four parts:

• Common requirements
• Installation of the SPLAY daemon or splayd and libraries.
• Installation of the controller (orchestrates the run on a testbed)
• Installation of SPLAY command-line-interface (CLI)

Disclaimers:

• this tutorial was tested using Ubuntu 9.10 and 10.04 LTS. The installation works with Ubuntu 8.0.4 TLS with one minor exception (detailed in the text);
• this tutorial assumes that you do not change the default paths of Lua, Ruby, and other third party software.

Common requirements

A. Install syntax highlighting for your favorite text editor

You may want to install Lua text coloring (and language-specific functions):

Installing the SPLAY daemon (splayd) and libraries

The splayd is required to run on each node of the testbed in a SPLAY deployment. For local runs, only the libraries need to be accessible via the LUA PATH.

A. Install required dependencies

The required packages differ depending on the Ubuntu distribution you are using.

sudo apt-get install \
build-essential lua5.1 liblua5.1-0 liblua5.1-0-dev \
liblua5.1-socket2 liblua5.1-socket-dev \
libssl-dev libssl0.9.8 liblua5.1-sec1

sudo apt-get install \
build-essential lua5.1 liblua5.1-0 liblua5.1-0-dev \
liblua5.1-socket2 liblua5.1-socket-dev \
libssl-dev libssl0.9.8 liblua5.1-sec0

sudo apt-get install \
build-essential lua5.1 liblua5.1-0 liblua5.1-0-dev \
liblua5.1-socket2 liblua5.1-socket-dev \
libssl-dev libssl0.9.8

wget http://mirror.ne.gov/ubuntu/pool/universe/l/lua-sec/liblua5.1-sec1_0.4-3_i386.deb
sudo dpkg -i liblua5.1-sec1_0.4-3_i386.deb

wget http://mirror.ne.gov/ubuntu/pool/universe/l/lua-sec/liblua5.1-sec1_0.4-3_amd64.deb
sudo dpkg -i liblua5.1-sec1_0.4-3_amd64.deb

B. Get the SPLAY daemon (splayd) source

Get the latest version of the splayd archive on this site. Here, the instructions refer to version 1.0 but apply to all following versions. First unpack the archive:

tar xvzf splayd_1.0.tar.gz 
cd splayd_1.0

As long as you did not change the default paths in your system, you do not need to modify the Makefile or any other file to compile the splayd and libraries on Ubuntu.

C. Build the splayd and the libraries

In the splayd_1.0 folder, type:

make all

When one includes some library within LUA, LUA looks first for a LUA-based library and then for a C-based library. The former is looked for in the LUA_PATH and the latter is in the LUA_CPATH.

It is recommended to create two directories "lualib" and "lualibc" for .lua and .so libraries:

mkdir -p ~/local/lualibs/lualib
mkdir -p ~/local/lualibs/clib

Edit install.sh and set LUA paths:

L_PATH=/home/YOU/local/lualibs/lualib
L_CPATH=/home/YOU/local/lualibs/clib

The compiled libraries will go in the L_CPATH while Lua libraries will be in L_PATH. You can use system-wide directories, and then use sudo for calling the install script.

Edit your ~/.bashrc and add at the end:

SPLAY_PATH="/home/YOU/local/lualibs/lib/?.lua"
SPLAY_CPATH="/home/YOU/local/lualibs/clib/?.so"
ST_PATH=`lua -e "print( package.path)"`
ST_CPATH=`lua -e "print( package.cpath)"`
if [[ "$ST_PATH" != *"$SPLAY_PATH"* ]]; then
	LUA_PATH="$SPLAY_PATH;$ST_PATH"
	LUA_CPATH="$SPLAY_CPATH;$ST_CPATH"
	export LUA_PATH LUA_CPATH
fi

Take the modifications into account:

source ~/.bashrc

D. Install the Splay libraries

Run the following command. You need to use sudo if LUA_(C)PATH is in the system-wide hierarchy

./install.sh

At this point, you can start using local runs of your Splay code using the libraries. You only have to proceed with the remaining of this tutorial if you plan to use the splayd itself, that is, on a machine on a testbed for being controlled by a controller node.

E. Prepare and run the splayd

Edit settings.lua and:

• set splayd.settings.name to something (e.g. the machine DNS name)
• set additional restrictions for the jobs that will be running on this splayd (if required)
• remove the two lines at the end to finish the setup.

To execute a splayd, you will need IN THE SAME DIRECTORY the following files:

• splayd
• splayd.lua
• jobd
• jobd.lua
• settings.lua
• *.pem

When a splayd runs, it will automatically create logs/, jobs/ and jobs_fs/ directories, so you need write access (path can eventually be changed editing splayd.lua).

Try the splay daemon:

./splayd

>> NAME: testname
>> KEY: local
>> Running on 32bits Darwin (little endian)

Installing the controller

The controller does not require compilation, but it requires a MySql database and some Ruby libraries. If you already have one, just skip the database creation in step B and ask the administrator to create a database and a user for you, both named 'splay'.

A. Set up: install a database, ruby and associated bindings

Install ruby and mysql using apt-get:

sudo apt-get install libruby1.8 ruby ruby1.8 ruby1.8-dev \
mysql-client-5.1 mysql-server libmysqlclient-dev rubygems1.8 libssl-dev libopenssl-ruby1.8

Install the support for openssl, json and ruby/SQL wrappers:

sudo gem install openssl-nonblock json dbi dbd-mysql mysql

B. Create the database

Create the database that will be used by the controller:

mysql -u root -p

create database splay;
GRANT ALL PRIVILEGES ON splay.* TO 'splay'@'localhost' IDENTIFIED BY 'splay' WITH GRANT OPTION;
quit;

C. Get and run the controller

Get the latest controller from here and unpack it:

tar xvfz controller-xxx.tar.gz
cd controller-xxx

Edit the database information: edit lib/db_config.rb and edit:

class DBConfig
	SQL_TYPE = "Mysql"
	SQL_DB = "splay"
	SQL_HOST = "localhost"
	SQL_USER = "splay"
	SQL_PASS = "splay"
end

Initialize the database:

ruby -rubygems init_db.rb

Initialize the users table:

ruby -rubygems init_users.rb

After this command, SPLAY will have on its tables only one user, admin, with password admin, which has the role of Administrator. To better understand the user's table manipulation, go here.

Start the cli-server (Server for the remote Command Line Interface) component of the controller and leave it running:

cd cli-server
ruby -rubygems cli-server.rb

Launch the controller:

ruby -rubygems controller.rb

Launch a splayd and observe the output of the controller. For running multiple splayd on the same machine, one has to set production to false (see INSTALL in the splayd folder). Nonetheless, local runs are supposed to be made outside of Splay.

Installing the SPLAY command tool

To install the SPLAY command tool, which will permit you to send commands remotely to the SPLAY controller, you have first to install LUA and some libraries:

sudo apt-get install lua5.1 liblua5.1-socket2 liblua5.1-json

NOTE: if you already installed the splayd package, apt-get will return the following error:

trying to overwrite '/usr/share/lua/5.1/json.lua', which is also in package splayd

This is due to the fact that the file json.lua is already installed by splayd and it contains a modified version that adapts to the needs of SPLAY. Please don't pay attention to this error.

tar xvfz splay-command-tool_1.0.tar.gz