Getting Started

This page describes how to get started with using an existing SystemsLab cluster. If you're looking to set up your own SystemsLab cluster you will need to follow the relevant install docs.

Installation

In order to submit experiments to a SystemsLab cluster you need the SystemsLab CLI. There are a few different ways to install it so pick the one that works best for your setup.

The systemslab-cli package is available in IOP Systems' APT repositories. You need to set those up first:

curl -fsSL "https://storage.googleapis.com/systemslab-public/deb/systemslab-repo-$(lsb_release -sc)_latest_all.deb" -o systemslab-repo.deb
sudo apt install ./systemslab-repo.deb
sudo apt update

Once the repository is enabled all you need to do is install the systemslab-cli package:

sudo apt install systemslab-cli

The systemslab-cli package is available in IOP Systems' RPM repositories. You need to set those up first:

sudo yum install "https://storage.googleapis.com/systemslab-public/rpm/systemslab-repo-$(rpm --eval '%{dist}' | cut -d. -f2)-latest.noarch.rpm"

Once the repository is enabled all you need to do to is install the systemslab-cli package:

sudo yum install systemslab-cli

You can install the systemslab CLI via the iopsystems/iop tap:

brew install iopsystems/iop/systemslab

Prebuilt packages are available for x86_64 and ARM64 on MacOS, and x86_64 on linux via linuxbrew. Unsupported architecture/OS combinations will result in a permission error, in that case consider using the install instructions for one of the distro package managers.

If you do run into an unsupported combination then please raise an issue on our tap github repo and we will look into adding it to the set that gets built with every release.

Configuration

Before using the CLI, you will likely want to set up a config file that tells it how to find the SystemsLab server. There are a number of different locations in which you can place the config file (see the reference for the full list). Here we will put it at .config/systemslab.toml in the current directory.

systemslab_url = "https://systemslab.example.com"

Setting this config means that it is not necessary to pass --systemslab-url http://systemslab.example.com to every single command you want to run.

Your First SystemsLab Experiment

Now that we have everything set up we can create our very first SystemsLab experiment. This won't be a benchmark, it will effectively just be an experiment that prints out "Hello, World!" but it is enough to see most of the parts involved in writing an experiment.

The first thing we need is an experiment specification. These can be written in json, YAML, or jsonnet. We'll use jsonnet here since it ends up being the most readable. So, without further ado:

local systemslab = import 'systemslab.libsonnet';

{
  name: 'My First Experiment',
  jobs: {
    main: {
      steps: [
        systemslab.bash('echo "Hello, World!"'),
      ]
    }
  }
}

You can see all the available fields in the experiment specification over in the reference.

We can save this file as experiment.jsonnet and then submit it to the server by running:

systemslab submit experiment.jsonnet --wait

When I run this I get the following:

Experiment page is available at http://localhost:3000/experiment/01903d77-b118-715f-a731-b338f141104c
main | Starting job on SystemsLab host:
main |   host name:     systemslab-agent-1
main |   host id:       019037a2-e5a7-7fe5-0e71-4728acb529c0
main |   agent version: 0.0.93
main | 
main | SystemsLab job info:
main |   experiment id: 01903d77-b118-715f-a731-b338f141104c
main |   job id:        01903d77-b118-723d-80ed-e8bf0f0d4ec4
main |   attempt:       0
main | 
main | systemslab/shell:
main |   run: echo "Hello, World!"
main |   shell: bash
main | 
main | + echo 'Hello, World!'
main | Hello, World!

There is a bunch of output here that has info about the job and the host that ran the experiment. At the end, however, we see:

main | + echo 'Hello, World!'
main | Hello, World!

Which means that our hello world experiment ran on a machine within the SystemsLab cluster!