Skip to main content

Installation Instructions

This guide walks through installing ioBuster Pro step by step. If you prefer a single-command approach, see the Installation Script page.

Overview​

ioBuster Pro has two components to install:

  1. Coordinator — a backend service (Docker container) that manages test hosts and coordinates test execution.
  2. iobc CLI — a command-line tool that communicates with the Coordinator to manage hosts, ports, and jobs.

You can run the Coordinator on the same machine as the CLI, on a dedicated server, or use an existing Coordinator that someone else has deployed.

Step 1 — Install Docker​

The Coordinator runs as a Docker container. Install Docker on the machine that will host the Coordinator.

Linux​

Follow the Docker Engine installation guide for your distribution (Ubuntu, Debian, CentOS, etc.).

After installation, verify Docker is running:

docker info

macOS​

Download and install Docker Desktop for Mac.

note

Docker is only required on the machine running the Coordinator. If you are connecting to a Coordinator on a remote machine, you do not need Docker locally.

Step 2 — Deploy the Coordinator​

Option A — Local Docker deployment​

Download the Coordinator image and start it:

# Download the image
curl -fSL -o /tmp/io-buster-cli.tar.gz \
  https://storage.googleapis.com/io-buster-pro/releases/io-buster-cli/io-buster-cli-latest.tar.gz

# Load it into Docker
docker load -i /tmp/io-buster-cli.tar.gz

# Create a persistent data volume
docker volume create iobc-data

# Create the network
docker network create iobc-net

# Start the Coordinator
docker run -d \
  --name iobc-coordinator \
  --network iobc-net \
  --restart unless-stopped \
  -p 9100:9100 \
  -v iobc-data:/data \
  -v /var/run/docker.sock:/var/run/docker.sock \
  io-buster-cli:latest

Wait a few seconds for the service to start, then verify:

curl -s http://localhost:9100/health

Option B — Remote deployment​

If the Coordinator will run on a different machine, SSH into that machine and follow the same steps from Option A. Then note the machine's IP address — you will need it when configuring the CLI.

Option C — Use an existing Coordinator​

If someone has already deployed a Coordinator, you only need its address (e.g., 192.168.1.100:9100). Skip to Step 3.

Step 3 — Install the iobc CLI​

Download the CLI binary for your platform:

# Determine your platform
OS=$(uname -s | tr '[:upper:]' '[:lower:]')   # linux or darwin
ARCH=$(uname -m)                                # x86_64 or aarch64/arm64

# Normalize architecture name
case "$ARCH" in
  x86_64)        ARCH="x64" ;;
  aarch64|arm64) ARCH="arm64" ;;
esac

# Download
curl -fSL -o /tmp/iobc \
  "https://storage.googleapis.com/io-buster-pro/releases/iobc/iobc-latest-${OS}-${ARCH}"

# Make executable
chmod +x /tmp/iobc

# Install (system-wide)
sudo mv /tmp/iobc /usr/local/bin/iobc

# Or install for current user only
# mkdir -p ~/.local/bin
# mv /tmp/iobc ~/.local/bin/iobc

Verify the CLI is accessible:

iobc --help
tip

If you installed to ~/.local/bin and the command is not found, add it to your PATH:

export PATH="$HOME/.local/bin:$PATH"

Add this line to your ~/.bashrc or ~/.zshrc to make it permanent.

Step 4 — Configure the CLI​

Create a configuration file that tells the CLI where to find the Coordinator:

mkdir -p ~/.iobc
cat > ~/.iobc/config.yaml <<EOF
server: localhost:9100
EOF

Replace localhost:9100 with the Coordinator's address if it is running on a different machine (e.g., 192.168.1.100:9100).

Step 5 — Verify​

Test the connection between the CLI and the Coordinator:

iobc host list

This should return an empty list (or your existing hosts if upgrading). If you see an error, check that:

  • The Coordinator container is running (docker ps)
  • The Coordinator port (default 9100) is reachable from this machine
  • The ~/.iobc/config.yaml file has the correct address

Installing a Specific Version​

By default, the instructions above install the latest release. To install a specific version, replace latest in the download URLs with the version number:

# Coordinator image for version 0.2.0
curl -fSL -o /tmp/io-buster-cli.tar.gz \
  https://storage.googleapis.com/io-buster-pro/releases/io-buster-cli/io-buster-cli-0.2.0.tar.gz

# CLI binary for version 0.2.0
curl -fSL -o /tmp/iobc \
  https://storage.googleapis.com/io-buster-pro/releases/iobc/iobc-0.2.0-linux-x64

You can check the latest available versions at:

https://storage.googleapis.com/io-buster-pro/releases/latest.json

Upgrading​

To upgrade an existing installation:

  1. Download and load the new Coordinator image (same steps as Step 2).

  2. Stop and remove the old container:

    docker stop iobc-coordinator
    docker rm iobc-coordinator

  3. Start a new container with the updated image (same docker run command as Step 2). The iobc-data volume persists your data across upgrades.

  4. Download and replace the CLI binary (same steps as Step 3).

tip

The Installation Script handles upgrades automatically. Running the installer again will detect the existing installation and perform an in-place upgrade.

Air-Gapped Installation​

For environments without internet access:

  1. On a machine with internet, download:

    • The Coordinator image: io-buster-cli-<version>.tar.gz
    • The CLI binary: iobc-<version>-linux-x64

  2. Transfer both files to the target machine (USB drive, internal network, etc.).

  3. Load the Coordinator image:

    docker load -i io-buster-cli-0.2.0.tar.gz

  4. Follow Steps 2–5 above, skipping the curl download steps.

Alternatively, use the self-contained installer which bundles the CLI binary into a single script file.