Skip to content

Installation Guide

The installation guide supposes the whole setup is made on a single machine.

Even if the installation involes multiple steps, it shouldn't take more than 15 min to install and run OctoPerf EE. Each step is simple and straight-forward.


The advanced setup assumes you are familiar with:

  • Running commands inside a Terminal on a Linux Operating System,
  • Installing software on a Linux computer,
  • Docker Basics like starting / stopping / destroying docker containers, pulling images.

Configure System

Elasticsearch requires the systemctl vm.max_map_count to be set at least to 262144:

sysctl -w vm.max_map_count=262144

To set this value permanently, update the vm.max_map_count setting in /etc/sysctl.conf. To verify after rebooting, run sysctl vm.max_map_count.

See Elasticsearch VM Max Map Count for more information.

Disable Firewalls

It's recommended to disable any firewall like firewalld (Centos) or ufw (Ubuntu) because they interfer with IPTables rules. As Docker inserts IPTables rules, it's wise to disable firewall to avoid networking issues.

Install Docker

1. How to install Docker

  • To install Docker, run the following command on a Terminal: curl -sSL | sh

Docker Setup Installing Docker on the system via Terminal. Docker is already installed here.

  • Once the installation is finished, add your current user to the Docker group: sudo usermod -aG docker $your_user

Docker Usermod Adding you current user to the docker group.

Where $your_user needs to be replaced by your username. This step is optional but avoids you to run docker commands as sudoer.

2. Configure docker to use a proxy

Before you try to install rancher, note that Docker can run from behind a proxy if required. The procedure is detailed in docker documentation.

Install Rancher

Rancher Logo

The next step is to launch Rancher. Rancher will be used to both:

  • Manage the OctoPerf EE infrastructure,
  • And manage the hosts used to run load tests.

Rancher is the orchestration system driven by OctoPerf EE to run distributed JMeter load tests across multiple machines. Rancher can be installed in various ways. The guide describes here how to install Rancher Server with its standalone built-in MySQL Server.

Configure Rancher to use a proxy

Rancher can also run from behind a proxy but this requires some configuration. The procedure is detailed in Rancher documentation.

Start Rancher Server

  • To install Rancher server, run the following command in a Terminal: sudo docker run -d -v <host_vol>:/var/lib/mysql --restart=unless-stopped -p 8080:8080 rancher/server

Please replace <host vol> by the folder where you would like to store Rancher data. Example: /home/ubuntu/rancher.

  • After a while, you should be able to browse http://rancher-hostname:8080. At this point, Rancher is running but needs to be configured.

Rancher Empty Env Rancher is up and running.

Set Rancher Hostname

  • Open http://rancher-hostname:8080, where rancher-hostname is the hostname where Rancher is being installed.
  • In the top menu, Click on Admin, then Settings,
  • In Host Registration URL, provide the right hostname.

Rancher Set Hostname Configuring Rancher with hostname here. hostname depends on your network.

This step is crucial to properly connect Docker hosts later. The hostname or IP must be accessible from the hosts which will connect to Rancher.

Remove System Services

The Default environment is used to register load generators. OctoPerf load generators doesn't require any system service.

  • In the top menu, Click on Stacks, then All.
  • Delete the existing system stacks (healthcheck, ipsec, network-services and scheduler)

Rancher System Services All the system services must be removed as these are not needed by load generators.

The Default environment is used for load generators. None of the system stacks above is required to run load tests.

Rancher Empty Services All system services have been removed from Default environment.

Create Infra Environment

The Infra environment is used to run OctoPerf EE on dedicated hosts. OctoPerf EE runs on separate hosts for stability reason.

  • Click on Default, then Manage Environments,
  • Then click on Add Environment and name it Infra, or any other relevant name.

Rancher Add Environment Creating Infra environment to run OctoPerf EE.

This environment is used to run OctoPerf Entreprise components including the backend, the frontend and the database. The following procedure explains how to setup a Rancher host.

Register a Rancher host

This host is used to run the OctoPerf EE components. It must be registered in Infra environment. We are going to setup a host on the same machine as the Rancher server. This is why the IP address must be specified.

  • Select Infra environment,
  • Click on Infrastructure, then click on Add Host,
  • Select Custom type, and specify the IP address of the rancher server (as the host will run on the same machine),
  • Copy and paste the command in a Terminal and execute it.

Rancher Add Host Adding custom host with IP here. IP depends on your network.

After a few minutes, the host should appear in the Web UI.

Rancher Host Added Custom host with IP up and running on the same host as the rancher server

If you struggle to get a host up and running, please see the Rancher Troubleshooting guide. Feel free to contact us if you need some assistance.

Add OctoPerf Catalog

In this step, we are going to configure Rancher to lookup OctoPerf Catalog which contains the OctoPerf EE installer.

  • Open Rancher Web UI,
  • Click on Admin, then Settings,
  • Click on + Add Catalog,
  • Enter OctoPerf as name, and as URL, ${RELEASE} as branch name,
  • Click on Save.

Rancher OctoPerf Catalog OctoPerf Catalog configured in Admin > Settings.

Start OctoPerf EE

In this step, we are going to launch OctoPerf EE from OctoPerf Rancher Catalog.

  • Click on Stacks,
  • Click on Add from Catalog,
  • In Category drop down in the top right corner, select Load Testing Tools,

Rancher OctoPerf Catalog OctoPerf Load Testing Tool from our Rancher Catalog.

  • Click on View Details,
  • Select latest version and provide relevant information,

Rancher Install OctoPerf OctoPerf Installation Settings.

General Settings:

  • Rancher Access Key and Rancher Secret Key: In case your Rancher server is secured, provide an Account API Key, leave empty if none,
  • Rancher Environment: Default by default. Specifies the Rancher environment to use for load generators,
  • Backend Hostname: Either Public or Private Hostname / IP accessible from load-generators. Examples:,,

See Data Storage Settings if you wish to customize data location settings.

OctoPerf EE Settings

  • Click on Create.

Rancher OctoPerf EE Stack All services are up and running.

Congratulations! OctoPerf EE should be up and running now. You can now browse to http://localhost:8090/ (or replace localhost with the hostname of the machine where OctoPerf EE is installed).

OctoPerf Signup Signup to create your account and get started.

Add a load generator

To run load tests, you need to create an on-premise provider and register a host. The host used to run OctoPerf EE cannot be used to run the load tests.