Installation Guide¶

OctoPerf On Premise Infra can be installed in just a few minutes by following the Quick Setup. For production-grade installations, we recommend to follow the High Availability Setup.

Quick Setup¶

This installation guide setups OctoPerf On Premise Infra on a single machine. The installation can be completed within 5 minutes by unexperienced users.

The setup using Docker Compose is provided as an example. OctoPerf EE can be indifferently setup in various environments like Kubernetes or Rancher.

Prerequisites¶

Requirements¶

OctoPerf On Premise Infra has the following requirements:

dual or quad cores CPU,
At least 8GB RAM,
Operating System: Ubuntu 20.04LTS or newer is recommended. (although Centos and Debian are supported too) See Docker Install for more supported operating systems.

The advanced setup assumes you are familiar with Linux and Docker.

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.

Increase VM Max Map Count¶

Elasticsearch Database 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.

Install Docker¶

Docker Setup¶

To install Docker, run the following command on a Terminal:

curl -sSL https://get.docker.com/ | sh

Once the installation is finished, add your current user to the Docker group:

sudo usermod -aG docker $your_user

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

Check Docker is installed correctly by running docker version:

Client: Docker Engine - Community
 Version:           23.0.1
 API version:       1.42
 Go version:        go1.19.5
 Git commit:        a5ee5b1
 Built:             Thu Feb  9 19:47:01 2023
 OS/Arch:           linux/amd64
 Context:           default

Server: Docker Engine - Community
 Engine:
  Version:          23.0.1
  API version:      1.42 (minimum version 1.12)
  Go version:       go1.19.5
  Git commit:       bc3805a
  Built:            Thu Feb  9 19:47:01 2023
  OS/Arch:          linux/amd64
  Experimental:     false
 containerd:
  Version:          1.6.16
  GitCommit:        31aa4358a36870b21a992d3ad2bef29e1d693bec
 runc:
  Version:          1.1.4
  GitCommit:        v1.1.4-0-g5fd4c4d
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad0

You should see something like above in your terminal.

Make sure you have the docker compose plugin installed:

ubuntu@pop-os:~$ docker compose version 
Docker Compose version v2.16.0

if the plugin is not installed, please follow the instructions here.

Download ZIP¶

OctoPerf EE exists in two versions:

The HTTPS version is configured to work with an SSL certificate. You must provide additional files to make it work:

nginx/server.crt: server certificate,
nginx/server.crt.key: server certificate key.

Those files must be copied in nginx/ folder before starting the OctoPerf stack.

A few notes:

The SSL certificate must be generated by a valid certification authority (self-signed certificates won't work),
The SSL certificate hostname must match with the hostname configured in config/application.yml.

Configuration¶

It's now time to configure OctoPerf EE using docker-compose:

Unzip the previously downloaded file in any location, it should decompress the following:
- config: configuration files for OctoPerf
  - config/application.yml: server configuration file,
  - config/config.json: front end configuration file,
- license: folder for the license file,
- nginx: contains the files related to the nginx configuration, (Dockerfile and config.json),
- docker-compose.yml: defines the services to start via docker-compose,
- Makefile: provides convenient commands like make to run OctoPerf EE.
- Edit config/application.yml: define the server.hostname property with the IP / Hostname of the machine running OctoPerf:

server:
  hostname: YOUR_HOSTNAME

By Default, the web-server runs with http protocol on port 80. Replace YOUR_HOSTNAME by the hostname of your machine. It must be a hostname reachable publicly or at least from your local area network.

Start the Application¶

To start OctoPerf EE:

Run make to start OctoPerf EE,
Browse to http(s)://<YOUR_HOSTNAME> (or localhost if running on your own machine) to open OctoPerf EE. (starts on port 80 by default; on port 443 with the SSL version)

OctoPerf EE Login OctoPerf Login Page (server running on my local machine)

Create an Account¶

OctoPerf EE comes completely empty. You need to create an account and register a load generator (computer used to generate the load) to be able to run load tests:

Signup and create a new account,
Create an On-Premise Provider: providers are groups of load generators,
And register an On-Premise Agent within the previously created On-Premise Provider.

Congratulations! The setup is now complete.

High Availability Setup¶

Warning

High Availability Setup require intensive knowledge of kubernetes and additional components like Hazelcast. As such we do not recommend it unless this OctoPerf server is going to be used by a huge team of testers (more than 20 people concurrently).

OctoPerf EE can be scaled horizontally by running on a cluster of machines. It allows you to:

Operate continuously: resiliency to one or multiple machine failures,
Replicate Data over multiple machines: your data is safe by being replicated on multiple machines.

High Availability Setup

The High Availability Setup procedure is intended to be used in Production Environments.

This setup involves:

cluster of at least 3 machines, (an odd number is recommended. Example: 3, 5, 7 etc.)
elasticsearch containers running on the whole cluster, (to benefit from data replication across multiple servers)
enterprise-edition (backend server) container running with High Availability enabled,
Load-balancer to distributed incoming traffic to relevant containers,
DNS hostname associated with one or multiple machines serving as load-balancers,
Automated Elasticsearch Backups (via snapshots; on a shared NFS Disk for example).