Welcome to the PHP implementation of the TPC-W ECommerce Benchmark Suite. This file describes how to install and run a test. Please be patient, a TPC-W benchmark setup and run is usually not what one can accomplish over a lunchbreak. 1. Requirements The following tools are required: At least 2 computer systems connected via network. C compiler to build the data and image generator utilities. Tcl/Tk version 8.3 or higher to produce the initial DB population. X11 utility xwd and the PBM toolkits utilities xwdtopnm and ppmtogif (to generate the button and label images). Apache Web Server with PHP version 4.1.2 or compatible. PHP must be installed with PostgreSQL and/or MySQL 4.1 support. Apache must be installed with SSL support (self signed certificates are accepted by the browser emulator). On the system emulating the browsers, Java Runtime 1.4.2. 2. Overview A typical TPC-W test installation looks like this: +----------+ +------------------+ | | | | | 1..n RBE |------Network-----| 1..n Web servers | | | | | +----------+ +------------------+ | | | +------------------+ | | | DB Server | | | +------------------+ The Remote Browser Emulator(s) (RBE), that is the application that simulates the users, is strictly required to run on separate systems which are not part of the System Under Test (SUT). Being implemented in this case as a Java application, all that is required to run this is a Java Runtime Environment, which can be easily installed on every Windows PC and most Unix systems. The SUT consists of one or more Web servers with a DB Server. It is allowed to distribute the SUT over as many physical servers as one wants to. The initial IP address a new browser connects to however must always be the same one. Typically the application middleware (in this case PHP) is installed on one system, a second Web server is serving the images and a third server system is used for the database. But is it totally valid to serve the PHP pages and images from the same Apache instance and have the database installed on the same server. 2. Installation 2.1 Building all executable files There are several executable files used during the initial population of the database. To build them type "make" in this toplevel directory. The programs built by that are: ./data_generation/rand_astring A helper program that produces a constant stream of rand-a-string characters (see TPC-W-4.6.2.2). It is used by the populate_database.tcl script. ./data_generation/wgen/tpcw The official TPC-W DBGEN utility described in TPC-W-Appendix-H. It is used by populate_database.tcl to generate the I_TITLE and A_LNAME fields. ./image_generation/ImgGen/ImgFiles/tpcwIMG The official TPC-W Image data generation utility (see TPC-W-4.6.2.13). 2.2 Database population This test suite assumes that the PHP scripts connect to a PostgreSQL database as user apache. If no such user exists, it should be created and the pg_hba.conf file adjusted so that PHP can establish a connection as that user. The TPC-W benchmark has 2 scaling factors. The number of products in the ITEM table, and the number of emulated browsers generating the test load. The number of EBs affects the size of the initial database as most tables are populated depending on that number (see TPC-W-4.1). The script ./data_generation/pop_100EB_1000ITEM.sh contains a sample run for a very small populated database. It should be used for first tests as higher scaling factors result in significant runtimes. To create this sample database do createdb tpcw cd data_generation ./pop_100EB_1000ITEM.sh pgsql psql tpcw is the scaling of the ITEM table used when populating the database): cd image_generation ./generate_images cd .. 2.4 Installing the application The entire directory ./html/tpcw must be copied now into the document root of the web server. cp -R ./html/tpcw The file /tpcw/config.inc must be created and edited. Use the existing config.inc.sample as a start. The correct database connection information must be specified and the current scaling factors (used to generate some random numbers in the SUT) must be adjusted. 3. Testing the SUT At this point the SUT should be fully operational. Use your favorite Web browser and point it to the tpcw application. Please refer to TPC-W Clause 2 for the expected input of the various Web interactions. 4. Running the emulated browser. The RBE is a Java application taken from the "TPC-W in Java" distribution written by Trey Cain, Milo Martin, Tim Heil, Eric Weglarz, and Todd Bezenek. University of Wisconsin - Madison, Computer Sciences Dept. and Dept. of Electrical and Computer Engineering, as a part of Prof. Mikko Lipasti's ECE 902 course. The sourcecode is adjusted for the PHP implementation (instead of Java servlets) of the SUT, the use of Cookies for session management and enhanced to support Secure Socket Layer connections required by several Web Interactions in the test suite. The sample script ./RBE/run_RBE_100EB_1000ITEM.sh must be adjusted for the current installation. Especially the web_server must point to exactly the full qualified domain name the SSL certificates used by the server are generated for. The specific options are explained in detail in that script. The script produces a .log file containing the entire stdout and stderr output of the RBE for diagnostic purposes. On successfull completion the RBE produces a .out file giving detailed information about the response time distributions of all different transaction types. 5. Recommendations The rampup time should not be chosen too small, as the DB's cache population has a significant impact on performance and the initial workload caused by an unpopulated cache needs some time to level out. For large numbers of Apache work processes, the PgPool utility should be used to reduce the resource consumption of the PostgreSQL database. Last but not least, be patient. Running through all the data generating and loading for the wee little test illustrated in the sample scripts takes several hours on a 2.4GHz Pentium4 system. Expect to spend a couple of days with this before you have found the right scaling factors for your particular server configuration.