Private Instances

WebPagetest is available as a software package for installation and running of private instances. 

Releases

The latest release is 2.16

Easy Deployment (on EC2)

There is an EC2 AMI available for the WebPageTest server that provides a lot of benefits:
  • No configuration required (up and running in 5 minutes).
  • Automatically starts and stops EC2 test agents in all of the EC2 regions as needed.
  • Automatically updates to the latest server and agent code.

Manual Deployment

System Requirements

WebPageTest can be configured to run all on one system (with the web server and test machines all running on the same PC) or with separate systems for the web server and testers. 

Web Server

The Web Server can be any OS that supports Apache and PHP (Linux and Windows have both been tested). If the tester is going to be running on the same machine as the web server then it needs to be a 32-bit version of Windows (XP or later).
  • Apache 2.x+ with the following modules enabled:
    • mod_expires
    • mod_headers
    • mod_rewrite
  • PHP 5.3.0 or later with the following modules:
    • gd
    • zip
    • zlib
    • curl (if you want to use remote-storage like S3 and Google storage)
    • sqlite (if you want to be able to edit test labels)
  • ffmpeg 
    • Make available in the path (used to extract video thumbnail images)
    • For mobile agent video support it needs to be 1.x (Linux, Windows)
  • imagemagick (optional)
    • Necessary for mobile video processing if using the mobile Node.js agent
  • jpegtran (optional)
    • Make available in the path (used for displaying jpeg analysis)
  • exiftool (optional)
    • Make available in the path (used for displaying jpeg analysis)

Test Machine(s)

  • Windows (XP or later) (if you use 64-bit you will need WebPagetest 2.9 or later to support traffic shaping)


Configuring

The zip archive contains 2 folders.  The www folder is the web server software and the agent folder is for the Test Machine(s).  The configuration files in the archive have a .sample extension so if you are updating an existing install you can just overwrite the current files with the new ones from the archive.

New in the 2.8 release is a script that will check for common configuration issues.  It can be accessed at http://<your web server>/install

Web Server

  1. Configure Apache with the required modules and set to allow for .htaccess overrides.
    • A sample site configuration file might look like this:
      <Directory "/var/www/webpagetest">
              AllowOverride all
              Order allow,deny
              Allow from all
      </Directory>
      <VirtualHost *:80>
              DocumentRoot /var/www/webpagetest
      </VirtualHost>
  2. If you will be using agents that upload .pcap files, consider setting upload_max_filesize and post_max_size to large values (10mb should be enough) and in php.ini.
  3. If you will be collecting Chrome dev tools traces, consider setting memory_limit to a large value or disabling the memory limit by setting it to -1.
  4. Using the PHP DSO handler mod_php can dramatically reduce the CPU required when working with large numbers of agents uploading results.
  5. Restart Apache to use new configuration settings.
  6. Copy the files from the www folder in the archive to the DocumentRoot location (e.g. /var/www/webpagetest).
  7. Grant the apache user read/write permissions to the following folders under the DocumentRoot:
    • tmp
    • dat
    • results
    • work/jobs
    • work/video
    • logs
  8. There are several settings files in the settings folder that can be used to configure the site.  Make a copy of all of the .sample files (removing the .sample extension) as a template for your configuration settings.  Most of the settings can be used as-is with the exception of locations.ini (particularly if you are configuring more than one test location).
  9. More information on configuring locations.ini is available here:  https://sites.google.com/a/webpagetest.org/docs/private-instances/locations   

Test Machine(s)

General Machine Configuration (common for all browsers)

  1. Configure the test system to automatically log-on to an administrator account. Running "control userpasswords2" from the start menu is one way to configure it.
  2. Disable any screen savers (the desktop needs to remain visible for the video capture to work)
  3. Disable UAC (Vista or later - slide to "never notify")
  4. Uninstall IE Enhanced-Security Mode (Windows Server)
  5. Force windows to use a stable clock if running in a VM (particularly KVM)
    • /USEPMTIMER to boot.ini for XP or Server 2003
    • "bcdedit /set {default} useplatformclock true" from an administrator shell otherwise
  6. Configure Windows to boot directly to the desktop (Server 2012)
  7. Disable Shutdown Event Tracker (Windows Server - for convenience)
    • run gpedit.msc
    • Open "Computer Configuration\Administrative Templates\System"
    • Open "Display Shutdown Event Tracker"
    • Set it to disabled
  8. Copy the test software from the agent folder to the system (to "c:\webpagetest" for this example)
  9. Install the DUMMYNET ipfw driver
    • If you are installing on 64-bit Windows, right-click on  "testmode.cmd" in the c:\webpagetest\dummynet\64bit folder and select "Run as Administrator".  Reboot the system to enable testmode.  If you do not run this then traffic shaping will not work after a reboot.
    • Copy the files from either the webpagetest\dummynet\32bit or webpagetest\dummynet\64bit directory into the webpagetest\dummynet directory (depending on your OS)
    • Pull up the properties for the Network Adapter that is used to access the Internet
    • Click "Install"
    • Select "Service" and click "Add"
    • Click "Have Disk" and navigate to webpagetest\dummynet
    • Select the ipfw+dummynet service (and click through any warnings about the driver being unsigned)

