Olio/Rails
Install and Setup Guide from Tarball

Note: The application currently does not use memcached. Please ignore the memcached related setup instructions.

This document assumes some familiarity with setting up Ruby on Rails. If you have never set up rails before, you may need to do some web searching if you get stuck in any of the steps.

Overview

Olio is a macro-level toolkit consisting of the following components:

  1. The web application

  2. The main database

  3. Distributed storage servers (NFS)

  4. Geocoder emulator

  5. Workload driver

If your primary interest is in setting up the application alone, you need items 1-3 above and they can all be setup on a single system. If on the other hand, you would like to drive load against the application, you will need at least 2 systems. At higher loads, you may need multiple systems. At a minimum, we need to separate the SUT (System Under Test) components and the non-SUT components to get valid results. The non-SUT components are the Geocoder emulator and the workload driver. It is best to connect the driver machine to the SUT machine on a local private network. This ensures that latencies measured do not include arbitrary delays.

For a horizontally scaled workload, or to measure the performance of the individual components, you can deploy the SUT components on separate physical or virtual machines. Keep in mind though that the bulk of the CPU is consumed in the web application tier (nginx/rails).

In the following sections, we will go over the steps needed to configure each component :

Extracting the Contents

The Olio/Rails kit is packaged as a gzipped tar file. The first task is to unzip the file and untar it to extract it's contents. Because of the long pathnames, please use GNU tar to extract. This can be done as follows:

# gzcat apache-olio-rails-<version>.tar.gz | gtar xvf -

This will cause a directory named olio-rails-<version> to be created whose contents should look like:

# ls apache-olio-rails-0.1*

LICENSE OlioDriver.jar geocoder.war rails_setup_kit.html

NOTICE RELEASE-NOTES-rails-0.1.txt oliorails/ release

#

We will use $OLIO_HOME to designate the name of this directory. A description of the contents follows :

Setting up the driver

Even if you don't plan to drive load against the application, this setup is required as the database and file loaders are part of the workload driver - feel free to install the driver on the same system as the web application.

  1. See http://faban.sunsource.net/docs/guide/harness/install.html for Faban installation instructions. Note that faban needs to be installed in the same location on all the machines used for the test. Please also read the Getting Started Guide to get a high-level understanding of Faban terminology and how it works. From now on, we will refer to the faban install directory as $FABAN_HOME.

  2. Copy $OLIO_HOME/OlioDriver.jar to the $FABAN_HOME/benchmarks directory. Also copy the OlioDriver.jar file to the $FABAN_HOME/benchmarks directory on the system that will run the rails application.

  3. For the driver to work, you will need JDK 1.6. Set JAVA_HOME to the path of the JDK in the faban user's environment.

  4. Start the faban master on the master driver machine : $FABAN_HOME/master/bin/startup.sh

  5. Test that you can connect to the master by pointing your browser at http://<driver_machine>:9980.

  6. Download MySQL Connector/J (JDBC Driver for MySQL) and install the jar in $FABAN_HOME/benchmarks/OlioDriver/lib.

Installing the Web Application

Required Software

The web application is a Rails application. It requires the following components:

  1. A web server such as Nginx, Lighttpd or Apache (the instructions below focus on nginx)

  2. Ruby 1.8.6 or higher with the following gems and their dependencies :


  1. FreeImage (which needs to be downloaded and built)

  2. MySQL 5 (5.1 recommended)

Additional Installation Steps

For Linux (debian or ubuntu), the following command can be used:

     aptitude install build-essential subversion ruby1.8 ruby1.8-dev nginx libmysqlclient-dev rubygems libgems-ruby1.8

For OpenSolaris 2008.11:



CONFIG["LDSHARED"] = "/usr/sfw/bin/gcc -G"



gem install mysql --with-mysql-lib=/usr/mysql/5.0/lib/mysql --with-mysql-include=/usr/mysql/5.0/include.



gem install rake rails thin rcov will_paginate image_science

Nginx Configuration

