Dockerized JMeter Starter Kit — Start Load Testing Faster

4 min readJan 22, 2021

Photo by Vidar Nordli-Mathisen on Unsplash

As a performance engineer, I regularly need to start new JMeter projects for new API or frontends. Not many projects share the same load injection infrastructure and deploying JMeter is not really easy nor fun. When you need more load than one JMeter injector can provide, the distributed testing come with it bunch of complexity.

I work in IT, so I’m lazy. Do it manually once, twice, then automate. What a better tool than Docker for lazy workers ? Describe, package, run, everywhere.

Description of the Starter Kit

The repository is available at https://github.com/Rbillon59/jmeter-docker-compose-starterkit

The README.md in the repository cover in detail the usage process

Multi-injectors ready
JMeter plugins installed automatically regarding the JMX needs
Real-time data with InfluxDB and Grafana with preconfigured dashboard
CSV datasets split automatically between all injectors
Fully automated with one line command

What is Docker-compose ?

Docker-compose is a tool used to manage multi-container Docker applications, you describe your services in a YAML file then run everything with a single command.

In our case, you can deploy easily your JMeter controller and workers with embedded real-time load test monitoring and data persistence.

How to use the starter kit ?

Step 1 : Writing your scenario

You just need to write your JMX file or put your existing one into the scenario folder. On your scenario you can take use of the variables used in the .env to have more flexibility at runtime :

As well, use the InfluxDB backend listener with http://influxdb:8086/write?db=jmeter to use the embedded real-time test monitoring :

Step 2 : Using CSV datasets

If needed put your csv datasets inside the data folder. For login or passwords for example. It will be split at run time for every injectors as equal parts. In JMeter, just put the filename inside the “Path”

Step 3 : Preparing the test configuration

Update the .env file with the destination host, the protocol, the port number of the target.

XMX=1g
XMS=1g
host=jsonplaceholder.typicode.com
port=443
protocol=https
threads=1
duration=60
rampup=60
nbInjector=1
JMX=my-scenario.jmx

XMX and XMS are the Java Heap setting, depending on your test complexity and number of virtual users per injectors, you can adapt it accordingly.

The number of threads defined here is per injectors

Host is the target domain name / IP
Port is the port number of the target application
Protocol is http or https
Rampup is the time taken to open the defined thread number (in seconds)
The duration is the total time of the test (not cumulated with rampup)

Step 4 : Unleash JMeter

At the root of the repository, just use this command and it will rain fire on your targeted app

source .env && JMX=my-scenario.jmx sudo docker-compose -p jmeter up --scale jmeter-slave=${nbInjector} -d

Sourcing the .env will give you the ability to use ${nbInjector} in the docker-compose command line.
Passing the JMX as param and not in the .env can give you flexibility to run the test of your choice by command line without editing the env file (optional)
The -p jmeter is mandatory to prefix the docker-compose created networks and containers to work together (Tips : For every docker-compose command, use -p jmeter)
The scale command is used to create the necessary amount of injectors

Step 5 : Monitor the test

Open your browser to the Grafana URL of the server hosting the Docker containers on http://host:30000 and open the “Apache JMeter Dashboard”

| login admin:admin

Grafana with InfluxDB datasource for real-time loas test monitoring

Step 6 : Exploit the report

At the end of the test a JMeter report is generated inside the report folder and the logs are stored in the log folder. To open a report just use your file explorer and open the index.html inside a test result