wptdriver (Chrome, Firefox, Safari, IE 6-10)

  1. You need a separate machine/VM for each version of IE but the rest of the browsers can all be run on the same machine and share a machine with IE (tests will not run at the same time, they will alternate)
  2. Create a shortcut to c:\webpagetest\wptdriver.exe in the startup folder
    • On Windows Server 2012 you will need to use task scheduler and create a logon task to run
  3. Make a copy of the settings file (wptdriver.ini) based on the sample
    • wptdriver can automatically install Chrome and Firefox (and keep Firefox up to date). If you would prefer to manually install the browsers then remove the installer=... entry for each of the browsers you want tp manually install
    • If you will be using Safari, download and install it
    • After installing safari you need to launch it and configure a few things manually
      • Dismiss the dialog that asks if you want it to be the default browser and tell it to never ask again
      • Go into the settings and set the start page to be about:blank
      • Drag the WebPagetest safari extension (c:\webpagetest\safari\wpt.safariextz) onto the browser to install it
    • Make sure the path to the browser executables are correct for your system (if you are automatically installing Chrome and Firefox they will only install after the first time you run wptdriver)
    • Configure the location to match the location defined on the server in locations.ini
    • Configure the location key to match the server in locations.ini
    • Make sure the available browsers in the ini file match the list defined in locations.ini in the browsers=x,y,z entry for the location.
  4. Launch wptdriver and let it install any software it needs to install (exit when it gets to "waiting for work").
  5. Launch Internet explorer and enable the WPT BHO plugin if prompted.
  6. Reboot to make sure everything starts up correctly

URLBlaster (legacy IE testing - IE 9 and earlier)

  1. Create a shortcut to c:\webpagetest\urlblast.exe in the startup folder
    1. On Windows Server 2012 you will need to use task scheduler and create a logon task to run
  2. Make a copy of the settings file (urlblast.ini) based on the sample
    • Give it the path to the server (default configuration points to a server on the local machine)
    • Configure the location to match the location defined on the server in locations.ini (if modified)
    • Configure the location key to match the server in locations.ini (if modified)
  3. Reboot to make sure everything starts up correctly 

If you connect a remote desktop to the test machine, make sure to reboot the machine when you are done, otherwise the desktop will remain locked and screen captures will not work.

Mobile

The mobile agent instructions are available here.


EC2 Test Agents

We have prepared public AMI's for EC2 that can be used as WebPagetest testers that are configured dynamically through the instance user data. The images have all of the software needed on a test system installed and configured (including AVISynth for generating videos and dummynet for doing the traffic shaping).

Configuration

The configuration of the test agents is done through user data strings when instances are started.

Parameters

  • wpt_server - the web server where WebPagetest is running (required)
  • wpt_loc - The location name to use for wptdriver (optional - if not specified it will fall back to wpt_location or be built from the region - ec2-us-east for example)
  • wpt_location - The location name to use for URLBlast (optional - if not specified it will be built from the region and browser - ec2-us-east-IE8 for example).  wptdriver will append _wptdriver to this location ID if wpt_loc is not set.
  • wpt_key - secret key for the specified location (optional)
  • wpt_timeout - timeout setting for each test in seconds (optional, defaults to 60)

Example User Data string

wpt_server=www.webpagetest.org wpt_location=Test wpt_key=xxxxx


Sample locations.ini

A sample locations.ini for the server is available that is configured with all of the available EC2 regions: http://webpagetest.googlecode.com/svn/trunk/www/webpagetest/settings/locations.ini.EC2-sample

AMI Images

The IE7 and IE8 instances were built on "small" instances and are configured to run off of instance storage.  The IE9/Chrome/Firefox instances are EBS-backed Windows 2008 instances that can run as small or medium instances. Medium instances are highly recommended for more consistent test results. Unless you have very intermittent testing needs, stay away from the t* instance sizes because they have variable performance.  A good test and review of the instance sizing for agents can be found here.

Note, the IE9/Chrome/Firefox instances will poll for 2 different locations:

IE 9 - will poll for the location specified in the user data (EC2_Dulles_IE8 in the example above)
Chrome/Firefox - will poll for <location>_wptdriver (EC2_Dulles_IE8_wptdriver in the example above) and is expecting locations.ini to be configured with "browser=Chrome,Firefox"

