Skip to content

Installing with Docker

Docker gives you an isolated, reproducible environment where Python, Node, browsers and every test tool are already installed. It's the simplest route on a server.

The image is built on Sitespeed.io's official image.

Prerequisites

Mac with Apple Silicon

Enable "Use Rosetta for x86/amd64 emulation" in Docker Desktop's settings. Sitespeed.io explains why.

Quickstart 

docker run -it --rm \
  --shm-size=4g \
  -e MAX_OLD_SPACE_SIZE=3000 \
  webperfse/webperf-core:latest \
  python default.py -u https://example.com -t 22 -r

The flags

Flag What it does
-it Interactive mode with a terminal
--rm Remove the container when the run finishes
--shm-size=4g Shared memory for Chrome and Firefox
-e MAX_OLD_SPACE_SIZE=3000 Node.js heap size in MB

The same values (--shm-size=4g -e MAX_OLD_SPACE_SIZE=3000) are what the project itself uses when regression-testing the image, so they're a proven starting point.

Interactive mode

Start a container and run several commands in it:

docker run -it --rm \
  --shm-size=4g \
  -e MAX_OLD_SPACE_SIZE=3000 \
  webperfse/webperf-core:latest \
  bash

Once inside:

python default.py --dependency
python default.py -u https://webperf.se -t 22 -r

Save results on the host

Mount a folder and write the report into it:

mkdir -p reports

docker run -it --rm \
  --shm-size=4g \
  -e MAX_OLD_SPACE_SIZE=3000 \
  -v "$(pwd)/reports:/usr/src/runner/output" \
  webperfse/webperf-core:latest \
  python default.py -u https://example.com -t 22 -o output/report.json

Your own image with your own files

If you have a custom settings.json or sites.json, it's convenient to bake them in. Create a Dockerfile:

FROM webperfse/webperf-core:latest

COPY settings.json /usr/src/runner/settings.json
COPY sites.json /usr/src/runner/sites.json

Build and run:

docker build -t my-webperf:latest .

docker run -it --rm \
  --shm-size=4g \
  -e MAX_OLD_SPACE_SIZE=3000 \
  my-webperf:latest \
  python default.py -i sites.json -t 22

Keeping your own files in a separate repository means you can bump the base tag without re-applying your changes.

IP2Location is needed for the GDPR ratings

If you build the image from source you should also obtain your own copy of data/IP2LOCATION-LITE-DB1.IPV6.BIN. Without it, the GDPR-related parts of the ratings can't be calculated.

Building from source 

git clone https://github.com/Webperf-se/webperf_core.git
cd webperf_core
docker build -t webperf-local:latest .

Expect it to take a while. The docker/ folder contains ready-made PowerShell scripts for building and for running with a mounted folder.

Resources

Parameter Recommended What it does
--shm-size 4g Shared memory for the browsers
--cpus 0.9 Limits how much CPU the container may take
MAX_OLD_SPACE_SIZE 3000 Node.js memory in MB

Keep the memory values straight

MAX_OLD_SPACE_SIZE is in MB and should be lower than --shm-size. Setting them the other way round produces hard-to-read crashes mid-run.

Troubleshooting

Lighthouse fails with NO_NAVSTART

A known problem with Chrome in Docker. Increase --shm-size, run again, or switch browser:

--setting tests.sitespeed.browser=firefox
The container won't start

Check that Docker is running and has enough memory allocated in its settings.

The result isn't saved

Make sure the mounted folder exists and is writable, and that the path you pass to -o points into it.

Scripts for repeated runs 

#!/bin/bash
URL=${1:-"https://example.com"}
TESTS=${2:-"22"}

docker run -it --rm \
  --shm-size=4g \
  -e MAX_OLD_SPACE_SIZE=3000 \
  webperfse/webperf-core:latest \
  python default.py -u "$URL" -t "$TESTS" -r

chmod +x run-test.sh
./run-test.sh "https://example.com" "22,9"

param(
    [Parameter(Mandatory=$true)]
    [string]$Url,
    [string]$Tests = "22"
)

docker run -it --rm `
  --shm-size=4g `
  -e MAX_OLD_SPACE_SIZE=3000 `
  webperfse/webperf-core:latest `
  python default.py -u $Url -t $Tests -r

.\run-test.ps1 -Url "https://example.com" -Tests "22,9"

Next steps