You are viewing a plain text version of this content. The canonical link for it is here.
Posted to olio-commits@incubator.apache.org by sh...@apache.org on 2009/03/17 23:40:05 UTC
svn commit: r755446 - in /incubator/olio/docs: app_spec.html php_setup.html
php_setup_kit.html rails_setup.html rails_setup_kit.html
Author: shanti
Date: Tue Mar 17 23:40:05 2009
New Revision: 755446
URL: http://svn.apache.org/viewvc?rev=755446&view=rev
Log:
Adding rails setup from kit, Fixed both rails files to add more detail, added license info for all files, minor corrections to others.
Added:
incubator/olio/docs/rails_setup_kit.html
Modified:
incubator/olio/docs/app_spec.html
incubator/olio/docs/php_setup.html
incubator/olio/docs/php_setup_kit.html
incubator/olio/docs/rails_setup.html
Modified: incubator/olio/docs/app_spec.html
URL: http://svn.apache.org/viewvc/incubator/olio/docs/app_spec.html?rev=755446&r1=755445&r2=755446&view=diff
==============================================================================
--- incubator/olio/docs/app_spec.html (original)
+++ incubator/olio/docs/app_spec.html Tue Mar 17 23:40:05 2009
@@ -1,6 +1,24 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=iso-8859-1">
<TITLE>Web20Kit Application Specifications</TITLE>
<META NAME="GENERATOR" CONTENT="StarOffice 8 (Solaris Sparc)">
@@ -299,4 +317,4 @@
</P>
</DIV>
</BODY>
-</HTML>
\ No newline at end of file
+</HTML>
Modified: incubator/olio/docs/php_setup.html
URL: http://svn.apache.org/viewvc/incubator/olio/docs/php_setup.html?rev=755446&r1=755445&r2=755446&view=diff
==============================================================================
--- incubator/olio/docs/php_setup.html (original)
+++ incubator/olio/docs/php_setup.html Tue Mar 17 23:40:05 2009
@@ -7,7 +7,25 @@
<META NAME="AUTHOR" CONTENT="Akara Sucharitakul">
<META NAME="CREATED" CONTENT="20070926;10111500">
<META NAME="CHANGEDBY" CONTENT="Shanti Subramanyam">
- <META NAME="CHANGED" CONTENT="20090311;9351100">
+ <META NAME="CHANGED" CONTENT="20090316;12552900">
+ <!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+ <META NAME="CHANGEDBY" CONTENT="Shanti Subramanyam">
<META NAME="CHANGEDBY" CONTENT="Shanti Subramanyam">
<STYLE TYPE="text/css">
<!--
@@ -83,10 +101,9 @@
The driver is implemented using <A HREF="http://faban.sunsource.net/"><I>Faban</I></A>
â an open source benchmarking toolkit. The <I>php/trunk</I>
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
- <I>workload/workload/php/trunk</I> is referred to as $WORKLOAD in
- this document.</P>
+ application. In future, we plan to integrate the driver source for
+ all implementations of the application. The <I>workload/php/trunk</I>
+ directory is referred to as $WORKLOAD in this document.</P>
<LI><P>The <I>geocoder</I> directory contains the code for the
geocoder emulator. This code is shared across all implementations of
Olio.</P>
@@ -108,8 +125,8 @@
</OL>
<UL>
<UL>
- <LI><P ALIGN=LEFT>cd $WORKLOAD; cp build.properties.template
- build.properties</P>
+ <LI><P ALIGN=LEFT><FONT FACE="Cumberland, monospace"><FONT SIZE=3>cd
+ $WORKLOAD; cp build.properties.template build.properties</FONT></FONT></P>
<LI><P ALIGN=LEFT>Edit build.properties and set faban.home to
$FABAN_HOME, faban.url to http://<I>driver_host</I>:9980 where
<I>driver_host</I> is the name of the machine where the Faban
@@ -123,10 +140,10 @@
</UL>
</UL>
<OL START=3>
- <LI><P ALIGN=LEFT>Copy $WORKLOAD/build/Olio<SPAN STYLE="font-weight: medium">Driver</SPAN><I><SPAN STYLE="font-weight: medium">.</SPAN></I><SPAN STYLE="font-style: normal"><SPAN STYLE="font-weight: medium">jar</SPAN></SPAN>
- to the $FABAN_HOME/benchmarks directory. IAlso copy the
- OlioDriver.jar file to the $FABAN_HOME/benchmarks directory on the
- web server system.</P>
+ <LI><P ALIGN=LEFT>Copy <FONT FACE="Cumberland, monospace">$WORKLOAD/build/Olio</FONT><FONT FACE="Cumberland, monospace"><SPAN STYLE="font-weight: medium">Driver</SPAN></FONT><FONT FACE="Cumberland, monospace"><I><SPAN STYLE="font-weight: medium">.</SPAN></I></FONT><FONT FACE="Cumberland, monospace"><SPAN STYLE="font-style: normal"><SPAN STYLE="font-weight: medium">jar</SPAN></SPAN></FONT>
+ to the <FONT FACE="Cumberland, monospace">$FABAN_HOME/benchmarks</FONT>
+ directory. Also copy the OlioDriver.jar file to the
+ $FABAN_HOME/benchmarks directory on the web server system.</P>
<LI><P ALIGN=LEFT>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.</P>
<LI><P ALIGN=LEFT>Start the faban master on the master driver
@@ -145,7 +162,7 @@
Lighttpd</P>
<LI><P STYLE="margin-bottom: 0in">PHP 5 with extensions: apc.so,
curl.so, gd.so, pdo_mysql.so</P>
- <LI><P STYLE="margin-bottom: 0in">MySQL 5</P>
+ <LI><P STYLE="margin-bottom: 0in">MySQL 5 (5.1 recommended)</P>
<LI><P STYLE="margin-bottom: 0in">Memcached
</P>
</OL>
@@ -240,6 +257,8 @@
containing the loader script:<BR></FONT><FONT FACE="monospace"><FONT SIZE=3>#
cd </FONT></FONT><FONT FACE="monospace"><I>$FABAN_HOME</I></FONT><FONT FACE="monospace">/benchmarks/OlioDriver/bin</FONT></P>
</OL>
+<P STYLE="margin-bottom: 0in"><BR>
+</P>
<OL START=3>
<LI><P STYLE="margin-bottom: 0in">Ensure the script has execute
permissions. Faban takes care of this for the runs, but since we
Modified: incubator/olio/docs/php_setup_kit.html
URL: http://svn.apache.org/viewvc/incubator/olio/docs/php_setup_kit.html?rev=755446&r1=755445&r2=755446&view=diff
==============================================================================
--- incubator/olio/docs/php_setup_kit.html (original)
+++ incubator/olio/docs/php_setup_kit.html Tue Mar 17 23:40:05 2009
@@ -7,7 +7,26 @@
<META NAME="AUTHOR" CONTENT="Akara Sucharitakul">
<META NAME="CREATED" CONTENT="20070926;10111500">
<META NAME="CHANGEDBY" CONTENT="Shanti Subramanyam">
- <META NAME="CHANGED" CONTENT="20090311;9350500">
+ <META NAME="CHANGED" CONTENT="20090316;13122800">
+ <META NAME="CHANGEDBY" CONTENT="Shanti Subramanyam">
+ <!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+ <META NAME="CHANGEDBY" CONTENT="Shanti Subramanyam">
<STYLE TYPE="text/css">
<!--
H1 { color: #000000 }
@@ -65,13 +84,12 @@
<P><A HREF="#startRun">Starting a performance test</A></P>
<H2><A NAME="Contents"></A>Extracting the Contents</H2>
<P>The Olio/PHP kit is packaged as a gzipped tar file. The first task
-is to unzip the file and untar it to extract it's contents. This can
-be done as follows:</P>
+is to unzip the file and untar it to extract it's contents. Because
+of the long pathnames, please use gtar to extract. This can be done
+as follows:</P>
<P><FONT FACE="Courier New, monospace"><FONT SIZE=2 STYLE="font-size: 11pt">#
-gzcat <I>olio-php-<version>b<build_date></I>.tar.gz | tar
-xvf -</FONT></FONT></P>
-<P>This will cause a directory named
-olio-php-<I><version></I>b<I><build_date></I><SPAN STYLE="font-style: normal">to
+gzcat <I>olio-php-<version></I>.tar.gz | gtar xvf -</FONT></FONT></P>
+<P>This will cause a directory named olio-php-<I><version> </I><SPAN STYLE="font-style: normal">to
be created whose contents should look like:</SPAN></P>
<P STYLE="margin-bottom: 0.04in; font-style: normal"><FONT FACE="Courier New, monospace"><FONT SIZE=2 STYLE="font-size: 11pt">#
ls olio-php-0.1*</FONT></FONT></P>
@@ -283,8 +301,8 @@
$FILESTORE</I></FONT></FONT>
</P>
<OL START=2>
- <P><FONT SIZE=3>This loads files for use for up to </FONT><FONT FACE="monospace"><FONT SIZE=3><I>load_scale</I></FONT></FONT><FONT SIZE=3>
- number of active users.</FONT></P>
+ <P><FONT SIZE=3>This loads files for use for up to </FONT><FONT FACE="monospace"><FONT SIZE=3><I>load_scale</I></FONT></FONT>
+ <FONT SIZE=3>number of active users.</FONT></P>
<LI><P><FONT SIZE=3>Edit the $APP_DIR/etc/config.php parameter
</FONT><I>localfsRoot</I> and set it to $FILESTORE.
</P>
Modified: incubator/olio/docs/rails_setup.html
URL: http://svn.apache.org/viewvc/incubator/olio/docs/rails_setup.html?rev=755446&r1=755445&r2=755446&view=diff
==============================================================================
--- incubator/olio/docs/rails_setup.html (original)
+++ incubator/olio/docs/rails_setup.html Tue Mar 17 23:40:05 2009
@@ -1,647 +1,540 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
-<html>
-<head>
- <meta name="generator" content=
- "HTML Tidy for Mac OS X (vers 31 October 2006 - Apple Inc. build 13), see www.w3.org">
- <meta http-equiv="CONTENT-TYPE" content=
- "text/html; charset=us-ascii">
-
- <title>Olio/Rails Install and Setup Guide</title>
- <meta name="GENERATOR" content="NeoOffice 2.2 (Unix)">
- <meta name="AUTHOR" content="Akara Sucharitakul">
- <meta name="CREATED" content="20070926;10111500">
- <meta name="CHANGED" content="20081014;13423500">
- <style type="text/css">
- <!--
- h1 { text-align: center; }
- ol li { padding-bottom: 1em; }
- ul li { padding-bottom: 1em; }
- ol ul li { padding-bottom: 0em; }
- pre { margin-bottom: 0; }
- -->
- </style>
-</head>
-
-<body lang="en-US" text="#000000" dir="ltr">
- <h1>Olio/Rails<br>
- Install and Setup Guide from Source Tree</h1>
-
- <p>Note: The application currently does not use memcached. Please
- ignore the memcached related setup instructions.</p>
-
- <h2>Overview</h2>
-
- <p>Olio is a macro-level toolkit consisting of the following
- components:</p>
-
- <ol>
- <li>The web application</li>
-
- <li>The main database</li>
-
- <li>Distributed storage servers (MogileFS or NFS)</li>
-
- <li>Storage metadata database (for MogileFS)</li>
-
- <li>Geocoder emulator</li>
-
- <li>Workload driver</li>
- </ol>
-
- <p>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.</p>
-
- <p>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).</p>
-
- <p>In the following sections, we will
- go over the steps needed to configure each component :</p>
-
- <ul>
- <li><a href="#downloading">Downloading the source</a></li>
-
- <li><a href="#setupDriver">Setting up the driver</a></li>
-
- <li><a href="#installWebApp">Installing the Web
- Application</a></li>
-
- <li><a href="#setupDB">Setting up the database</a></li>
-
- <li><a href="#loadDB">Loading the database</a></li>
-
- <li><a href="#setupFileStore">Setting up the filestore</a></li>
-
- <li><a href="#setupEmulator">Setting up the Geocoder
- Emulator</a></li>
-
- <li><a href="#testWebApp">Testing the web application</a></li>
-
- <li><a href="#startRun">Starting a performance test</a></li>
- </ul>
-
- <h2 id="downloading">Downloading The Source</h2>
-
- <p>The Olio source is available via SVN at <a href=
- "https://svn.apache.org/repos/asf/incubator/olio/">https://svn.apache.org/repos/asf/incubator/olio/</a>.
- Please see the <a href=
- "http://www.apache.org/dev/version-control.html#anon-svn">instructions</a>
- for downloading the source. We will use $OLIO_HOME to designate
- the directory where the source is downloaded. The source is
- organized as follows :</p>
-
- <ul>
- <li>
- The <i>webapp</i> 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.
- </li>
-
- <li>
- The <i>workload</i> directory contains the code for the
- load generator/driver (which we typically refer to simply as
- <i>driver</i>). The driver is implemented using <a href=
- "http://faban.sunsource.net/"><i>Faban</i></a> ? 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/rails/trunk is referred to as $WORKLOAD in
- this document.
- </li>
- </ul>
-
- <h2 id="setupDriver">Setting up the driver</h2>
-
- <p>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.</p>
-
- <ol>
- <li>
- See <a href="http://faban.sunsource.net/docs/guide/harness/install.html">
- http://faban.sunsource.net/docs/guide/harness/install.html</a>
- for Faban installation instructions. Note that faban needs to
- be installed on all the machines used for the test. Please
- also read the <i>Getting Started Guide</i> 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 <code>$FABAN_HOME</code>.
- </li>
-
- <li>To build the driver, do the following:
- <ul>
- <li><code>cd $WORKLOAD; cp build.properties.template build.properties</code></li>
-
- <li>Edit build.properties and set faban.home to
- <code>$FABAN_HOME</code>, faban.url to http://<i>driver_host</i>:9980
- where <i>driver_host</i> is the name of the machine where
- the Faban master will run. This is usually the driver
- system.
- </li>
-
- <li> Set the environment variable <code>JAVA_HOME</code> to
- point to your JDK1.6 installation.
- </li>
-
- <li> Build the driver using the command: <i>ant
- deploy.jar.</i> If successful, you should see the file
- <i>Web20Driver.jar</i> in the<i>build</i>sub-directory.
- </li>
- </ul>
- </li>
- <li>Copy <code>$WORKLOAD/build/Web20Driver.jar</code> to the
- <code>$FABAN_HOME/benchmarks</code> directory.
- </li>
-
- <li>
- For the driver to work, you will need JDK
- 1.6. Set <code>JAVA_HOME</code> to the path of the JDK in the faban user's
- environment.
- </li>
-
- <li> Start the faban master on the master driver
- machine :<br/>
- <code>$FABAN_HOME/master/bin/startup.sh</code>
- </li>
-
- <li>
- Test that you can connect to the master by
- pointing your browser at <code>http://<i><driver_machine></i>:9980</code>
- </li>
- </ol>
-
- <h2 id="installWebApp">Installing the Web Application</h2>
-
- <p>The web application is a Rails application. It requires the
- following components:</p>
-
- <ol>
- <li>
- A web server such as Nginx or Apache
- </li>
-
- <li>
- Ruby 1.8.6 or higher with the following gems:
- <ul>
- <li>rails</li>
- <li>thin (mongrel can be used if desired)</li>
- <li>mysql</li>
- </ul>
- </li>
-
- <li>
- MySQL 5
- </li>
- </ol>
-
- <p>For Linux (debian or ubunu), Install the following packages:</p>
- <pre> aptitude install build-essential subversion ruby1.8 ruby1.8-dev nginx libmysqlclient-dev rubygems libgems-ruby1.8</pre>
- </p>
-
- <p>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.</p>
-
-<p>Once you have the application stack installed, follow the steps
- below to set up the application.</p>
-
- <ol>
- <li>
- Decide where you want to install the web application. For this example
- we will use /var/app:
-<pre>
-$ mkdir /var/app
-$ cd /var/app
-</pre>
- </li>
-
- <li>
- Checkout the Olio rails branch.
- <pre>
-$ svn co https://svn.apache.org/repos/asf/incubator/olio/webapp/rails/trunk olio
- </pre>
-
- We will use <code>$APP_DIR</code> to refer to the location: <code>/var/app/olio</code>
- </li>
-
- <li>
- After installing all the above packages, go to
- and edit the 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 <code>/usr/local/nginx/conf</code>.
-
- <p>To change to user to another user, modify the first line and change
- <code>user root;</code> to your perferred user. If you have more than
- one machine hosting your thins, modify the upstream thin and add the
- addresses of your application servers.</p>
-
- <p>To change the location of the application static content, change the
- line <code>root /var/app/olio/public;</code> to <code>root $APP_DIR;</code>
- </p>
-
- Wait until the next step before starting nginx.
- </li>
-
- <li>
- Create a symbolic link from the filestore location to the following location:
- <code>$APP_DIR/public/uploaded_files</code>. Olio will look for and add all
- files in this location. These locations can also be changed in the environment.rb
- by modifying the values of <code>IMAGE_STORE_PATH</code> and
- <code>DOCUMENT_STORE_PATH</code>.
- </li>
-
- <li>
- Go to <code>$APP_DIR/config</code>. Edit the file <code>config/environment.rb</code>
- and set the <code>Geolocation.url = '...'</code> to the location of
- the Geocoder.
- <p>
- </p>
- </li>
-
- <li>
- Start thin:
- <pre>
-$ cd $APP_DIR
-$ thin -d -p 3000 -e production -s 4</pre>
- <p>
- 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
- <code>nginx.conf</code> file will need to be modified as well. You can
- also change to unix domain sockets by using the --socket option and
- <code>server unix:/tmp/projects.0.sock;</code> for each of the sockets.
- </p>
- </li>
-
- <li>
- Start nginx. Check that you can connect to it from your
- browser (http://<i>host</i>:80), but don't try to access
- any of the application pages yet !
- </li>
- </ol>
-
- <h2 id="setupDB">Setting up the database</h2>
-
- <ol>
- <li>
- 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.
- </li>
-
- <li>
- Setup the mysql user/group and permissions for it's
- directories:
- <pre>
-# groupadd mysql
-# useradd -d $MYSQL_HOME -g mysql -s
-/usr/bin/bash mysql
-# chown -R mysql:mysql $MYSQL_HOME</pre>
- </li>
-
- <li>
- Create the database :
- <pre>
-# su - mysql
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<HTML>
+<HEAD>
+ <META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=utf-8">
+ <TITLE>Olio/Rails Install and Setup Guide</TITLE>
+ <META NAME="GENERATOR" CONTENT="StarOffice 8 (Solaris Sparc)">
+ <META NAME="AUTHOR" CONTENT="Akara Sucharitakul">
+ <META NAME="CREATED" CONTENT="20070926;10111500">
+ <META NAME="CHANGEDBY" CONTENT="Shanti Subramanyam">
+ <META NAME="CHANGED" CONTENT="20090316;13050200">
+ <META NAME="CHANGEDBY" CONTENT="Shanti Subramanyam">
+ <!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+ -->
+ <STYLE TYPE="text/css">
+ <!--
+ H1 { color: #000000; text-align: center }
+ P { color: #000000 }
+ PRE { color: #000000 }
+ H2 { color: #000000 }
+ -->
+ </STYLE>
+</HEAD>
+<BODY LANG="en-US" TEXT="#000000" DIR="LTR">
+<H1>Olio/Rails<BR>Install and Setup Guide from Source Tree</H1>
+<P>Note: The application currently does not use memcached. Please
+ignore the memcached related setup instructions.</P>
+<H2>Overview</H2>
+<P>Olio is a macro-level toolkit consisting of the following
+components:</P>
+<OL>
+ <LI><P STYLE="margin-bottom: 0in">The web application
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">The main database
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">Distributed storage servers (NFS)
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">Geocoder emulator
+ </P>
+ <LI><P>Workload driver
+ </P>
+</OL>
+<P>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.</P>
+<P>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).</P>
+<P>In the following sections, we will go over the steps needed to
+configure each component :</P>
+<UL>
+ <LI><P STYLE="margin-bottom: 0in"><A HREF="#downloading">Downloading
+ the source</A>
+ </P>
+ <LI><P STYLE="margin-bottom: 0in"><A HREF="#setupDriver">Setting up
+ the driver</A>
+ </P>
+ <LI><P STYLE="margin-bottom: 0in"><A HREF="#installWebApp">Installing
+ the Web Application</A>
+ </P>
+ <LI><P STYLE="margin-bottom: 0in"><A HREF="#setupDB">Setting up the
+ database</A>
+ </P>
+ <LI><P STYLE="margin-bottom: 0in"><A HREF="#loadDB">Loading the
+ database</A>
+ </P>
+ <LI><P STYLE="margin-bottom: 0in"><A HREF="#setupFileStore">Setting
+ up the filestore</A>
+ </P>
+ <LI><P STYLE="margin-bottom: 0in"><A HREF="#setupEmulator">Setting
+ up the Geocoder Emulator</A>
+ </P>
+ <LI><P STYLE="margin-bottom: 0in"><A HREF="#testWebApp">Testing the
+ web application</A>
+ </P>
+ <LI><P><A HREF="#startRun">Starting a performance test</A>
+ </P>
+</UL>
+<H2><A NAME="downloading"></A>Downloading The Source</H2>
+<P>The Olio source is available via SVN at
+<A HREF="https://svn.apache.org/repos/asf/incubator/olio/">https://svn.apache.org/repos/asf/incubator/olio/</A>.
+Please see the <A HREF="http://www.apache.org/dev/version-control.html#anon-svn">instructions</A>
+for downloading the source. We will use $OLIO_HOME to designate the
+directory where the source is downloaded. The source is organized as
+follows :</P>
+<UL>
+ <LI><P STYLE="margin-bottom: 0in">The <I>webapp</I> 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.</P>
+</UL>
+<P STYLE="margin-bottom: 0in"><BR>
+</P>
+<UL>
+ <LI><P>The <I>workload</I> directory contains the code for the load
+ generator/driver (which we typically refer to simply as <I>driver</I>).
+ The driver is implemented using <A HREF="http://faban.sunsource.net/"><I>Faban,</I></A>
+ 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 <I>workload/rails/trunk</I> directory is
+ referred to as $WORKLOAD in this document.</P>
+</UL>
+<UL>
+ <LI><P>The <I>geocoder</I> directory contains the code for the
+ geocoder emulator. This code is shared across all implementations of
+ Olio.</P>
+</UL>
+<H2><A NAME="setupDriver"></A>Setting up the driver</H2>
+<P>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.</P>
+<OL>
+ <LI><P STYLE="margin-bottom: 0in">See
+ <A HREF="http://faban.sunsource.net/docs/guide/harness/install.html">http://faban.sunsource.net/docs/guide/harness/install.html</A>
+ for Faban installation instructions. Note that faban needs to be
+ installed on all the machines used for the test. Please also read
+ the <I>Getting Started Guide</I> 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 <CODE>$FABAN_HOME</CODE>.
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">To build the driver, do the
+ following:
+ </P>
+ <UL>
+ <LI><P STYLE="margin-bottom: 0in"><CODE>cd $WORKLOAD; cp
+ build.properties.template build.properties</CODE>
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">Edit build.properties and set
+ faban.home to <CODE>$FABAN_HOME</CODE>, faban.url to
+ http://<I>driver_host</I>:9980 where <I>driver_host</I> is the name
+ of the machine where the Faban master will run. This is usually the
+ driver system.
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">Set the environment variable
+ <CODE>JAVA_HOME</CODE> to point to your JDK1.6 installation.
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">Build the driver using the
+ command: <I>ant deploy.jar.</I> If successful, you should see the
+ file Olio<I>Driver.jar</I> in the <I>build </I>sub-directory.
+ </P>
+ </UL>
+ <LI><P STYLE="margin-bottom: 0in">Copy
+ <CODE>$WORKLOAD/build/OlioDriver.jar</CODE> to the
+ <CODE>$FABAN_HOME/benchmarks</CODE> directory. Also copy the
+ OlioDriver.jar file to the $FABAN_HOME/benchmarks directory on the
+ system that will run the rails application.
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">For the driver to work, you will
+ need JDK 1.6. Set <CODE>JAVA_HOME</CODE> to the path of the JDK in
+ the faban user's environment.
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">Start the faban master on the
+ master driver machine : <CODE>$FABAN_HOME/master/bin/startup.sh</CODE>
+ </P>
+ <LI><P>Test that you can connect to the master by pointing your
+ browser at <CODE>http://</CODE><CODE><I><driver_machine></I></CODE><CODE>:9980</CODE>
+ </P>
+</OL>
+<H2><A NAME="installWebApp"></A>Installing the Web Application</H2>
+<P>The web application is a Rails application. It requires the
+following components:</P>
+<OL>
+ <LI><P STYLE="margin-bottom: 0in">A web server such as Nginx,
+ Lighttpd or Apache (the instructions below focus on nginx)</P>
+ <LI><P STYLE="margin-bottom: 0in">Ruby 1.8.6 or higher with the
+ following gems:
+ </P>
+ <UL>
+ <LI><P STYLE="margin-bottom: 0in">rails
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">thin (mongrel can be used if
+ desired)
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">mysql</P>
+ <LI><P STYLE="margin-bottom: 0in">image_science</P>
+ <LI><P STYLE="margin-bottom: 0in">rcov</P>
+ <LI><P STYLE="margin-bottom: 0in">will_paginate</P>
+ <LI><P STYLE="margin-bottom: 0in">FreeImage</P>
+ </UL>
+</OL>
+<P STYLE="margin-left: 0.79in; margin-bottom: 0in"><BR>
+</P>
+<OL START=3>
+ <LI><P>MySQL 5 (5.1 recommended)</P>
+</OL>
+<P>For Linux (debian or ubunu), the following command can be used:</P>
+<PRE STYLE="margin-bottom: 0.2in"> aptitude install build-essential subversion ruby1.8 ruby1.8-dev nginx libmysqlclient-dev rubygems libgems-ruby1.8</PRE><P STYLE="margin-bottom: 0in">
+For OpenSolaris 2008.11:</P>
+<UL>
+ <LI><P STYLE="margin-bottom: 0in">Upgrade your Ruby version to the
+ latest in the pkg.opensolaris.org/dev repository. This will give you
+ Rubygems 1.3.1 and Ruby 1.8.7p72.
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">Since some of the gems install in
+ /usr/local, edit
+ <FONT FACE="Cumberland, monospace">/usr/ruby/1.8/lib/ruby/1.8/i386-solaris2.11/rbconfig.rb</FONT>
+ as follows :</P>
+</UL>
+<P STYLE="margin-left: 0.79in; margin-bottom: 0in">CONFIG[CFLAGS] =
+"-g -O3 -fPIC -R/usr/local/libâ</P>
+<P STYLE="margin-left: 0.79in; margin-bottom: 0in">CONFIG["LDFLAGS"]
+= "-L/usr/sfw/lib -R/usr/sfw/lib -R/usr/local/lib"</P>
+<P STYLE="margin-left: 0.79in; margin-bottom: 0in">CONFIG["LDSHARED"]
+= "gcc -G"</P>
+<UL>
+ <LI><P STYLE="margin-bottom: 0in">Install nginx following the
+ instructions in
+ </P>
+ <P STYLE="margin-bottom: 0in"><A HREF="http://blogs.sun.com/jyrivirkki/entry/nginx_package_updates">http://blogs.sun.com/jyrivirkki/entry/nginx_package_updates</A></P>
+</UL>
+<P STYLE="margin-bottom: 0in"><BR>
+</P>
+<P STYLE="margin-bottom: 0in"><BR>
+</P>
+<P>Once you have the application stack installed, follow the steps
+below to set up the application.</P>
+<OL>
+ <LI><P>Decide where you want to install the web application. For
+ this example we will use /var/app:
+ </P>
+ <PRE>$ mkdir /var/app
+$ cd /var/app</PRE>
+ <LI><P>Copy the contents of $WEBAPP to /var/app/olio. We will use
+ <CODE>$APP_DIR</CODE> to refer to the location: <CODE>/var/app/olio</CODE>
+ </P>
+ <LI><P>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.</P>
+ <P>To change user to another user, modify the first line and change
+ <CODE>user root;</CODE> to your preferred user. If you have more
+ than one machine hosting your thins, modify the upstream thin and
+ add the addresses of your application servers.</P>
+ <P STYLE="margin-bottom: 0.04in">To change the location of the
+ application static content :</P>
+</OL>
+<P STYLE="margin-bottom: 0.04in"><CODE>#### Replace with the full
+path to your rails app's public directory: </CODE>
+</P>
+<PRE STYLE="margin-bottom: 0.2in"><CODE> root /var/www/virtual/example.com/rails/railsapp/public;</CODE></PRE><P STYLE="margin-bottom: 0.04in">
+to <CODE>root $APP_DIR;</CODE>
+</P>
+<OL START=3>
+ <P STYLE="margin-bottom: 0.14in">Wait until the next step before
+ starting nginx.
+ </P>
+</OL>
+<P STYLE="margin-bottom: 0in"><BR>
+</P>
+<OL START=4>
+ <LI><P>Start thin:
+ </P>
+ <PRE>$ cd $APP_DIR
+$ thin -d -p 3000 -e production -s 4</PRE><P>
+ 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
+ <CODE>nginx.conf</CODE> file will need to be modified as well. You
+ can also change to unix domain sockets by using the --socket option
+ and <CODE>server unix:/tmp/projects.0.sock;</CODE> for each of the
+ sockets.
+ </P>
+ <LI><P>Start nginx. Check that you can connect to it from your
+ browser (http://<I>host</I>:80), but don't try to access any of the
+ application pages yet !
+ </P>
+</OL>
+<H2><A NAME="setupDB"></A>Setting up the database</H2>
+<OL>
+ <LI><P STYLE="margin-bottom: 0in">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.
+ </P>
+ <LI><P>Setup the mysql user/group and permissions for it's
+ directories:
+ </P>
+ <PRE># groupadd mysql
+# useradd -d $MYSQL_HOME -g mysql -s /usr/bin/bash mysql
+# chown -R mysql:mysql $MYSQL_HOME</PRE>
+ <LI><P>Create the database :
+ </P>
+ <PRE># su - mysql
$ cd bin
-$ ./mysql_install_db</pre>
- </li>
-
- <li>
- Start the mysql server. Substitute your own password for
- <i>pwd</i> (we typically use <i>adminadmin</i>)
- <pre>
-$ ./mysqld_safe &
-$ ./mysqladmin -u root password <i>pwd</i></pre>
- </li>
-
- <li>
- Create the web20 user and grant privileges:
- <pre>
- $ ./mysql -u root -p <i>pwd</i>
- mysql> create user 'web20'@'%' identified by 'web20';
- mysql> grant all privileges on *.* to 'web20'@'%' identified by 'web20' with grant option;
-
-</pre>
- 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 nginx systems.
- </li>
-
- <li>
- Create database:
- <pre>
-mysql> create database web20load;
-mysql> use web20load;</pre>
- </li>
-
- <li>
- Create database schema by logging in as mysql root user
- Now, if you login as the user web20, you should be able to
- see the database created by the root user.
- <pre>
-rake db:migrate</pre>
- </li>
- </ol>
-
- <h2 id="loadDB">Loading the database</h2>
-
- <p>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.</p>
-
- <ol>
- <li>
- Login to the machine running the Faban
- master driver. Only this machine has the loader at this
- time.
- </li>
-
- <li>
- Go to the directory containing the loader script:
- <pre>
-# cd <i>$FABAN_HOME</i>/benchmarks/Web20Driver/bin</pre>
- </li>
-
- <li> 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:
- <pre>
-# chmod +x dbloader.sh</pre>
- </li>
-
- <li>
- Run the loader script:
- <pre>
-# ./dbloader.sh <i><dbserver> <load_scale></i>
-
-</pre>
- You can start small with a SCALE of 50 for initial testing.
- </li>
- </ol>
-
- <h2 id="setupFileStore">Setting up the filestore</h2>
-
- <p>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.</p>
-
- <ol>
- <li>
- 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:
- <pre>
-# mkdir -p $FILESTORE
-# chmod a+rwx $FILESTORE</pre>
- </li>
-
- <li>
- Now load the filestore:
- <pre>
-# cd $FILESTORE
-# JAVA_HOME=<java_install_dir>; export $JAVA_HOME
-# $FABAN_HOME/benchmarks/web20/bin/fileloader.sh <load_scale>
-
-</pre>
- This loads files for use for up to
- <code><i>load_scale</i></code> number of
- concurrent users.
- </li>
-
- <li>
- Ensure the <code>$APP_DIR/etc/config.php</code>
- parameter localfsRoot is pointing to
- <code><filestore>.</code>
- </li>
- </ol>
-
- <h2 id="setupEmulator">Setting up the Geocoder Emulator</h2>
-
- <p>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 :</p>
-
- <ol>
- <li>
- Donwload and install Tomcat (either from Cool Stack
- CSKtomcat package for Solaris or directly from <a href=
- "http://tomcat.nginx.org/">http://tomcat.nginx.org</a>) on
- the driver machine. The install directory doesn't matter ? we
- will refer to it as <code>$TOMCAT_HOME</code>.
- </li>
-
- <li>
- Build the <i>geocoder.war</i> file by going to the
- 'geocoder' directory and following the instructions in the
- README file.
- </li>
-
- <li>
- Copy the geocoder.war file from the geocoder/dist
- directory to $TOMCAT_HOME/webapps.
- </li>
-
- <li>
- Start Tomcat using $TOMCAT_HOME/bin/startup.sh.
- </li>
- </ol>
-
- <h2 id="testWebApp">Testing the web application</h2>
-
- <ol>
- <li>
- 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!
- </li>
-
- <li>
- Click on an event (EventDetail). Make sure
- the whole page looks OK.
- </li>
-
- <li>
- Click on an attendee (PersonDetail) to see
- a person's profile.
- </li>
-
- <li>
- 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.
- </li>
-
- <li>
- 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.<br/>
- Submit the form. Make sure the form goes through. This
- completes the AddPerson transaction.
- </li>
-
- <li>
- Login using your new login name you just
- created. The top right of the screen should show that you're
- logged on.
- </li>
-
- <li>
- Select an event, go back to the EventDetail
- page but this time as a logged on user.<br/>
- Add yourself as an attendee. This is the EventDetail
- transaction with attendee added (about 8-9% of all
- EventDetail views).
- </li>
-
- <li>
- 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<br/>
- <code>$FABAN_HOME/benchmarks/web20/resources</code>. Fill in the form and
- submit. This is the AddEvent transaction.
- </li>
- </ol>
-
- <h2 id="startRun">Starting a performance test</h2>
-
- <p>Now that we know that the web
- application is running and the faban harness is up, it is time to
- kick off a test.</p>
-
- <ol>
- <li>
- 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.
- </li>
-
- <li>
- Point your browser at
- http://<i><driver_machine></i>:9980
- </li>
-
- <li>
- Click on the <b>Schedule Run</b> link.
- </li>
-
- <li>
- Under the JAVA tab, set the JAVA_HOME. You can accept the
- default value for JVM options. <b>DO NOT</b> click on the OK
- button yet!<br/><br/>
- <ul>
- <li>Select the Driver tab.</li>
-
- <li>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.</li>
-
- <li>Enter the name of your
- driver(s) machine for Host (when using more than one machine,
- simply separate them by a space).</li>
-
- <li>Enter 10 for 'Concurrent Users'
- (we want to start small).</li>
-
- <li>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.</li>
-
- <li>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.</li>
-
- <li>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.</li>
- </ul>
- </li>
- <li>
- Select the Web Server tab.
-
- <p>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 "nginx" or "apache" 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
+$ ./mysql_install_db</PRE>
+ <LI><P>Start the mysql server. Substitute your own password for <I>pwd</I>
+ (we typically use <I>adminadmin</I>)
+ </P>
+ <PRE>$ ./mysqld_safe &
+$ ./mysqladmin -u root password <I>pwd</I></PRE>
+ <LI><P>Create the web20 user and grant privileges:
+ </P>
+ <PRE> $ ./mysql -u root -p <I>pwd</I>
+ mysql> create user 'olio'@'%' identified by 'olio';
+ mysql> grant all privileges on *.* to 'olio'@'%' identified by 'olio' with grant option;</PRE><P STYLE="margin-bottom: 0in">
+ 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.</P>
+</OL>
+<P STYLE="margin-bottom: 0in">.
+</P>
+<OL START=6>
+ <LI><P>Create database:
+ </P>
+ <PRE>mysql> create database olio;
+mysql> use olio;</PRE>
+ <LI><P>Create database schema:</P>
+ <PRE STYLE="margin-bottom: 0.2in">rake db:migrate</PRE>
+</OL>
+<H2><A NAME="loadDB"></A>Loading the database</H2>
+<P>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.</P>
+<OL>
+ <LI><P STYLE="margin-bottom: 0in">Login to the machine running the
+ Faban master driver. Only this machine has the loader at this time.</P>
+</OL>
+<OL START=2>
+ <LI><P>Go to the directory containing the loader script:
+ </P>
+ <PRE STYLE="margin-bottom: 0.2in"># cd <I>$FABAN_HOME</I>/benchmarks/OlioDriver/bin</PRE>
+ <LI><P>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:
+ </P>
+ <PRE STYLE="margin-bottom: 0.2in"># chmod +x dbloader.sh</PRE>
+ <LI><P>Run the loader script:
+ </P>
+ <PRE># ./dbloader.sh <I><dbserver> <load_scale></I>
+<FONT FACE="Times New Roman, serif"><FONT SIZE=3>You can start small with a SCALE of 50 for initial testing. </FONT></FONT></PRE>
+</OL>
+<H2><A NAME="setupFileStore"></A>Setting up the filestore</H2>
+<P>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.</P>
+<OL>
+ <LI><P>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:
+ </P>
+ <PRE># mkdir -p $FILESTORE
+# chmod a+rwx $FILESTORE</PRE>
+ <LI><P>Now load the filestore. You should have the
+ $FABAN_HOME/benchmarks/OlioDriver.jar file on this system.</P>
+ <PRE STYLE="margin-bottom: 0.2in"># JAVA_HOME=<java_install_dir>; export $JAVA_HOME</PRE>
+</OL>
+<PRE> # cd $FABAN_HOME/benchmarks; mkdir olio
+ # cd olio; jar xvf ../OlioDriver.jar; chmod a+x bin/*</PRE>
+<OL START=2>
+ <PRE># $FABAN_HOME/benchmarks/olio/bin/fileloader.sh <load_scale> $FILESTORE
+<FONT FACE="Times New Roman, serif"><FONT SIZE=3>This loads files for use for up to </FONT></FONT><CODE><FONT FACE="Times New Roman, serif"><FONT SIZE=3><I>load_scale</I></FONT></FONT></CODE> <FONT FACE="Times New Roman, serif"><FONT SIZE=3>number of concurrent users. </FONT></FONT></PRE>
+ <LI><P>Edit $APP_DIR/config/environment.rb and modify the values of
+ <CODE>IMAGE_STORE_PATH</CODE> and <CODE>DOCUMENT_STORE_PATH </CODE><CODE><FONT FACE="Times New Roman, serif">to
+ point to $FILESTORE</FONT></CODE><CODE>.</CODE><CODE><FONT FACE="Times New Roman, serif">Alternatively,
+ create a symbolic link from the default IMAGE_STORE_PATH to
+ $FILESTORE.</FONT></CODE></P>
+</OL>
+<H2><A NAME="setupEmulator"></A>Setting up the Geocoder Emulator</H2>
+<P>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 :</P>
+<OL>
+ <LI><P STYLE="margin-bottom: 0in">Donwload and install Tomcat (from
+ <A HREF="http://tomcat.nginx.org/">http://tomcat.nginx.org</A>) on
+ the driver machine. The install directory doesn't matter - we will
+ refer to it as <CODE>$TOMCAT_HOME</CODE>.
+ </P>
+</OL>
+<P STYLE="margin-bottom: 0in"><BR>
+</P>
+<OL START=2>
+ <LI><P STYLE="margin-bottom: 0in">Build the <I>geocoder.war</I> file
+ by going to the 'geocoder' directory and following the instructions
+ in the README file.
+ </P>
+</OL>
+<P STYLE="margin-bottom: 0in"><BR>
+</P>
+<OL START=3>
+ <LI><P STYLE="margin-bottom: 0in">Copy the geocoder.war file from
+ the geocoder/dist directory to $TOMCAT_HOME/webapps.
+ </P>
+</OL>
+<P STYLE="margin-bottom: 0in"><BR>
+</P>
+<OL START=4>
+ <LI><P>Start Tomcat using $TOMCAT_HOME/bin/startup.sh.
+ </P>
+ <LI><P>Go to <CODE>$APP_DIR/config</CODE>. Edit the file
+ <CODE>environment.rb</CODE> and change 'localhost' in
+ <CODE>Geolocation.url = '...'</CODE> to the actual hostname where
+ the geocoder emulator is running.</P>
+</OL>
+<H2><A NAME="testWebApp"></A>Testing the web application</H2>
+<OL>
+ <LI><P STYLE="margin-bottom: 0in">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!
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">Click on an event (EventDetail).
+ Make sure the whole page looks OK.
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">Click on an attendee
+ (PersonDetail) to see a person's profile.
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">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.
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">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.
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">Login using your new login name
+ you just created. The top right of the screen should show that
+ you're logged on.
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">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).
+ </P>
+ <LI><P>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 <CODE>$FABAN_HOME/benchmarks/web20/resources</CODE>. Fill in
+ the form and submit. This is the AddEvent transaction.
+ </P>
+</OL>
+<H2><A NAME="startRun"></A>Starting a performance test</H2>
+<P>Now that we know that the web application is running and the faban
+harness is up, it is time to kick off a test.</P>
+<OL>
+ <LI><P STYLE="margin-bottom: 0in">Point your browser at
+ http://<I><driver_machine></I>:9980
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">Click on the <B>Schedule Run</B>
+ link.
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">Under the JAVA tab, set the
+ JAVA_HOME. You can accept the default value for JVM options. <B>DO
+ NOT</B> click on the OK button yet!
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">Select the Driver tab.
+ </P>
+</OL>
+<P STYLE="margin-bottom: 0in">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</P>
+<P STYLE="margin-bottom: 0in">run is testing.
+</P>
+<P STYLE="margin-bottom: 0in">Enter the name of your driver(s)
+machine for Host (when using more than one machine, simply separate
+them by a space).
+</P>
+<P STYLE="margin-bottom: 0in">Enter 10 for 'Concurrent Users' (we
+want to start small).
+</P>
+<P STYLE="margin-bottom: 0in">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</P>
+<P STYLE="margin-bottom: 0in">utilization.
+</P>
+<P STYLE="margin-bottom: 0in">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</P>
+<P STYLE="margin-bottom: 0in">200 seconds and a steady state of at
+least 600 seconds during which measurements are made.
+</P>
+<P STYLE="margin-bottom: 0in">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
+</P>
+<P STYLE="margin-bottom: 0in">accept connections very frequently. In
+that case we may want to increase this value to 1000 milliseconds.
+</P>
+<OL START=5>
+ <LI><P>Select the Web Server tab.
+ </P>
+ <P>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</p>
- </li>
- <li>Select the Data Servers tab.
-
- <p>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.</p>
-
- <p>Set the Data Storage server.
- For local storage this is the same host as the web
- server. </p>
-
- <p>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.</p>
- </li>
- <li>
- 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.
- </li>
- </ol>
-</body>
-</html>
+ vmstat 10; mpstat 10; iostat -x 10</P>
+ <LI><P>Select the Data Servers tab.
+ </P>
+ <P>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 .</P>
+ <P>Set the Data Storage server. For local storage this is the same
+ host as the web server.</P>
+ <LI><P>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.
+ </P>
+</OL>
+</BODY>
+</HTML>
\ No newline at end of file
Added: incubator/olio/docs/rails_setup_kit.html
URL: http://svn.apache.org/viewvc/incubator/olio/docs/rails_setup_kit.html?rev=755446&view=auto
==============================================================================
--- incubator/olio/docs/rails_setup_kit.html (added)
+++ incubator/olio/docs/rails_setup_kit.html Tue Mar 17 23:40:05 2009
@@ -0,0 +1,601 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<HTML>
+<HEAD>
+ <META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=utf-8">
+ <TITLE>Olio/Rails Install and Setup Guide</TITLE>
+ <META NAME="GENERATOR" CONTENT="NeoOffice 2.2 (Unix)">
+ <META NAME="AUTHOR" CONTENT="Akara Sucharitakul">
+ <META NAME="CREATED" CONTENT="20070926;10111500">
+ <META NAME="CHANGED" CONTENT="20090317;16320600">
+ <!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+ -->
+ <STYLE TYPE="text/css">
+ <!--
+ @page { size: 8.5in 11in }
+ H1 { color: #000000; text-align: center }
+ P { color: #000000 }
+ PRE { color: #000000 }
+ H2 { color: #000000 }
+ -->
+ </STYLE>
+</HEAD>
+<BODY LANG="en-US" TEXT="#000000" DIR="LTR">
+<H1>Olio/Rails<BR>Install and Setup Guide from Tarball</H1>
+<P>Note: The application currently does not use memcached. Please
+ignore the memcached related setup instructions.</P>
+<P>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.</P>
+<H2>Overview</H2>
+<P>Olio is a macro-level toolkit consisting of the following
+components:</P>
+<OL>
+ <LI><P STYLE="margin-bottom: 0in">The web application
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">The main database
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">Distributed storage servers (NFS)
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">Geocoder emulator
+ </P>
+ <LI><P>Workload driver
+ </P>
+</OL>
+<P>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.</P>
+<P>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).</P>
+<P>In the following sections, we will go over the steps needed to
+configure each component :</P>
+<UL>
+ <LI><P STYLE="margin-bottom: 0in"><A HREF="#Extracting the Contents|outline">Extracting
+ the contents</A>
+ </P>
+ <LI><P STYLE="margin-bottom: 0in"><A HREF="#setupDriver">Setting up
+ the driver</A>
+ </P>
+ <LI><P STYLE="margin-bottom: 0in"><A HREF="#installWebApp">Installing
+ the Web Application</A>
+ </P>
+ <LI><P STYLE="margin-bottom: 0in"><A HREF="#setupDB">Setting up the
+ database</A>
+ </P>
+ <LI><P STYLE="margin-bottom: 0in"><A HREF="#loadDB">Loading the
+ database</A>
+ </P>
+ <LI><P STYLE="margin-bottom: 0in"><A HREF="#setupFileStore">Setting
+ up the filestore</A>
+ </P>
+ <LI><P STYLE="margin-bottom: 0in"><A HREF="#setupEmulator">Setting
+ up the Geocoder Emulator</A>
+ </P>
+ <LI><P STYLE="margin-bottom: 0in"><A HREF="#testWebApp">Testing the
+ web application</A>
+ </P>
+ <LI><P><A HREF="#startRun">Starting a performance test</A>
+ </P>
+</UL>
+<H2><A NAME="Extracting the Contents|outline"></A>Extracting the
+Contents</H2>
+<P>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 gtar to extract. This can
+be done as follows:</P>
+<P><FONT FACE="Courier New, monospace"><FONT SIZE=2 STYLE="font-size: 11pt">#
+gzcat <I>olio-rails-<version></I>.tar.gz | gtar xvf -</FONT></FONT></P>
+<P>This will cause a directory named olio-rails-<I><version> </I><SPAN STYLE="font-style: normal">to
+be created whose contents should look like:</SPAN></P>
+<P STYLE="margin-bottom: 0.04in; font-style: normal"><FONT FACE="Courier New, monospace"><FONT SIZE=2 STYLE="font-size: 11pt">#
+ls olio-rails-0.1*</FONT></FONT></P>
+<P STYLE="margin-bottom: 0.04in; font-style: normal"><FONT FACE="Courier New, monospace"><FONT SIZE=2 STYLE="font-size: 11pt">LICENSE
+OlioDriver.jar geocoder.war rails_setup_kit.html</FONT></FONT></P>
+<P STYLE="margin-bottom: 0.04in; font-style: normal"><FONT FACE="Courier New, monospace"><FONT SIZE=2 STYLE="font-size: 11pt">NOTICE
+ RELEASE-NOTES-rails-0.1.txt oliorails/ release</FONT></FONT></P>
+<P STYLE="margin-bottom: 0.04in; font-style: normal"><FONT FACE="Courier New, monospace"><FONT SIZE=2 STYLE="font-size: 11pt">#
+</FONT></FONT>
+</P>
+<P>We will use $OLIO_HOME to designate the name of this directory. A
+description of the contents follows :</P>
+<UL>
+ <LI><P>The <I>oliorails</I> directory contains the web application.
+ This application will be deployed on the rails server (thin or
+ mongrel).</P>
+ <LI><P><I>OlioDriver.jar</I> contains the load generator/driver
+ (which we typically refer to simply as <I>driver</I>). The driver is
+ implemented using <A HREF="http://faban.sunsource.net/"><I>Faban</I></A>
+ â an open source benchmarking toolkit.</P>
+ <LI><P><I>geocoder.war</I> contains the simple servlet used to
+ emulate the geocoder.</P>
+ <LI><P><I>rails_setup_kit.html</I> is this document.</P>
+ <LI><P>RELEASE-NOTES-rails-0.1.txt contains the release notes for
+ this release.</P>
+ <LI><P><I>release</I> contains the release name.
+ </P>
+ <LI><P>LICENSE and NOTICE contain the licenses.</P>
+</UL>
+<H2><A NAME="setupDriver"></A>Setting up the driver</H2>
+<P>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.</P>
+<OL>
+ <LI><P STYLE="margin-bottom: 0in">See
+ <A HREF="http://faban.sunsource.net/docs/guide/harness/install.html">http://faban.sunsource.net/docs/guide/harness/install.html</A>
+ for Faban installation instructions. Note that faban needs to be
+ installed on all the machines used for the test. Please also read
+ the <I>Getting Started Guide</I> 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 <CODE>$FABAN_HOME</CODE>.
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">Copy <CODE>$OLIO_HOME/OlioDriver.jar</CODE>
+ to the <CODE>$FABAN_HOME/benchmarks</CODE> directory. Also copy the
+ OlioDriver.jar file to the $FABAN_HOME/benchmarks directory on the
+ system that will run the rails application.
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">For the driver to work, you will
+ need JDK 1.6. Set <CODE>JAVA_HOME</CODE> to the path of the JDK in
+ the faban user's environment.
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">Start the faban master on the
+ master driver machine : <CODE>$FABAN_HOME/master/bin/startup.sh</CODE>
+ </P>
+ <LI><P>Test that you can connect to the master by pointing your
+ browser at <CODE>http://</CODE><CODE><I><driver_machine></I></CODE><CODE>:9980</CODE>
+ </P>
+</OL>
+<H2><A NAME="installWebApp"></A>Installing the Web Application</H2>
+<P>The web application is a Rails application. It requires the
+following components:</P>
+<OL>
+ <LI><P STYLE="margin-bottom: 0in">A web server such as Nginx,
+ Lighttpd or Apache (the instructions below focus on nginx)</P>
+ <LI><P STYLE="margin-bottom: 0in">Ruby 1.8.6 or higher with the
+ following gems and their dependencies :</P>
+ <UL>
+ <LI><P STYLE="margin-bottom: 0in">rails</P>
+ <LI><P STYLE="margin-bottom: 0in">rake
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">thin (mongrel can be used if
+ desired)
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">mysql</P>
+ <LI><P STYLE="margin-bottom: 0in">image_science (uses FreeImage
+ which needs to be downloaded and built)</P>
+ <LI><P STYLE="margin-bottom: 0in">rcov</P>
+ <LI><P STYLE="margin-bottom: 0in">will_paginate</P>
+ </UL>
+</OL>
+<P STYLE="margin-left: 0.79in; margin-bottom: 0in"><BR>
+</P>
+<OL START=3>
+ <LI><P>MySQL 5 (5.1 recommended)</P>
+</OL>
+<P>For Linux (debian or ubunu), the following command can be used:</P>
+<PRE STYLE="margin-bottom: 0.2in"> aptitude install build-essential subversion ruby1.8 ruby1.8-dev nginx libmysqlclient-dev rubygems libgems-ruby1.8</PRE><P STYLE="margin-bottom: 0in">
+For OpenSolaris 2008.11:</P>
+<UL>
+ <LI><P STYLE="margin-bottom: 0in">Upgrade your Ruby version to the
+ latest in the pkg.opensolaris.org/dev repository. This will give you
+ Rubygems 1.3.1 and Ruby 1.8.7p72.</P>
+ <P STYLE="margin-bottom: 0in"></P>
+</UL>
+<UL>
+ <LI><P STYLE="margin-bottom: 0in">Set the environment variable CXX
+ to /usr/sfw/bin/gcc. This is required to build eventmachine (a thin
+ dependency).</P>
+</UL>
+<P STYLE="margin-bottom: 0in"><BR>
+</P>
+<UL>
+ <LI><P STYLE="margin-bottom: 0in">Edit
+ <FONT FACE="Cumberland, monospace">/usr/ruby/1.8/lib/ruby/1.8/i386-solaris2.11/rbconfig.rb</FONT>
+ as follows :</P>
+</UL>
+<P STYLE="margin-left: 0.79in; margin-bottom: 0in">CONFIG["LDSHARED"]
+= "/usr/sfw/bin/gcc -G"</P>
+<P STYLE="margin-bottom: 0in"><BR>
+</P>
+<UL>
+ <LI><P STYLE="margin-bottom: 0in">Download and build FreeImage.
+ Instructions are given in
+ <A HREF="http://wiki.joyent.com/accelerators:freeimage_imagescience">http://wiki.joyent.com/accelerators:freeimage_imagescience</A>.
+ Do not change the COMPILERFLAGS setting. Set INSTALLDIR to
+ /opt/local. The entries for the 'install' directive in
+ Makefile.solaris should read:</P>
+</UL>
+<P STYLE="margin-bottom: 0in"> i<FONT FACE="Courier New, monospace"><FONT SIZE=2 STYLE="font-size: 11pt">nstall:</FONT></FONT></P>
+<P STYLE="margin-bottom: 0in"> <FONT FACE="Courier New, monospace"><FONT SIZE=2 STYLE="font-size: 11pt">install
+-m 644 -u root -g root -f $(INSTALLDIR)/include Source/FreeImage.h </FONT></FONT>
+</P>
+<P STYLE="margin-bottom: 0in"> <FONT FACE="Courier New, monospace"><FONT SIZE=2 STYLE="font-size: 11pt">install
+-m 644 -u root -g root -f $(INSTALLDIR)/lib $(STATICLIB) </FONT></FONT>
+</P>
+<P STYLE="margin-bottom: 0in"> <FONT FACE="Courier New, monospace"><FONT SIZE=2 STYLE="font-size: 11pt">install
+-m 755 -u root -g root -f $(INSTALLDIR)/lib $(SHAREDLIB) </FONT></FONT>
+</P>
+<P STYLE="margin-bottom: 0in"> <FONT FACE="Courier New, monospace"><FONT SIZE=2 STYLE="font-size: 11pt">ln
+-sf $(INSTALLDIR)/lib/$(SHAREDLIB) $(INSTALLDIR)/lib/$(LIBNAME)</FONT></FONT></P>
+<P STYLE="margin-bottom: 0in"><BR>
+</P>
+<UL>
+ <LI><P STYLE="margin-bottom: 0in">Now install these gems:
+ </P>
+</UL>
+<P STYLE="margin-bottom: 0in"> <FONT FACE="Courier New, monospace"><FONT SIZE=2 STYLE="font-size: 11pt">gem
+install rake rails thin rcov will_paginate image_science</FONT></FONT></P>
+<P STYLE="margin-bottom: 0in"><BR>
+</P>
+<UL>
+ <LI><P STYLE="margin-bottom: 0in">To install the mysql gem, you will
+ need to use the <A HREF="http://developers.sun.com/sunstudio/downloads/">Sun
+ Studio compiler</A>. Edit
+ <FONT FACE="Cumberland, monospace">/usr/ruby/1.8/lib/ruby/1.8/i386-solaris2.11/rbconfig.rb</FONT>
+ as follows :</P>
+</UL>
+<P STYLE="margin-left: 0.79in; margin-bottom: 0in">CONFIG[CC] = "ccâ</P>
+<P STYLE="margin-left: 0.79in; margin-bottom: 0in">CONFIG[CFLAGS] =
+"-xO4 -xtarget=genericâ</P>
+<P STYLE="margin-left: 0.79in; margin-bottom: 0in">CONFIG["LDFLAGS"]
+= ""</P>
+<P STYLE="margin-left: 0.79in; margin-bottom: 0in">CONFIG["LDSHARED"]
+= "ld -G"</P>
+<P STYLE="margin-left: 0.79in; margin-bottom: 0in"><BR>
+</P>
+<UL>
+ <LI><P STYLE="margin-bottom: 0in">Ensure the Studio compiler bin
+ directory is in your PATH, then run: <FONT FACE="Courier New, monospace">gem
+ install mysql</FONT>.</P>
+</UL>
+<P STYLE="margin-bottom: 0in"><BR>
+</P>
+<UL>
+ <LI><P STYLE="margin-bottom: 0in">Install nginx. You can build nginx
+ from source by using the Makefile in
+ <A HREF="http://hg.opensolaris.org/sc/src/webstack/nginx/">http://hg.opensolaris.org/sc/src/webstack/nginx/</A>.
+ Alternatively, you can install a pre-build binary following the
+ instructions in
+ </P>
+</UL>
+<UL>
+ <P STYLE="margin-bottom: 0in"><A HREF="http://blogs.sun.com/jyrivirkki/entry/nginx_package_updates">http://blogs.sun.com/jyrivirkki/entry/nginx_package_updates</A><A HREF="http://blogs.sun.com/jyrivirkki/entry/nginx_package_updates">.</A><A HREF="http://blogs.sun.com/jyrivirkki/entry/nginx_package_updates"><SPAN STYLE="text-decoration: none">
+ </SPAN></A>
+ </P>
+</UL>
+<P STYLE="margin-bottom: 0in"><BR>
+</P>
+<P STYLE="margin-bottom: 0in"><BR>
+</P>
+<P>Once you have the application stack installed, follow the steps
+below to set up the application.</P>
+<OL>
+ <LI><P>Decide where you want to install the web application. For
+ this example we will use /var/app:
+ </P>
+ <PRE>$ mkdir /var/app
+$ cd /var/app</PRE>
+ <LI><P>Copy the contents of $OLIO_HOME/oliorails to /var/app/olio.
+ We will use <CODE>$APP_DIR</CODE> to refer to the location:
+ <CODE>/var/app/olio</CODE>
+ </P>
+ <LI><P>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 <FONT FACE="Courier New, monospace">error_log</FONT>
+ and <FONT FACE="Courier New, monospace">pid</FONT> entries. The
+ default location for these files is in /var/nginx/logs.</P>
+ <P>To change user to another user, modify the first line and change
+ <CODE>user root;</CODE> to your preferred user. On OpenSolaris, the
+ default user is usually webservd. If you have more than one machine
+ hosting your thins, modify the upstream thin and add the addresses
+ of your application servers.</P>
+ <P STYLE="margin-bottom: 0.04in">To change the location of the
+ application static content :</P>
+</OL>
+<P STYLE="margin-bottom: 0.04in"><CODE>#### Replace with the full
+path to your rails app's public directory: </CODE>
+</P>
+<PRE STYLE="margin-bottom: 0.2in"><CODE> root /var/www/virtual/example.com/rails/railsapp/public;</CODE></PRE><P STYLE="margin-bottom: 0.04in">
+ to <CODE>root $APP_DIR/public;</CODE>
+</P>
+<OL START=3>
+ <P STYLE="margin-bottom: 0.14in">Do not start nginx yet.</P>
+</OL>
+<H2><A NAME="setupDB"></A>Setting up the database</H2>
+<OL>
+ <LI><P STYLE="margin-bottom: 0in">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.
+ </P>
+ <LI><P>Setup the mysql user/group and permissions for it's
+ directories:
+ </P>
+ <PRE># groupadd mysql
+# useradd -d $MYSQL_HOME -g mysql -s /usr/bin/bash mysql
+# chown -R mysql:mysql $MYSQL_HOME</PRE>
+ <LI><P>Create the database :
+ </P>
+ <PRE># su - mysql
+$ cd bin
+$ ./mysql_install_db</PRE>
+ <LI><P>Start the mysql server. Substitute your own password for <I>pwd</I>
+ (we typically use <I>adminadmin</I>)
+ </P>
+ <PRE>$ ./mysqld_safe &
+$ ./mysqladmin -u root password <I>pwd</I></PRE>
+ <LI><P>Create the web20 user and grant privileges:
+ </P>
+ <PRE> $ ./mysql -u root -p <I>pwd</I>
+ mysql> create user 'olio'@'%' identified by 'olio';
+ mysql> grant all privileges on *.* to 'olio'@'%' identified by 'olio' with grant option;</PRE><P STYLE="margin-bottom: 0in">
+ 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.</P>
+</OL>
+<P STYLE="margin-bottom: 0in">.
+</P>
+<OL START=6>
+ <LI><P>Create database:
+ </P>
+ <PRE>mysql> create database olio;</PRE>
+</OL>
+<PRE></PRE>
+<OL START=6>
+ <LI><PRE><FONT FACE="Times New Roman, serif"><FONT SIZE=3>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.</FONT></FONT></PRE>
+</OL>
+<PRE STYLE="margin-bottom: 0.2in"></PRE>
+<OL START=6>
+ <LI><P>Create database schema from the rails application :</P>
+ <PRE STYLE="margin-bottom: 0.2in">cd $APP_DIR; rake db:migrate</PRE>
+</OL>
+<H2><A NAME="loadDB"></A>Loading the database</H2>
+<P>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.</P>
+<OL>
+ <LI><P STYLE="margin-bottom: 0in">Login to the machine running the
+ Faban master driver. Only this machine has the loader at this time.</P>
+</OL>
+<OL START=2>
+ <LI><P>Go to the directory containing the loader script:
+ </P>
+ <PRE STYLE="margin-bottom: 0.2in"># cd <I>$FABAN_HOME</I>/benchmarks/OlioDriver/bin</PRE>
+ <LI><P>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:
+ </P>
+ <PRE STYLE="margin-bottom: 0.2in"># chmod +x dbloader.sh</PRE>
+ <LI><P>Run the loader script:
+ </P>
+ <PRE># ./dbloader.sh <I><dbserver> <load_scale></I>
+<FONT FACE="Times New Roman, serif"><FONT SIZE=3>You can start small with a SCALE of 50 for initial testing. </FONT></FONT></PRE>
+</OL>
+<H2><A NAME="setupFileStore"></A>Setting up the filestore</H2>
+<P>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.</P>
+<OL>
+ <LI><P>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:
+ </P>
+ <PRE># mkdir -p $FILESTORE
+# chmod a+rwx $FILESTORE</PRE>
+ <LI><P>Now load the filestore. You should have the
+ $FABAN_HOME/benchmarks/OlioDriver.jar file on this system.</P>
+ <PRE STYLE="margin-bottom: 0.2in"># JAVA_HOME=<java_install_dir>; export $JAVA_HOME</PRE>
+</OL>
+<PRE> # cd $FABAN_HOME/benchmarks; mkdir olio
+ # cd olio; jar xvf ../OlioDriver.jar; chmod a+x bin/*</PRE>
+<OL START=2>
+ <PRE># $FABAN_HOME/benchmarks/olio/bin/fileloader.sh <load_scale> $FILESTORE
+<FONT FACE="Times New Roman, serif"><FONT SIZE=3>This loads files for use for up to </FONT></FONT><CODE><FONT FACE="Times New Roman, serif"><FONT SIZE=3><I>load_scale</I></FONT></FONT></CODE> <FONT FACE="Times New Roman, serif"><FONT SIZE=3>number of concurrent users. </FONT></FONT></PRE>
+ <LI><P>Edit $APP_DIR/config/environment.rb and modify the values of
+ <CODE>IMAGE_STORE_PATH</CODE> and <CODE>DOCUMENT_STORE_PATH </CODE><CODE><FONT FACE="Times New Roman, serif">to
+ point to $</FONT></CODE><CODE><FONT FACE="Times New Roman, serif">FILESTORE.
+ Note that $FILESTORE is relative to $APP_DIR. Alternatively</FONT></CODE><CODE><FONT FACE="Times New Roman, serif">,
+ create a symbolic link from the default IMAGE_STORE_PATH to
+ $FILESTORE. </FONT></CODE>
+ </P>
+</OL>
+<H2><A NAME="setupEmulator"></A>Setting up the Geocoder Emulator</H2>
+<P>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 :</P>
+<OL>
+ <LI><P STYLE="margin-bottom: 0in">Donwload and install Tomcat (from
+ <A HREF="http://tomcat.nginx.org/">http://tomcat.nginx.org</A>) on
+ the driver machine. The install directory doesn't matter - we will
+ refer to it as <CODE>$TOMCAT_HOME</CODE>.
+ </P>
+</OL>
+<P STYLE="margin-bottom: 0in"><BR>
+</P>
+<OL START=2>
+ <LI><P STYLE="margin-bottom: 0in">Copy $OLIO_HOME/geocoder.war file
+ to $TOMCAT_HOME/webapps.
+ </P>
+</OL>
+<P STYLE="margin-bottom: 0in"><BR>
+</P>
+<OL START=3>
+ <LI><P STYLE="margin-bottom: 0in">Start Tomcat using
+ $TOMCAT_HOME/bin/startup.sh.
+ </P>
+</OL>
+<P STYLE="margin-bottom: 0in"><BR>
+</P>
+<OL START=4>
+ <LI><P>Go to <CODE>$APP_DIR/config</CODE>. Edit the file
+ <CODE>environment.rb</CODE> and change 'localhost' in
+ <CODE>Geolocation.url = '...'</CODE> to the actual hostname where
+ the geocoder emulator is running.</P>
+</OL>
+<H2><A NAME="testWebApp"></A>Testing the web application</H2>
+<UL>
+ <LI><P>Start thin:
+ </P>
+ <LI><PRE>$ cd $APP_DIR</PRE>
+ <LI><PRE STYLE="margin-bottom: 0.2in">$ thin -d -p 3000 -e production -l /var/log/thin.log â-pid /var/run/thin.pid -s 4 start</PRE>
+ <LI><P>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 <CODE>nginx.conf</CODE> file will need to be modified as well.
+ You can also change to unix domain sockets by using the --socket
+ option and <CODE>server unix:/tmp/projects.0.sock;</CODE> for each
+ of the sockets.
+ </P>
+ <LI><P>Start nginx. Check that you can connect to it from your
+ browser (<A HREF="http://host:80/">http://<I>host</I>:80</A>).
+ 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 thin
+ and nginx error logs to debug.
+ </P>
+ <LI><P>Click on an event (EventDetail). Make sure the whole page
+ looks OK.
+ </P>
+ <LI><P>Click on an attendee (PersonDetail) to see a person's
+ profile.
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">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.
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">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.
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">Login using your new login name
+ you just created. The top right of the screen should show that
+ you're logged on.
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">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).
+ </P>
+ <LI><P>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 <CODE>$FABAN_HOME/benchmarks/web20/resources</CODE>. Fill in
+ the form and submit. This is the AddEvent transaction.
+ </P>
+</UL>
+<H2><A NAME="startRun"></A>Starting a performance test</H2>
+<P>Now that we know that the web application is running and the faban
+harness is up, it is time to kick off a test.</P>
+<OL>
+ <LI><P STYLE="margin-bottom: 0in">Point your browser at
+ http://<I><driver_machine></I>:9980
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">Click on the <B>Schedule Run</B>
+ link.
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">Under the JAVA tab, set the
+ JAVA_HOME. You can accept the default value for JVM options. <B>DO
+ NOT</B> click on the OK button yet!
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">Select the Driver tab.
+ </P>
+</OL>
+<UL>
+ <UL>
+ <LI><P STYLE="margin-bottom: 0in">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.
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">Enter the name of your driver(s)
+ machine for Host (when using more than one machine, simply separate
+ them by a space).
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">Enter 10 for 'Concurrent Users'
+ (we want to start small).
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">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.
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">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.
+ </P>
+ <LI><P STYLE="margin-bottom: 0in">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.
+ </P>
+ </UL>
+</UL>
+<P STYLE="margin-bottom: 0in"><BR>
+</P>
+<OL START=5>
+ <LI><P>Select the Web Server tab.
+ </P>
+ <P>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</P>
+ <LI><P>Select the Data Servers tab.
+ </P>
+ <P>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 .</P>
+ <P>Set the Data Storage server. For local storage this is the same
+ host as the web server.</P>
+ <LI><P>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.
+ </P>
+</OL>
+</BODY>
+</HTML>
\ No newline at end of file