The wptdriver instances (IE 9, 10 and 11) must have a matching browser name in locations.ini for the version of IE in the AMI ("IE 9", "IE 10" or "IE 11").

The IE9/Chrome/Firefox instance will automatically install the latest supported versions of Chrome, Firefox, Flash Player and Silverlight when they start up (and will automatically update while they are running)

Finding the Images (aka EC2 AMI search sucks)

If you are having trouble finding the AMI's for manual launching, it's because EC2's AMI search is pretty broken.  I've found this path to work:

  • Do NOT search for the AMI in the Images->AMIs interface
  • Go to Instances->Instances (or spot instances)
  • Launch Instance
  • Select "Community AMIs"
  • Check "Windows"
  • Put the AMI ID in the search box and hit enter

us-east (Virginia)

  • IE7 - ami-fe689397 : wpt-virginia/ie7-20110703.manifest.xml
  • IE8 - ami-406f9429 : wpt-virginia/ie8-20110703.manifest.xml
  • IE9/Chrome/Firefox/Safari - ami-c262d9ab : 314854558937/ie9-20121031
  • IE9/Chrome/Firefox/Safari (2014, wptdriver only) - ami-261cb14e
  • IE10/Chrome/Firefox/Safari (2014, wptdriver only) - ami-2a1cb142
  • IE11/Chrome/Firefox/Safari (2014, wptdriver only) - ami-561cb13e

us-west (California)

  • IE7 - ami-919dcfd4 : wpt-california/ie7-20110703.manifest.xml
  • IE8 - ami-5982d01c : wpt-california/ie8-20110703.manifest.xml
  • IE9/Chrome/Firefox/Safari - ami-d53d1b90 : 314854558937/ie9-20121031
  • IE9/Chrome/Firefox/Safari (2014, wptdriver only) - ami-d9c9dd9c
  • IE10/Chrome/Firefox/Safari (2014, wptdriver only) - ami-cbc9dd8e
  • IE11/Chrome/Firefox/Safari (2014, wptdriver only) - ami-dfc9dd9a

us-west-2 (Oregon)

  • IE7 - ami-68a42958 : wpt-oregon/ie7-20110703.manifest.xml
  • IE8 - ami-2ca4291c : wpt-oregon/ie8-20110703.manifest.xml
  • IE9/Chrome/Firefox/Safari - ami-3ca3360c : 314854558937/ie9-20121031
  • IE9/Chrome/Firefox/Safari (2014, wptdriver only) - ami-9f0148af
  • IE10/Chrome/Firefox/Safari (2014, wptdriver only) - ami-ad01489d
  • IE11/Chrome/Firefox/Safari (2014, wptdriver only) - ami-950148a5

eu-west (Ireland)

  • IE7 - ami-70b18004 : wpt-ireland/ie7-20110703.manifest.xml
  • IE8 - ami-00b18074 : wpt-ireland/ie8-20110703.manifest.xml
  • IE9/Chrome/Firefox/Safari - ami-8b2c2fff : 314854558937/ie9-20121031
  • IE9/Chrome/Firefox/Safari (2014, wptdriver only) - ami-ccc76fbb
  • IE10/Chrome/Firefox/Safari (2014, wptdriver only) - ami-f4c76f83
  • IE11/Chrome/Firefox/Safari (2014, wptdriver only) - ami-d0c76fa7

eu-central (Frankfurt)

  • IE9/Chrome/Firefox/Safari (2014, wptdriver only) - ami-50291f4d
  • IE10/Chrome/Firefox/Safari (2014, wptdriver only) - ami-56291f4b
  • IE11/Chrome/Firefox/Safari (2014, wptdriver only) - ami-54291f49

ap-southeast (Singapore)

  • IE7 - ami-38bac26a : wpt-singapore/ie7-20110703.manifest.xml
  • IE8 - ami-92bac2c0 : wpt-singapore/ie8-20110703.manifest.xml
  • IE9/Chrome/Firefox/Safari - ami-7c14572e : 314854558937/ie9-20121031
  • IE9/Chrome/Firefox/Safari (2014, wptdriver only) - ami-7e2e0e2c
  • IE10/Chrome/Firefox/Safari (2014, wptdriver only) - ami-4a2e0e18
  • IE11/Chrome/Firefox/Safari (2014, wptdriver only) - ami-7a2e0e28

