How to Quickly Set Up a Private WebPageTest Server And Client

Get your own WebPageTest server and test agent up and running in minutes, not hours!

Motivation

The original documentation can be found here and here. Unfortunately, it's a bit vague in some parts, especially if you don't set up infrastructural pieces and cloud server instances on a daily basis. So here's a how-to guide to get you up and running as fast as possible.

Infrastructure overview

To run web page tests against your own private instance, we need:

• a WebPageTest server instance (the master)
• one ore more WebPageTest test agents (the clients)

The master receives test jobs and delegates them to one of the clients. You can run tests from the web interface or using the API through the webpagetest node module.

You might want to think about where in the world you want to spin up those virtual machines. The WPT server (master) can really be hosted anywhere you want but the test agents (client) location should be chosen conciously because their distance to the tested site's server will play a role in the results you will see later during testing.

How to set up the master (WPT server)

You need an Amazon AWS account to set this up quickly. If you haven't got one, you either quit here and set up your own server with the WebPageTest stack, or you go and create one.

Now, go to your AWS dashboard, to Instances –> Instances, and click "Launch Instance":

On the next screen, go to Community AMIs, enter one of the ids that can be found here – I chose ami-22cefd3f (eu-central-1) – and hit "Select":

In step 2, you can choose a t2.micro instance. The WPT server does not need to be high performance – it only delegates test execution and gathers the results. It's when setting up the client (test agent), that we'll have to pay attention to the performance of the instance.

Now, you keep clicking Next until you reach "Step 6. Configure Security Group". Here we need to add a firewall rule that allows us to access our WPT server (master) through HTTP, otherwise no testing will be possible. Giving the security group a more descriptive name and description (❸) is optional but nice:

In step 7, review your settings if you want, then hit "Launch":

As highlighted in the screen above, AWS will now want to assign a (ssh) key pair to this instance.

In case you have an existing key pair you can re-use that.

In case you're doing this for the first time, you won't have any existing key pairs to choose from and will have to create a new one. The "Launch Instances" button will activate only after you've downloaded your private key (❸):

Clicking ❷ gets you to the Instances overview that was empty at the beginning where you'll find the public IP address and DNS entry of your instance:

Congratulations, you've successfully completed the setup of the WPT server (master)! If you now open http://your.instance.ip you should see the WebPageTest UI:

To log into your instance via SSH follow one of the guides here. In short:

1. Either use ssh from the command line, available on all linuxes and even on Windows if you have Git installed, e.g. in C:\Program Files\Git\usr\bin:
   • ssh -i wpt-server.pem ubuntu@[public-ip|public-dns]
2. Or, on Windows, use PuTTY. In this case you'll first have to generate a PuTTY compatible private key file from your *.pem file and then you can connect through PuTTy. Here's how to do that.

How to set up the client (WPT test agent)

Now, we need to set up at least one test agent to actually execute some tests. There's a long list of pre-configured, regularly updated Windows AMIs with all software installed that's needed to execute tests in the documentation. To get started quickly, pick one that contains all major browsers and is located in your favorite region. In this guide, we're going to use ami-54291f49 (IE11/Chrome/Firefox/Safari) in region "eu-central (Frankfurt)".

Basically, we repeat the steps from the master setup, but now using the test agent AMI.

In step 2, when choosing an Instance Type, we'll now have to ensure that our agent will deliver consistent results. This performance review recommends the following choices (prices will vary by region, the ones displayed here were for US East N. Virginia), quoting:

• If you’re running just a couple tests per hour, on small HTTP sites, a t2.micro will be okay ($13/month)
• If you’re running just a couple tests per hour, on large or secure sites, you’ll need to use a t2.medium ($52/month)
• If you’re running lots of tests per hour, you can’t use t2’s –  the most efficient agent will be a c3.large ($135/month)

In step 3, we have to configure our test agent with the following information:

• where to find the WPT server (master): use the public IP address or DNS name
• what's the location (name) of this agent: a string used in the locations.ini of the master

To be honest, I haven't quite wrapped my head around the auto-scaling feature of WPT. That's why we set up a single location ("first") manually that this client will be identified with. In the user data field under Advanced Details we enter:

• wpt_server=52.29.your.ip   wpt_location=first

Now, either click your way through the remaining steps or jump to "Review and Launch" and launch your test agent instance. The key pair dialog will pop up again, and now you can choose your existing key "wpt-server" to assign to that instance. You won't use it to connect to it, anyway, because the default connection type to a Windows instance is RDP for which a firewall rule was automatically added in step 6.

After launching, a link will be available with instructions on how to connect to that Windows instance, but you shouldn't need to do that.

Connecting master and client

One step is left: we have to configure the master to know which test agents it can use.

This part was actually one of the most tedious bits in the setup because juggling several configuration files with lots of options and entries to make them do what you want them to do is never easy.

For the manual management of test agents we need to do the following:

1. Log into the master, e.g. ssh -i wpt-server.pem ubuntu@pu.bl.ic.ip
2. Go to the folder /var/www/webpagetest/www/settings/
3. Edit locations.ini to contain these blocks (sudo nano locations.ini):

   [locations]
   1=first
   default=first
   
   [first]
   1=first_wptdriver
   2=first_ie
   label="My first agent"
   default=first_wptdriver
   
   [first_wptdriver]
   browser=Chrome,Firefox,Safari
   
   [first_ie]
   browser=IE 11

4. In settings.ini, at the very end, set ec2_locations=0 to hide the predefined EC2 locations from the location dropdown in the browser.
5. Restart NGNIX: sudo service nginx restart

Now, if you go to http://your.public.ip again, you'll see "My first agent" in the location dropdown and "Chrome", "Firefox", and "Safari (Windows)" in the browser dropdown. I didn't try to find out how to show "IE 11" as well, but at this moment I didn't care. (You might have to wait a few moments before the location lists update after the NGINX restart.)

You can now run your first test!

After some 10-15 seconds you should see this screen:

And a few moments later the first results should show. Congratulations!

Automating tests via the WebPageTest API

If you've tried to run WebPageTests in an automated way, you'll without a doubt have found the webpagetest node module. With your private server and test agent set up, you'll now need to dispatch your tests like so:

webpagetest test http://my.example.com ↵
    --server http://<master_ip> ↵
    --key <api_key> ↵
    --location first_wptdriver:Chrome

The location argument refers to the definitions in the locations.ini file. The api key can be found in the keys.ini file on the master:

We run our test from within TeamCity using a custom script, but that's a topic for another post!

Happy WebPageTesting!