Setting up a WebPageTest.org private instance

5 min readMay 11, 2016

WebPageTest.org, in my opinion, is by far the best web page testing tool out there. From loading statistics, to flow graphs, to filmstrip images of your rendering process, when you need to debug the delivery of a website from a server to the user’s screen, that is where you go.

My master thesis required some of these statistics, and I was very happy to see that they offer an API to run tests and collect the results, it came very handy! The problem came when I needed to execute a ton of tests that exceeded the 200 tests per day limit of the API. Instead of requesting you to pay for more tests, they instead let you run your own instance of the whole service, so you can use it for as long as you need! But it’s no walk in the park, by far.

From this point on, this is an instructional guide on how I set up an instance. There is an awesome guide from VoxMedia which I followed as well, but ran into some additional issues, so this is a summery to those who will be in need of running their own instances.

5 step tutorial

In order to make this as easy as possible to set up, we will use Amazon EC2 instances to launch server that will host the application that queues, requests test and gathers results — from here on called the master, and another server to actually run the tests in browsers — called the slave.

Documentation on these is available on Google Sites and GitHub, but what you first will want to do is to create an Amazon account (if you don’t have one), and add some billing information. Every instance we launch will cost money, and based on it’s performance, you can see how much you will need to chug out here.

Step 1 — Set up a master

Based on the region you have selected in your AWS account (look in the top right here), select one of these pre-configured instances of the master.

us-east-1: ami-fcfd6194
us-west-1: ami-e44853a1
us-west-2: ami-d7bde6e7
sa-east-1: ami-0fce7112
eu-west-1: ami-9978f6ee
eu-central-1: ami-22cefd3f
ap-southeast-1: ami-88bd97da
ap-southeast-2: ami-eb3542d1
ap-northeast-1: ami-66233967

The process to creating is pretty straight forward, select an instance type that meets your requirements. My suggestion is that you go for a m2.* instance, since in testing it shows little deviation, but if you just want to fool around with the server, take the t2.micro since it’s eligible for some free runtime credits if you are new to AWS. Also, take a look at note #2 on the end of this page regarding storage!
Once selected, skip over to Configure Security Group setting page, and add HTTP and HTTPS traffic as allowed. Save the instance (and the accompanying SSH key) and launch it.

Step 2 — Set up an Elastic IP

The slave will need to connect to the master once it’s up and running, and in order to accomplish that, we will need to have a static IP address for the master instance we just created. Head over to the Elastic IPs section in the AWS console, allocate a new address, right click it and associate it with the master instance.

Step 3 — Set up a slave

In order to find the instance for our slave(s), you will need to go over this list. Don’t let it overwhelm you with information, all you are looking for AMI ID for the region that you have your master instance in. If you are in US_East then look for the section that start with that title:

[US_East]
; AMI: ami-0f7eae66
; user-data: wpt_server=www.yourserver.com wpt_key=SecretKey wpt_location=US_East
browser=IE 9
latency=0
label="US East (Virginia) - IE9"
key=SecretKey

The ami-XXXXXXXX ID is what we need, so copy the whole thing down, go back to the AWS console, and from the instances list, click Launch new instance. Head over to the Community AMIs section, and paste in the AMI ID that we copied in the search box. If you did this right, a Windows AMI should appear. If not, you probably copied an AMI from a wrong region. Launch the AMI with the same addition of allowing HTTP and HTTPS traffic to it.

Step 4 — Let baby call it’s mama

This is the part I was most confused about. How the hell do the 2 separate instances know they exist?

Well, head over to your new slave instance, right click it and find the View/Change User Data submenu (make sure the instance is turned off, otherwise it will not allow you to edit the data). Inside, you will need to paste in the line below, remembering to change the values in it (the IP of the master that we assigned in step 2, and a name of the slave node that you NEED TO REMEMBER).

wpt_server=IP_OF_MASTER_HERE wpt_location=NAME_OF_SLAVE_HERE

Now go ahead and launch both instances.

Step 5 — Configuring Master

Using the SSH key you got from step 1, log into the server’s elastic IP (if you don’t know how to do this, check out Putty as an SSH client, and PuttyGen to generate a Putty supported private key from the one Amazon gave you). When it asks you for a user, enter ubuntu. All that remains is to edit 2 files in the following directory:

/var/www/webpagetest/www/settings

First open settings.ini, scroll all the way to the end of the file, and set ec2_locations and ec2 both to 0.
Next, open locations.ini, and add the following lines, remembering to replace NAME_OF_SLAVE_HERE with the actual name you assigned in the user data in step 4.

[locations]
1=EC2
default=EC2 [EC2]
1=NAME_OF_SLAVE_HERE_wptdriver
2=NAME_OF_SLAVE_HERE-WPT
label="My awesome tester agent"
default=NAME_OF_SLAVE_HERE-WPT_wptdriver[NAME_OF_SLAVE_HERE-WPT_wptdriver]
browser=Chrome,Firefox
label="My awesome tester agent with wptdriver"[NAME_OF_SLAVE_HERE-WPT]
browser=IE 9
label="My awesome tester agent"

If you did everything well, let that settle in for a minute, and then check the http://ELASTIC_IP_OF_MASTER/install URL. Down in it’s end, you should see the name of the slave, with a green checkmark stating that 1 agent is connected.

Notes

In order to use the API to call tests on the server, get the existing one, or add a new key to keys.ini
If your instance has EBS storage, it will only retain the custom data on it while it’s launched (custom data being test data, and all changes we made in step 5). If you turn it off, you will need to redo that step in order to make it functional again.