incubator-olio-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sha...@apache.org
Subject svn commit: r755446 - in /incubator/olio/docs: app_spec.html php_setup.html php_setup_kit.html rails_setup.html rails_setup_kit.html
Date Tue, 17 Mar 2009 23:40:05 GMT
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-&lt;version&gt;b&lt;build_date&gt;</I>.tar.gz | tar
-xvf -</FONT></FONT></P>
-<P>This will cause a directory named
-olio-php-<I>&lt;version&gt;</I>b<I>&lt;build_date&gt;</I><SPAN STYLE="font-style: normal">to
+gzcat <I>olio-php-&lt;version&gt;</I>.tar.gz | gtar xvf -</FONT></FONT></P>
+<P>This will cause a directory named olio-php-<I>&lt;version&gt; </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>&lt;driver_machine&gt;</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>&lt;driver_machine&gt;</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] =
+&quot;-g -O3 -fPIC -R/usr/local/lib”</P>
+<P STYLE="margin-left: 0.79in; margin-bottom: 0in">CONFIG[&quot;LDFLAGS&quot;]
+= &quot;-L/usr/sfw/lib -R/usr/sfw/lib -R/usr/local/lib&quot;</P>
+<P STYLE="margin-left: 0.79in; margin-bottom: 0in">CONFIG[&quot;LDSHARED&quot;]
+= &quot;gcc -G&quot;</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 &amp;
-$ ./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&gt; create user 'web20'@'%' identified by 'web20';
- mysql&gt; 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'@'&lt;hostname&gt;' individually, where hostname
-      are the names of the driver and nginx systems.
-    </li>
-
-    <li>
-      Create database:
-      <pre>
-mysql&gt; create database web20load;
-mysql&gt; 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>&lt;dbserver&gt; &lt;load_scale&gt;</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>&lt;filestore&gt;.</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://&lt;web_server&gt;: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>&lt;driver_machine&gt;</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 &amp;
+$ ./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&gt; create user 'olio'@'%' identified by 'olio';
+ mysql&gt; 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'@'&lt;hostname&gt;' 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&gt; create database olio;
+mysql&gt; 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>&lt;dbserver&gt; &lt;load_scale&gt;</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=&lt;java_install_dir&gt;; 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 &lt;load_scale&gt; $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://&lt;web_server&gt;: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>&lt;driver_machine&gt;</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
+	&quot;lighttpd&quot; 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.&nbsp;</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-&lt;version&gt;</I>.tar.gz | gtar xvf -</FONT></FONT></P>
+<P>This will cause a directory named olio-rails-<I>&lt;version&gt; </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>&lt;driver_machine&gt;</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[&quot;LDSHARED&quot;]
+= &quot;/usr/sfw/bin/gcc -G&quot;</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] = &quot;cc”</P>
+<P STYLE="margin-left: 0.79in; margin-bottom: 0in">CONFIG[CFLAGS] =
+&quot;-xO4 -xtarget=generic”</P>
+<P STYLE="margin-left: 0.79in; margin-bottom: 0in">CONFIG[&quot;LDFLAGS&quot;]
+= &quot;&quot;</P>
+<P STYLE="margin-left: 0.79in; margin-bottom: 0in">CONFIG[&quot;LDSHARED&quot;]
+= &quot;ld -G&quot;</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 &amp;
+$ ./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&gt; create user 'olio'@'%' identified by 'olio';
+ mysql&gt; 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'@'&lt;hostname&gt;' 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&gt; 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>&lt;dbserver&gt; &lt;load_scale&gt;</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=&lt;java_install_dir&gt;; 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 &lt;load_scale&gt; $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>&lt;driver_machine&gt;</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
+	&quot;lighttpd&quot; 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



Mime
View raw message