How to Quickly Set Up a Private WebPageTest Server And Client

by Oliver 14. November 2015 21:40

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


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
  2. Go to the folder /var/www/webpagetest/www/settings/
  3. Edit locations.ini to contain these blocks (sudo nano locations.ini):
    label="My first agent"
    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 ↵
    --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!

Comments (8) -

Antoine France
1/19/2017 12:24:34 AM #

So much times saved ! thanks to this guide !

Now it's working Smile

Thanks for your help !!!!!!


Kurt United States
3/16/2017 5:57:58 AM #

Nice set of directions. I'm trying  set up a Server/Agent instance for webpagetest on Amazon and getting nowhere. Any hints? This "5 minute" stuff is turning into 50 hours.


Oliver Poland
4/29/2017 9:55:07 PM #

@Kurt: What's not working?


Arek Poland
5/24/2017 11:39:58 AM #


thx for tutorial. I want to install my private instance of and I'm Wonder if there is posibility to install agent located in Poland/Warsaw.


Oliver Poland
5/31/2017 1:57:43 PM #

Hi Arek,

I'm not aware of any Amazon data/computing centers in Poland. If you need to have it on a Polish server you'll have to install both server and client/agent by hand. See for more info.


subham Mohapatra
subham Mohapatra India
1/4/2018 8:04:14 AM #

Hi Thanks for providing the detailed step.....

I followed all the steps but still for me its showing "no agent is connected" .

Below is my locations.ini file


label="My WptSlave agent"

ami= ami-03e80c63  //My agent server AMI
label="My WptSlave agent with wptdriver"
user_data="//my user data here"

browser=IE 9
ami= ami-03e80c63
label="My WptSlave agent"
user_data="//my user data here"

and in settings.ini also i have set as mentioned. Can you please help me to fix it


James United States
2/26/2019 4:44:30 PM #


I've followed the guide and I'm unable to connect the master and test agent. No matter what setting I use for the user data on the test agent, I keep getting the "No Agents Connected" issue.

I'm assuming something is wrong with the user data I'm putting in to connect the two. Have there been any updates with that process?


Oliver Poland
4/17/2019 1:37:34 AM #

Hi James,

I'm sorry my post didn't help. We've stopped using this setup, so I'm not able to help you out here. I hope you've found a solution to your problem.

Best wishes!


Add comment

  Country flag

  • Comment
  • Preview

About Oliver code blog logo I build web applications using ASP.NET and have a passion for javascript. Enjoy MVC 4 and Orchard CMS, and I do TDD whenever I can. I like clean code. Love to spend time with my wife and our children. My profile on Stack Exchange, a network of free, community-driven Q&A sites

About Anton code blog logo I'm a software developer at teamaton. I code in C# and work with MVC, Orchard, SpecFlow, Coypu and NHibernate. I enjoy beach volleyball, board games and Coke.