Installing the Server

This page assumes that you have already followed the steps in the setup page.

INFO

Currently we only support installing the SystemsLab server on x86_64.

Installing the SystemsLab Server

You can install the server itself via apt

sudo apt install systemslab-server

Now you can install the server itself via yum

sudo yum install systemslab-server

This will automatically create and use a postgresql database on the current machine.

Setting up the Database

Debian-based distros have a custom tool to manage postgres clusters and the default database setup for SystemsLab makes use of that.

You can initialize the systemslab database by using systemslab-dbctl:

sudo systemslab-dbctl init --yes

This will initialize the default main cluster that is reated when the postgresql-15 package is installed.

In order to set up the database you will need to run the commands below

# Create the database
sudo postgresql-15-setup initdb

# Set up the database for use by SystemsLab
systemslab-dbctl init --pgdata /var/lib/pgsql/15/data --yes

Starting the Server

At this point you can now start the server. The relevant service is managed via systemd. Depending on your distro, this may already have been done automatically.

sudo systemctl enable systemslab-server
sudo systemctl start systemslab-server

You can verify that the service is up by running

systemctl status systemslab-server

or by verifying that the request below completes successfully

curl http://localhost/api/v1/version

Configuration

The server config file is stored at /etc/systemslab/server.toml. At a minimum you will want to configure

log.cluster_id = "<your company name>/<cluster name>"

This doesn't change any server behaviour but it allows us (IOP) to determine where errors are being emitted so we can reach out.

To see all available options see the server config reference.

INFO

The config file is TOML but some of the keys for config options are set on the root object. These must come before you start adding any nested sections to the config.

As an example, the config below will properly set the server to listen on port 3000:

port = 3000

[storage]
bucket = "/var/lib/blah"

but this config will cause an error because storage.port is not a valid config key:

[storage]
bucket = "/var/lib/blah"

port = 3000

Configuring Artifact Storage

Experiments run on SystemsLab produce artifact files. This can end up being rather large so storing them on the local filesystem is not recommended for a production setup.

If you want to store artifacts on a service that is not listed here, please let us know and we will add support to SystemsLab.

This is the default configuration for the server. Artifacts will be stored at /var/lib/systemslab/data.

If you wish to change where artifacts are stored you can add

[storage]
bucket = "/path/to/storage/dir"

to the server configuration file.

To store artifacts in S3 add the following to your server config file.

[storage]
bucket = "s3://<your s3 bucket>"

By default, the server will use the AWS default credential chain to authenticate with S3. If this doesn't work for you then you can explicitly add credentials to the config file instead:

[storage]
# You can get these out of an existing `~/.aws/credentials` file.
s3.access_key_id = "<your access key>"
s3.secret_access_key = "<your secret key>"

You can also configure systemslab to use S3-compatible services that are not S3 itself. This is generally done by setting s3.endpoint to point to the endpoint for the relevant service and explicitly setting s3.region. Note that some S3 compatible services require options in addition to the two above, see the OpenDAL documentation for more details.

To store artifacts in GCS add the following to your server config file.

[storage]
bucket = "gs://<your gcs bucket>"

By default, the server will attempt to use the available application default credentials to authenticate with GCS. If this doesn't work for you then you can explicitly specify a JSON credentials file

[storage]
gcs.credentials_json = "/path/to/credentials.json"

You can also override the service account to be used

[storage]
gcs.service_account = "..."