Documentation / Docker


Containers #

Docker is the preferred installation method because every dependency is handled for you for all the features in

We have a ready made container with Chrome, Firefox & Xvfb. It also contains FFMpeg and Imagemagick, so we can record a video and get metrics like SpeedIndex using VisualMetrics.

Structure #

The Docker structure looks like this:

NodeJS with Ubuntu 18 -> VisualMetrics dependencies -> Firefox/Chrome/xvfb ->

The first container installs NodeJS (latest LTS) on Ubuntu 18. The next one adds the dependencies (FFMpeg, ImageMagick and some Python libraries) needed to run VisualMetrics. We then install specific version of Firefox, Chrome and lastly xvfb. Then in last step, we add and tag it to the version number.

We lock down the browsers to specific versions for maximum compatibility and stability with’s current feature set; upgrading once we verify browser compatibility.

Running in Docker #

The simplest way to run using Chrome:

docker run --rm -v "$(pwd)":/ sitespeedio/ -b chrome

In the real world you should always specify the exact version (tag) of the Docker container to make sure you use the same version for every run. If you use the latest tag you will download newer version of as they become available, meaning you can have major changes between test runs (version upgrades, dependencies updates, browser versions, etc). So you should always specify a tag after the container name(X.Y.Z). Know that the tag/version number will be the same number as the release:

docker run --rm -v "$(pwd)":/ sitespeedio/ -b chrome

If you want to use Firefox:

docker run --rm -v "$(pwd)":/ sitespeedio/ -b firefox

Using -v "$(pwd)":/ will map the current directory inside Docker and output the result directory there.

More about volumes #

If you want to feed with a file with URLs or if you want to store the HTML result, you should setup a volume. will do all the work inside the container in a directory located at / To setup your current working directory add the -v “$(pwd)”:/ to your parameter list. Using “$(pwd)” will default to the current directory. In order to specify a static location, simply define an absolute path: -v /Users/sitespeedio/html:/

If you run on Windows, it could be that you need to map a absolute path. If you have problems on Windows please check

Update (download a newer #

When using Docker upgrading to a newer version is super easy, change X.Y.Z to the version you want to use:

docker pull sitespeedio/

Then change your start script (or where you start your container) to use the new version number.

Synchronise docker machines time with host #

If you want to make sure your containers have the same time as the host, you can do that by adding -v /etc/localtime:/etc/localtime:ro (Note: This is specific to Linux).

Full example:

docker run --rm -v "$(pwd)":/ -v /etc/localtime:/etc/localtime:ro sitespeedio/ -b firefox

Setting time zone #

If you want your container to run in a specific time zone you can do that with TZ.

docker run -e TZ=America/New_York --rm -v "$(pwd)":/ sitespeedio/ -n 1

Change connectivity #

To change connectivity you should use Docker networks, read all about it here.

Access localhost #

If you run a server local on your machine and want to access it with you can do that on Mac and Windows super easy if you are using Docker 18-3 or later by using host.docker.internal.

docker run --rm -v "$(pwd)":/ sitespeedio/ -b firefox http://host.docker.internal:4000/

If you are using Linux you should use --network=host to make sure localhost is your host machine.

docker run --rm -v "$(pwd)":/ --network=host sitespeedio/ -b firefox http://localhost:4000/

Extra start script #

You can run your extra start script in the Docker container:

docker run -e EXTRA_START_SCRIPT=/ --rm -v "$(pwd)":/ ...`. 

Troubleshooting #

If something doesn’t work, it’s hard to guess what’t wrong. Then hook up x11vnc with xvfb so that you can see what happens on your screen.

Inspect the container #

We autostart when you run the container. If you want to check what’s in the container, you can do that by changing the entry point.

docker run -it --entrypoint bash sitespeedio/

Visualise your test in XVFB #

The docker containers have x11vnc installed which enables visualisation of the test running inside Xvfb. To view the tests, follow these steps:

  • You will need to run the image by exposing a PORT for vnc server. By default this port is 5900. If you plan to change your port for VNC server, then you need to expose that port.
docker run --rm -v "$(pwd)":/ -p 5900:5900 sitespeedio/ -b chrome
  • Find the container id of the docker container for sitespeed by running:
docker ps
  • Now enter into your running docker container for by executing:
docker exec -it <container-id> bash
  • Find the Xvfb process using ps -ef. It should be using DISPLAY=:99.
  • Run
x11vnc -display :99 -storepasswd

Enter any password. This will start your VNC server which you can use by any VNC client to view:

  • Download VNC client like RealVNC
  • Enter VNC server :
  • When prompted for password, enter the password you entered while creating the vnc server.
  • You should be able to view the contents of Xvfb.