Chapter 11 · Docker Containerized Running

Chapter goals: Run Locust with the official Docker image, orchestrate master + workers distributed testing with Docker Compose, and learn custom image and OpenTelemetry image usage.

11.1 Why Run Locust in Docker

Local single-machine testing is convenient, but production-grade testing faces three problems:

1. Environment consistency — differing dependency versions across machines make results non-reproducible;
2. Resource isolation — load-test processes competing with app processes for CPU/memory skews results;
3. Rapid scaling — need to spin up multiple worker nodes on demand.

Docker solves all three: images lock the environment, containers provide natural isolation, and docker compose up --scale scales in one line.

11.2 Using the Official Image

The official image is hosted on Docker Hub as locustio/locust. Assuming your current directory has a locustfile.py:

docker run -p 8089:8089 -v $PWD:/mnt/locust locustio/locust -f /mnt/locust/locustfile.py

Parameter guide:

Parameter	Description
-p 8089:8089	Map container port 8089 (Web UI) to the host
-v $PWD:/mnt/locust	Mount current directory into the container so Locust can read the locustfile
-f /mnt/locust/locustfile.py	Specify the locustfile path

Windows users

Windows -v mounts sometimes fail; use --mount instead:

docker run -p 8089:8089 --mount type=bind,source=%cd%,target=/mnt/locust locustio/locust -f /mnt/locust/locustfile.py

After starting, visit http://localhost:8089 to see the Web UI.

Headless mode (no browser):

docker run -p 8089:8089 -v $PWD:/mnt/locust locustio/locust \
  -f /mnt/locust/locustfile.py --headless -u 100 -r 10 --run-time 60s

11.3 Docker Compose for Distributed Testing

Distributed testing needs a master node (dispatch tasks, aggregate results) and multiple worker nodes (generate actual load). This compose file orchestrates everything in one command:

# docker-compose.yml
version: '3'
services:
  master:
    image: locustio/locust
    ports:
      - "8089:8089"
    volumes:
      - ./:/mnt/locust
    command: -f /mnt/locust/locustfile.py --master -H http://master:8089

  worker:
    image: locustio/locust
    volumes:
      - ./:/mnt/locust
    command: -f /mnt/locust/locustfile.py --worker --master-host master

Key parameters:

Parameter	Description
--master	Mark this node as master
-H http://master:8089	Tell the master its own address (for workers to connect)
--worker	Mark this node as worker
--master-host master	Worker finds the master via the service name master

Start master + 4 workers:

docker compose up -d master
docker compose up -d --scale worker=4

Verify:

docker compose ps
# master    created
# worker-1  created
# worker-2  created
# worker-3  created
# worker-4  created

11.4 Custom Image and OpenTelemetry

For custom dependencies, build your own image:

# Dockerfile
FROM locustio/locust:latest
RUN pip install some-custom-package
COPY locustfile.py /mnt/locust/locustfile.py

docker build -t my-locust .
docker run -p 8089:8089 -v $PWD:/mnt/locust my-locust -f /mnt/locust/locustfile.py

For OpenTelemetry integration, use the official OTel image:

docker run -p 8089:8089 -v $PWD:/mnt/locust \
  locustio/locust:latest-otel \
  -f /mnt/locust/locustfile.py --locustfile /mnt/locust/locustfile.py

11.5 Chapter Summary

• Official image locustio/locust has all browser engines and system deps pre-installed;
• Docker Compose with --scale worker=N one-liner scales distributed testing;
• Custom Dockerfiles for third-party dependencies;
• OTel image for distributed tracing integration.

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. Why use Docker Compose --scale worker=4 instead of starting 4 separate containers?

2. What does the -v $PWD:/mnt/locust flag do?

3. How do you add a third-party Python package to a Locust Docker container?

4. What is the purpose of the locustio/locust:latest-otel image?

🛠️ Hands-On Exercises

1. Write a docker-compose.yml with master + 2 workers; run the test and verify all 3 containers appear in docker compose ps.
2. Build a custom Dockerfile adding requests and pytest; run a test inside the custom image.
3. Compare RPS between native Python run and Docker run on the same hardware; note any overhead.

Proceed to Chapter 12: Kubernetes Operator.