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.
Olio is a macro-level toolkit consisting of the following components:
The web application
The main database
Distributed storage servers (NFS)
Geocoder emulator
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 :
The Olio source is available in the source package (apache-olio-rails-src-<version>.tar) from the Olio Downloads page or via SVN at https://svn.apache.org/repos/asf/incubator/olio/. The source kit offers a stable release and the SVN repository has the latest code. If you choose to use SVN, please see the instructions for downloading the source. We will use $OLIO_HOME to designate the directory where the source is downloaded. The source is organized as follows :
The webapp directory contains the web application. The rails/trunk sub-directory contains the web application for the Rails implementation. We will refer to webapp/rails/trunk as $WEBAPP in this document.
The workload directory contains the code for the load generator/driver (which we typically refer to simply as driver). The driver is implemented using Faban, an open source benchmarking toolkit. The rails/trunk sub-directory has the faban driver code to drive the rails application. In future, we plan to integrate the driver source for all implementations of the application. The workload/rails/trunk directory is referred to as $WORKLOAD in this document.
The geocoder directory contains the code for the geocoder emulator. This code is shared across all implementations of Olio.
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.
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
.
Install the required Faban services:
cd $FABAN_HOME
cp
samples/services/ApacheHttpdService/build/ApacheHttpdService.jar
services
cp samples/services/MysqlService/build/MysqlService.jar
services
cp
samples/services/MemcachedService/build/MemcachedService.jar services
To build the driver, do the following:
cd $WORKLOAD; cp
build.properties.template build.properties
Edit build.properties and set
faban.home to $FABAN_HOME
, faban.url to http://driver_host:9980
where driver_host is the name of the machine where the Faban
master will run. This is usually the driver system.
Set the environment variable JAVA_HOME
to point to your JDK1.6 installation.
$WORKLOAD/lib
directory.Build the driver using the command: ant deploy.jar. If successful, you should see the file OlioDriver.jar in the build sub-directory.
Copy $WORKLOAD/build/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.
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.
Start the faban master on the master
driver machine : $FABAN_HOME/master/bin/startup.sh
Test that you can connect to the master by pointing your browser
at http://
<driver_machine>
:9980.
The web application is a Rails application. It requires the following components:
A web server such as Nginx, Lighttpd or Apache (the instructions below focus on nginx)
Ruby 1.8.6 or higher with the following gems:
rails
rake
thin (mongrel can be used if desired)
mysql
RubyInline
image_science (uses FreeImage which needs to be downloaded and built)
rcov
will_paginate
FreeImage (which needs to be downloaded and built)
MySQL 5 (5.1 recommended)
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:
If you are running on a version of
OpenSolaris before 2009.06, upgrade your Ruby version to the
latest in the pkg.opensolaris.org/dev repository.
You may need to set the environment variable CXX to /usr/sfw/bin/gcc to build eventmachine (a thin dependency). See http://blogs.sun.com/mandy/entry/building_eventmachine_on_opensolaris_and for details.
If running on OpenSolaris before 2009.06, edit /usr/ruby/1.8/lib/ruby/1.8/i386-solaris2.11/rbconfig.rb as follows :
CONFIG["LDSHARED"] = "/usr/sfw/bin/gcc -G"
Download and build FreeImage. See instructions.
To install the mysql gem, run:
gem install mysql --with-mysql-lib=/usr/mysql/lib/mysql --with-mysql-include=/usr/mysql/include
Install nginx. You can build nginx from source by using the Makefile in http://hg.opensolaris.org/sc/src/webstack/nginx/. Alternatively, you can install a pre-built binary following the instructions in
Now install these gems:
gem install rake rails thin rcov will_paginate image_science
Once you have the application stack installed, follow the steps below to set up the application.
Decide where you want to install the web application. For this example we will use /var/app:
$ mkdir /var/app
$ cd /var/app
Copy the contents of $WEBAPP to /var/app/olio. We will use $APP_DIR
to refer to the location: /var/app/olio
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;
#
replace $APP_DIR with whatever
value you used for $APP_DIR throughput the installation
You may need to increase the number of open file descriptors
allowed when running at
larger scales. You can do this by using the command ulimit -n
10240
.
Do NOT start nginx yet.
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.
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
Create the database :
# su - mysql
$ cd bin
$ ./mysql_install_db
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 &
Substitute your own password for pwd (we typically use adminadmin)
$ ./mysqladmin -u root password pwd
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.
Create database:
mysql> create database olio;
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.
Create database schema from the rails application :
cd $APP_DIR; rake db:migrate
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.
Login to the machine running the Faban master driver. Only this machine has the loader at this time.
Go to the directory containing the loader script:
# cd $FABAN_HOME/benchmarks/OlioDriver/bin
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
Run the loader script:
# ./dbloader.sh <dbserver> <load_scale>
You can start small with a SCALE of 50 for initial testing.
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.
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
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 toload_scale
number of concurrent users.
In $APP_DIR/public/, create a symbolic link from uploaded_files
to $FILESTORE.
#
ln -s $FILESTORE uploaded_files
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 :
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
.
Build the geocoder.war file by going to the 'geocoder' directory and following the instructions in the README file.
Copy the geocoder.war file from the geocoder/dist directory to $TOMCAT_HOME/webapps.
Start Tomcat using $TOMCAT_HOME/bin/startup.sh.
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.
Download and install memcached on the system you plan to use.
Start memcached : “memcached -u mysql &”
Start thin:
$ cd $APP_DIR
$ chmod a+x bin/*thin
$ bin/start_thin 4
This will start four thin servers on ports 3000, 3001, 3002, and
3004. You can change the port and number of servers if you want, the nginx.conf
file will need to be modified as well. You can also change to unix
domain sockets by using the --socket option and server
unix:/tmp/projects.0.sock;
for each of the sockets.
Start nginx. Check that you can connect to it from your browser (http://host:80). Check the home page (HomePage). If there are no error messages and all images get loaded, that's a great start! If not, check the rails application log (in $APP_DIR/log), thin and nginx error logs to debug.
Click on an event (EventDetail). Make sure the whole page looks OK.
Click on an attendee (PersonDetail) to see a person's profile.
Go back to the home page and click on a tag in the tag cloud. Choose a big tag and check that we have good results and images get loaded OK.
Click on the sign up tab. Fill in the form and create a user. Make sure you find some jpeg images to upload. If not, take them from $FABAN_HOME/benchmarks/web20/resources. Submit the form. Make sure the form goes through. This completes the AddPerson transaction.
Login using your new login name you just created. The top left of the screen should show that you're logged on.
Select an event, go back to the EventDetail page but this time as a logged on user. Add yourself as an attendee. This is the EventDetail transaction with attendee added (about 8-9% of all EventDetail views).
Click on the add event tab and add
an event. Make sure to include an image and some literature. You can
also use the files from $FABAN_HOME/benchmarks/web20/resources
.
Fill in the form and submit. This is the AddEvent transaction.
Now that we know that the web application is running and the faban harness is up, it is time to kick off a test.
Point your browser at http://<driver_machine>:9980
Click on the Schedule Run link.
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!
Select the Driver tab.
Select the Web Server tab.
Proxy Server Section
App Server Section
Select the Data Servers tab.
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.