ap-northeast (Tokyo)

  • IE7 - ami-ba16bcbb : wpt-tokyo/ie7-20110703.manifest.xml
  • IE8 - ami-bc16bcbd : wpt-tokyo/ie8-20110703.manifest.xml
  • IE9/Chrome/Firefox/Safari - ami-b465dbb5 : 314854558937/ie9-20121031
  • IE9/Chrome/Firefox/Safari (2014, wptdriver only) - ami-4bb2804a
  • IE10/Chrome/Firefox/Safari (2014, wptdriver only) - ami-05b28004
  • IE11/Chrome/Firefox/Safari (2014, wptdriver only) - ami-27b28026

ap-southeast-2 (Sydney)

  • IE7 - ami-2b40d711 : wpt-sydney/ie7-20110703.manifest.xml
  • IE8 - ami-2940d713 : wpt-sydney/ie8-20110703.manifest.xml
  • IE9/Chrome/Firefox/Safari - ami-6cb82956 : 314854558937/ie9-20121031
  • IE9/Chrome/Firefox/Safari (2014, wptdriver only) - ami-4fa8c475
  • IE10/Chrome/Firefox/Safari (2014, wptdriver only) - ami-5da8c467
  • IE11/Chrome/Firefox/Safari (2014, wptdriver only) - ami-55a8c46f

sa-east (Sao Paulo)

  • IE7 - ami-622ff07f : wpt-saopaulo/ie7-20110703.manifest.xml
  • IE8 - ami-9c2ff081 : wpt-saopaulo/ie8-20110703.manifest.xml
  • IE9/Chrome/Firefox/Safari - ami-1c4a9301 : 314854558937/ie9-20121031
  • IE9/Chrome/Firefox/Safari (2014, wptdriver only) - ami-eba611f6
  • IE10/Chrome/Firefox/Safari (2014, wptdriver only) - ami-fba611e6
  • IE11/Chrome/Firefox/Safari (2014, wptdriver only) - ami-eda611f0

Updating Test Agents

The test agents will automatically update their code from the server if there are update files in place (in /work/update on the server).  Each update consists of a zip file (the actual updata) and an ini file that contains some meta-data about the update (most importantly, the software version).  There are separate updates for the IE agent (update.zip/update.ini) and the Chrome/Firefox agent (wptupdate.zip/wptupdate.ini).

Each new release includes updated agent binaries but sometimes it is helpful or necessary to update the agents in between releases if you need a bug fix or functionality that has been made available on the public instance but that hasn't been packaged up in a new release yet.  In this case you can download the update from the public instance of WebPagetest and deploy it on your private instance (the agents are backwards compatible so you do not need to update the web code unless you need updated functionality there).  To download and update:

After uploading the updates, each agent will automatically download and install the update before running their next test so you can be guaranteed that the update will be deployed before any more testing occurs.


Troubleshooting

Web Server

  • Waiting at the front of the queue
    • Commonly the issue is in your locations.ini. Double check that your location settings match that of which your agent is pulling the server with. Also note if you're using a key, do they match. You can check your Apache access logs for incoming requests being made by your test agent. 
  • The test completed but there were no successful results
    • If you're using a 64-bit Windows client you will be unable to perform traffic shaping (using dummynet.) In your locations.ini, add connectivity=LAN to the test location.
  • Waterfall charts are missing
    • Check if the GD library is installed. The GD library is used for drawing the waterfalls and generating thumbnail images.
    • Look to see if php-zip, php5-zip or a similar zip library is installed. With some default PHP distributions the library is not present.
  • Screen captures are black
    • When disconnecting from RDP, try rebooting the instance versus disconnecting from the RDP client. RDP locks up the desktop when you disconnect which will cause the screen shots and video to break.
  • Error message like this in /var/log/apache2/error.log:
    • [Mon Apr 30 10:18:14 2012] [error] [client 1.2.3.4] PHP Warning: POST Content-Length of 22689689 bytes exceeds the limit of 8388608 bytes in Unknown on line 0
    • PHP enforces a limit on the size of uploaded files, and an agent is uploading something larger than this limit. Change upload_max_filesize and post_max_filesize to larger values in php.ini.

Test Agent

  • Low disk space
    • WebPagetest doesn't maintain any temporary files but sometimes Windows itself leaves stuff lying around and the disks can fill up. When that happens there are a few common things you can do to clean it up:
      • You can delete everything in "C:\Windows\SoftwareDistribution\Download". Windows keeps the full installer for every software update it installs and it doesn't need them after the install.
      • Try right-clicking on the c drive -> properties -> Disk Cleanup. There might be some crash reports it can cleanup
    • If that doesn't free enough space there are a few more things you can do:
      • Use windirstat to see what is taking up the disk space
      • It's possible the IE temporary Internet files got corrupt and is growing out of control. CCleaner can help fix that sometimes
      • Make sure hibernation is disabled (no hiberfile.sys on the c drive)
      • Worst case, you can disable the swap file to get back a gig or two