WebPageTest Private Instance in 5 Minutes or Less

Posted in Front End Engineering, Open Source, Web Performance, WebPageTest on by Rick Viscomi.

If you’re like me and you have ideas to help improve the WebPageTest public instance UI or you want to crush some bugs, you have a couple of development options. If it’s just a tweak to the styles or similar, you could verify the change live in browser developer tools and submit a small pull request to the GitHub repository. New features that are more complex can’t be done as easily on the fly. A development server should be used to ensure the changes work as intended and don’t break anything. So what are the options for testing WebPageTest locally?

Running WebPageTest on your laptop

My first choice is to run the development server on my laptop running OSX. For how easy it is, there are surprisingly few guides written on getting WebPageTest set up for ad hoc development. Here’s an overview of the process:

  1. Get a clean copy of the code.
  2. Configure the private instance.
  3. Configure Apache to point to the server.

The goal is to accomplish these three steps in under five minutes, so I may take some shortcuts or make assumptions about your development environment. I’ll be sure to note these along the way.

1. Clone the latest version from GitHub

If you want simple, this is it. Just download the master at https://github.com/WPO-Foundation/webpagetest/archive/master.zip. Save it anywhere.

Note: If you already have the GitHub Desktop application installed, here’s a shortcut that will clone the repository for you: github-mac://openRepo/https://github.com/WPO-Foundation/webpagetest

It would also be proper version control etiquette to create a new branch for your changes rather than work in the master branch.

2. Point the private instance to the public test agents

This is key. If we’re only interested in making changes to the UI, it’s totally unnecessary to spin up your own test agents. If your change doesn’t depend on live data at all, you could skip this step. For example, the home page is static and as long as you don’t have to submit a test, you can work entirely local. However, most of the site involves configuring and analyzing tests, which definitely requires live data. The trick is that you can let the public instance do the actual testing workload while your private instance simply pulls in the data and displays it.

The WebPageTest API

Now is a good time to bring up the API. Of course, if you already have an API key you can skip this part.

If you want to communicate with the public instance, you’ll need to be authorized. All API users have a unique key, which can be immediately obtained by filling out a short form at http://www.webpagetest.org/getkey.php. After submitting, you’ll be emailed a key. Save this for the next part.

Using the public test agents

If the goal is to simply get test results from an arbitrary test agent, any of the Dulles browsers will do as they’re provisioned for a healthy amount traffic — not that we’ll be producing much. To use one of these test agents, we’ll need to create a file at www/settings/locations.ini. Note that the source code is bundled with a locations.ini.sample file for reference.

The contents of this file should be:


label=”Dulles, VA”

label=”Dulles, VA – Chrome”

The relay server and location ensure that we use the public instance and the relay key authorizes the requests. You can skip the overhead of creating a blank file and copy/pasting the configuration above by downloading it as a gist from GitHub and saving it to the www/settings/ directory. Remember to use your own API key.

3. Configure Apache

OSX already includes Apache, which is needed to run the server, and PHP, which is needed to render the pages. This last step is only a matter of flipping switches and linking the two with WebPageTest.

Open the Apache configuration file at /etc/apache2/httpd.conf and update the following settings.

Enable PHP

#LoadModule php5_module libexec/apache2/libphp5.so
By default, PHP is disabled. Enable it by changing this to: LoadModule php5_module libexec/apache2/libphp5.so.

Give Apache read/write permissions

User _www
Group _www

Apache needs file permissions to save the test data. Instead of granting the Apache user (_www) these permissions, just run Apache as yourself. Change this to:
Group staff

In case you’re not sure, your username is the output of the whoami command.

Point to the server code

DocumentRoot "/foo"
<Directory "/foo">

This sets up the base file path from which requests will be served. By default it is pointing to some local file path (like /foo). So to point localhost to the WebPageTest web server, change this to:

Note: If you’ve already got Apache configured for something else, instead you may want to point to WebPageTest’s www directory for only a unique port number.

And that should be it! If you start Apache and navigate to localhost in your browser, you should see the WebPageTest home page. Now you’re ready to start the real work of making the UI changes.

You can find out more about how to use WebPageTest to analyze the performance of websites in my new book, Using WebPageTest.

3 thoughts on “WebPageTest Private Instance in 5 Minutes or Less

  1. JAY

    THANKS for posting such a wonderful blog!

    It really helped a lot!

    I’m trying to use similar way as you mentioned, “the goal is to simply get test results from an arbitrary test agent” – but I want to specifically use Banglore Headspin agent to test.

    my location.ini -

    label=”Dulles, VA”


    label=”Dulles, VA – Chrome”

    label=”Banglore- Vodafone 3G”

    when I submit the request – it says: “Testing completed but failed. Failed to configure IPFW/dummynet. Is it installed?”
    First View: Test Data Missing

    What should I do?


  2. Pingback: 27-12-2015 - This is the end of this year... so these are the leftover links - Magnus Udbjørg

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>