Once you have the application stack installed, follow the steps below to set up the application.

  1. Decide where you want to install the web application. For this example we will use /var/app: 

    $ mkdir /var/app
$ cd /var/app

  2. Copy the contents of $OLIO_HOME/oliorails to /var/app/olio. We will use $APP_DIR to refer to the location: /var/app/olio

  3. Now edit nginx.conf. There is an example in the $APP_DIR/etc directory. If you're using a single machine and you're using root as the user, you can copy the file to the nginx 'conf' directory. For OpenSolaris, comment out the error_log and pid entries. The default location for these files is in /var/nginx/logs.

    To change user to another user, modify the first line and change user root; to your preferred user. On OpenSolaris, the default user is usually webservd.

The nginx.conf has a section named upstream thin that contains a list of the server and port numbers of the rails application servers that will host the application. If you have more than one machine hosting your thins or if the applications are located on a different machine to Nginx, modify this section and add the addresses and port numbers of your application servers.

    To change the location of the application static content :

#### Replace with the full path to your rails app's public directory: 

       root /var/www/virtual/example.com/rails/railsapp/public;

to root $APP_DIR/public; # replace $APP_DIR with whatever value you used for $APP_DIR throughput the installation



    Do NOT start nginx yet.

Setting up the database

  1. If you plan to run MySQL on a separate machine, install MySQL on that system. We will refer to the MySQL installation directory as MYSQL_HOME.

  2. Setup the mysql user/group and permissions for it's directories: 

    # groupadd mysql
# useradd -d $MYSQL_HOME -g mysql -s /usr/bin/bash mysql
# chown -R mysql:mysql $MYSQL_HOME

  3. Create the database : 

    # su - mysql
$ cd bin
$ ./mysql_install_db

  4. A sample my.cnf file is included in $APP_DIR/etc/my.cnf. This will work with both MySQL 5.0 and 5.1. Copy it to /etc/my.cnf and edit it to add the location of innodb_data_home_dir and innodb_log_group_home_dir. The default values for these parameters is the MySQL data directory. Start the mysql server. 

    $ ./mysqld_safe –defaults-file=/etc/my.cnf &


    
	
  1. Set the root password. Substitute your own password for pwd
	(we typically use adminadmin) 
	
    
	
    $ ./mysqladmin -u root password pwd
    
	
  2. Create the olio user and grant privileges: 
	
    
	
     $ ./mysql -u root -p pwd
 mysql> create user 'olio'@'%' identified by 'olio';
 mysql> grant all privileges on *.* to 'olio'@'%' identified by 'olio';
    
	In some cases the wildcard '%' does not work reliably as a
	substitution for all hosts. You need to grant the privileges to
	'olio'@'<hostname>' individually, where hostname is localhost,
	the name of the database system and any other names that are used to
	access the database system.
    



. 



    
	
  1. Create database: 
	
    
	
    mysql> create database olio;
    
	
  2. In the web application directory, go to the config directory. Copy database.yml.template to database.yml and edit it to set the hostname running the database.
    
	
  3. Create database schema from the rails application :
    



    
	
    cd $APP_DIR; rake db:migrate
    



Loading the database


It is best to load the database manually the first time so that we
can test the web application. However, while doing performance tests,
the load driver can be configured to automatically re-load the
database before the run.


    
	
  1. Login to the machine running the
	Faban master driver. Only this machine has the loader at this time.
    



    
	
  1. Go to the directory containing the loader script: 
	
    
	
    # cd $FABAN_HOME/benchmarks/OlioDriver/bin
    
	
  2. Ensure the script has execute permissions. Faban takes care
	of this for the runs, but since we have not yet started the first
	run, we will need to change that ourselves: 
	
    
	
    # chmod +x dbloader.sh
    
	
  3. Run the loader script: 
	
    
	
    # ./dbloader.sh <dbserver> <load_scale>
You can start small with a SCALE of 50 for initial testing. 
    



Setting up the filestore


