Note: The application currently does not use memcached. Please ignore the memcached related setup instructions.
Olio is a macro-level toolkit consisting of the following components:
The web application
The main database
Distributed storage servers (MogileFS or NFS)
Storage metadata database (for MogileFS)
Geocoder emulator
Workload driver
If your primary interest is in setting up the application alone, you need items 1-5 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 (apache/php).
In the following sections, we will go over the steps needed to configure each component :
Downloading the source
Installing the Web Application
Setting up the Geocoder Emulator
The Olio source is available via SVN at https://svn.apache.org/repos/asf/incubator/olio/. 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 php/trunk sub-directory contains the web application for the PHP implementation. We will refer to webapp/php/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 php/trunk sub-directory has the faban driver code to drive the php application. In future, we'd like to integrate the driver source for all implementations of the application. The workload/workload/php/trunk is referred to as $WORKLOAD in this document.
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 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.
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.
Build the driver using the command: ant deploy.jar. If successful, you should see the file Web20Driver.jar in the build sub-directory.
Copy $WORKLOAD/build/Web20Driver.jar to the $FABAN_HOME/benchmarks directory.
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 PHP application. It requires the following components:
A web server such as Apache or Lighttpd
PHP 5 with extensions: curl.so, gd.so, pdo.so, pdo_mysql.so
MySQL 5
Coolstack is one pre-integrated suite of open source applications
optimized for Solaris. If you're running on any other operating
system, please install the above applications.
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. The default for apache is the htdocs sub-directory but a common location is /var/www. Create a sub-directory web20php2 where the php application will reside. We will use $APP_DIR to refer to this location.
After installing all the above packages, go to /opt/coolstack/apache2/conf and edit the httpd.conf. Set the Listen parameter to the hostname or ip address and set the DocumentRoot to $APP_DIR/public_html. An example httpd.conf is provided in $APP_DIR/etc.
An example, tuned php.ini is provided in $APP_DIR/etc/php.ini. Copy the non-installation specific settings to the location where php.ini exists for your installation. For Cool Stack users, you can copy this file as is to /opt/coolstack/php5/lib.
Go to $APP_DIR/etc. Edit the file config.php and set the appropriate values for geocoderHost, localfsRoot. localfsRoot is the directory where the object filestore resides (either a local filesystem or nfs-mounted from a remote location – see the section on Setting up the filestore below). The default location is /filestore. The geocoderHost is usually the driver system.
Start apache. Check that you can connect to it from your browser (http://host:8080), but don't try to access any of the application pages 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
Start the mysql server. Substitute your own password for pwd
(we typically use
adminadmin)
$ ./mysqld_safe
&
$ ./mysqladmin -u root
password pwd
Create the web20 user and grant privileges:
$
./mysql -uroot -ppwd
mysql>
create user 'web20'@'%' identified by 'web20';
mysql>
grant all privileges on *.* to 'web20'@'%' identified by 'web20'
with grant option;
In some cases the wildcard '%' does
not work reliably as a substitution for all hosts. You need to grant
the privileges to 'web20'@'<hostname>' individually, where
hostname are the names of the driver and apache systems.
Create database
mysql>
create database web20load;
mysql>
use web20load;
Create database schema by logging in as mysql root user and
running the schema.sql script from either
$FABAN_HOME/benchmarks/Web20Driver/bin or $APP_DIR/etc:
mysql>
\.<location>/schema.sql
mysql>
exit
$
Now, if you
login as the user web20, you should be able to see the database
created by the root user.
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/Web20Driver/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 either a local filesystem or MogileFS for the object data. Our initial testing with MogileFS found some severe performance issues, so for now we advice using 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 :
#
cd $FILESTORE
#
JAVA_HOME=<java_install_dir>;
export $JAVA_HOME
#
$FABAN_HOME/benchmarks/web20/bin/fileloader.sh <load_scale>
This loads files for use for up to load_scale number of concurrent users.
Ensure the $APP_DIR/etc/config.php parameter localfsRoot is pointing to <filestore>.
The Geocoder Emulator is a simple J2EE application deployed on Tomcat. It is typically run on a driver machine. The following steps describe how to install it :
Donwload and install Tomcat (either from Cool Stack CSKtomcat package for Solaris or directly from http://tomcat.apache.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.
Check the home page (HomePage) http://<web_server>:8080/index.php . If there are no error messages and all images get loaded, that's a great start !
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 right 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.
Kill memcached. Memcached is always started by the driver before the run to ensure a clean cache and will cause port conflicts if it is already running.
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.
Enter a Description for the run (say 'First test run' for this case). In general, the Description field is very useful to get a quick idea of what a particular run is testing.
Enter the name of your driver(s) machine for Host (when using more than one machine, simply separate them by a space).
Enter 10 for 'Concurrent Users' (we want to start small).
Enter 'vmstat 10' for Tools. This indicates the measurement tools that will be run on the driver machine. It's a good idea to keep an eye on the driver cpu utilization.
Now enter 30, 30, 30 for the Ramp up, Steady State and Ramp down times. This is a very short test run. For normal runs, you may need a ramp up of 200 seconds and a steady state of at least 600 seconds during which measurements are made.
For current systems, the time between client startup of 200 milliseconds is good enough. Some web servers or slower systems may not be able to accept connections very frequently. In that case we may want to increase this value to 1000 milliseconds.
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" dependent on which web server you're using, or leave the field blank if you're using servers other than these two. Only these two servers are supported at this time. Then provide the webserver's bin, log, and config directories, and the directory containing the php.ini file in the respective fields. Next, choose the server type to be PHP, if it is not already that way. 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
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. It is not absolutely necessary to reload the database and files every time, but you should do so for all performance runs. In that case, set the reload fields to true every time.
Set the Data Storage server. For local storage this is the same host as the web server.
Set the memcached server instances to the servers you've configured in config.php of the web application. The driver harness will start the memcached server instances accordingly. Note that the memcached server instances are given as host:port pairs, separated by space. If a port is not given, the default memcached port of 11211 is assumed.
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.