Olio can be configured to use a local filesystem or network file
systems such as NFS. You will need about 50GB of space for the data,
as the data does grow over runs. Using a single spindle does work but
may create performance bottlenecks. We recommend striping the
filesystem across at least 3 spindles to avoid such bottlenecks. A
local file system needs to be setup on the same machine as the web
application. A network file system can reside on a separate server
but needs to be exported and mounted on the web application.


    
	
  1. Create a directory (or mount a filesystem) designated for
	storing the image and binary files. This directory is referred to as
	$FILESTORE. Any valid name for the OS should be fine. Ensure that
	everyone has read and write access to it: 
	
    
	
    # mkdir -p $FILESTORE
# chmod a+rwx $FILESTORE
    
	
  2. Now load the filestore. You should have the
	$FABAN_HOME/benchmarks/OlioDriver.jar file on this system.
    
	
    # JAVA_HOME=<java_install_dir>; export $JAVA_HOME
    



      # cd $FABAN_HOME/benchmarks; mkdir olio
      # cd olio; jar xvf ../OlioDriver.jar; chmod a+x bin/*


    
	
    # $FABAN_HOME/benchmarks/olio/bin/fileloader.sh <load_scale> $FILESTORE
This loads files for use for up to load_scale number of concurrent users. 
    
	
  1. In
	$APP_DIR/public/, create a symbolic link from uploaded_files
	to $FILESTORE. 
	
    



            #
ln -s $FILESTORE uploaded_files


Setting up the Geocoder Emulator


The Geocoder Emulator is a simple servlet deployed on Tomcat. It
is typically run on a driver machine. The following steps describe
how to install it :


    
	
  1. Donwload and install Tomcat (from
	http://tomcat.nginx.org) on
	the driver machine. The install directory doesn't matter - we will
	refer to it as $TOMCAT_HOME. 
	
    








    
	
  1. Copy $OLIO_HOME/geocoder.war file
	to $TOMCAT_HOME/webapps. 
	
    








    
	
  1. Start Tomcat using
	$TOMCAT_HOME/bin/startup.sh. 
	
    








    
	
  1. Go to $APP_DIR/config. Edit the file
	environment.rb and change 'localhost' in
	Geolocation.url = '...' to the actual hostname where
	the geocoder emulator is running.
    



Testing the web application



      $ cd $APP_DIR
      $ thin -d -p 3000 -e production -l /var/log/thin.log –-pid /var/run/thin.pid -s 4 start



























Starting a performance test


Now that we know that the web application is running and the faban
harness is up, it is time to kick off a test.


    
	
  1. Point your browser at
	http://<driver_machine>:9980 
	
    
	
  2. Click on the Schedule Run
	link. 
	
    
	
  3. Under the JAVA tab, set the
	JAVA_HOME. You can accept the default value for JVM options. DO
	NOT click on the OK button yet! 
	
    
	
  4. Select the Driver tab. 
	
    









    
	
  1. Select the Web Server tab. 
	
    
	
    The number of Agents is best the same or multiple the number of
	driver machines; we start with 1. The Host:Port Pairs field takes
	the host port pairs where the web applications are running. The host
	and port is separated by a colon. Each pair is separated by space.
	For the Webserver type field, enter either “apache” or
	"lighttpd" or leave the field blank if you're using nginx
	or other servers. Only these two servers are supported by faban at
	this time. Then provide the webserver's bin, log, and config
	directories in the respective fields. Then, in the tools box, type
	the tools you want to run. Here are the tools we typically run :
	vmstat 10; mpstat 10; iostat -x 10
    
	
  2. Select the Data Servers tab. 
	
    
	
    For the database server, enter the Host name. Edit the hostname
	part along of the JDBC Connection URL. This is used by the loader
	program to reload the database before a run. Set the 'Load for
	Concurrent Users' to 25 (this is the minimum number of users we can
	load for and is good for up to 25 concurrent users). You can set the
	loader to run a larger number so that you don't have to edit this
	field every time. However, you must reload the database before every
	run .
    
	
    Set the Data Storage server. For local storage this is the same
	host as the web server.
    
	
  3. That's it. Click OK and the run should be scheduled. You can
	click on the View Results link on the left to monitor the run.