1. Installing Variant Experiment Server

Variant server is entirely self-contained and does not have any external dependencies. It requires Java runtime 17 or later. To install Variant server:

□ Download Variant server

□ Unpack the distribution in a directory of your choice:

$ unzip /path/to/variant-server-<release>.zip

This will create a server installation with the following directory structure:

□ Change directory to Variant server top level directory:

$ cd variant-server-<release>

□ Start Variant server in the foreground:

$ bin/variant start

If all goes well, the server console output should look something like this:

$ bin/variant.sh start
2024-01-05 13:58:49,745 INFO - c.v.s.boot.ConfigLoader$ - Found  config resource [/variant.conf] as [/Users/variant/variant-server-1.0.1/conf/variant.conf]
2024-01-05 13:58:50,549 INFO - c.v.s.schema.SchemaDeployerFileSystem - Mounted schemata directory [/Users/variant/variant-server-1.0.1/schemata]
2024-01-05 13:58:50,553 INFO - c.v.s.schema.SchemaDeployerFileSystem - [421] Deploying schema from file [/Users/variant/variant-server-1.0.1/schemata/example.yaml]
2024-01-05 13:58:50,608 INFO - c.v.s.schema.ServerFlusherService - [431] Initialized flusher [TraceEventFlusherCsv] for schema [example]
2024-01-05 13:58:50,615 INFO - c.v.s.schema.Schemata - [422] Deployed schema [example] from file [example.yaml]
2024-01-05 13:58:50,645 INFO - c.v.s.impl.VariantServerImpl - [410] Variant Experiment Server release 1.3.1 started on port [5377] in 1.477s

You can deploy any other schema file by copying it into the schemata/ directory.

By default, the server binds to port 5377. To start the server on a different port, change the value of the configuration parameter variant.http.port  in the config file config/variant.conf.

You may always ping a running server by typing its URL into a Web browser, or from the command line with the curl command:

$ curl localhost:5377
{
  "name" : "Variant Experiment Server",
  "version" : "1.4.0",
  "uptimeSeconds" : 10,
  "build" : {
    "timestamp" : "2024-09-29T16:28:51.749146Z",
    "scalaVersion" : "2.13.4",
    "javaVersion" : "17.0.7",
    "javaVmName" : "OpenJDK 64-Bit Server VM",
    "javaVmVersion" : "17.0.7+7-LTS"
  },
  "schemata" : [ {
    "name" : "bookworms",
    "description" : "Variant experiment schema for the Bookworms demo application"
  } ]
}

A running server can be stopped by typing Control-C in the shell where it was started, or by typing in a different shell

$ bin/variant.sh stop

Either will trigger a graceful shutdown whereby the Variant server stops accepting new connections but continues to operate until all existing sessions expire naturally. If you require an emergency server shutdown use instead

$ bin/variant.sh halt

Beware that this may compromise user experiences of the currently in-progress sessions.

2. Variant Experiment Server CLI

Variant server is written in Scala and runs on a JVM. It is controlled by the bin/variant shell script, which supports the following operations:

□ To get help on the supported command line options type:

$ variant help

□ To start Variant server in the foreground:

$ variant start

Any additional parameters will be passed to the underlying java command without interpretation. In particular, you may pass any Java system property by appending the -D... to the start command like so

$ variant start -Dvariant.http.port=9876

At startup, Variant server looks for the default configuration file conf/variant.conf. If it is found, its contents override the default settings, listed in the next section. If you need to modify any configuration properties, you may either update them directly in the conf/variant.conf file, or provide an alternate configuration file. Variant supports two ways for doing so: as a file system file or as a JVM classpath resource. Either way, the contents of the alternate config file override those in the default config file conf/variant.conf, if any.

To supply an alternate configuration file as a file system file, use the variant.config.file JVM system property:

$ variant start -Dvariant.config.file=/path/to/alt/config/as/file

To supply an alternate configuration fileas a classpath resource , use the variant.config.resource JVM system property:

$ variant start -Dvariant.config.resource=resource-name

The simplest way to add a resource to the server classpath is to place it in the server’s conf directory, which is automatically added to the server’s runtime classpath at the root level. In other words, the file conf/extra.conf should be referenced as

$ variant.sh start -Dvariant.config.resource=/extra.conf

It is an error to set both variant.config.file and variant.config.resource system properties.

Similarly, any individual config parameter may be overridden from the command line via the JVM system variable of the same name, e.g.:

$ variant.sh start -Dvariant.schemata.dir=/Users/variant/schemata

□ To stop Variant server:

Either type Control-C in the shell where there the server was started in the foreground, or type in a different shell

$ variant stop

Either action will send the SIGINT signal to the server, which initiates a graceful shutdown:

1. Each currently mounted experiment schema will be put in a draining state, whereby no new connections will be accepted, but the existing sessions will be waited for for up to a configurable period of time.
2. Each schema’s pending trace events are flushed to disk.
3. The embedded RocksDB is properly closed.

If you need to halt Variant server without waiting for the existing sessions to drain, use

$ bin/variant halt

This will send the SIGTERM signal, which initiates an emergency shutdown:

1. Each currently mounted experiment schema is dismounted without draining existing sessions. This may cause in-flight sessions to see unintended user experiences.
2. Each schema’s pending trace events are flushed to disk.
3. The embedded RocksDB is properly closed.

You should avoid using non-maskable interrupts such as SIGKILL by running kill -9 directly on the Variant server process, because this may compromise the integrity of the imbedded RocksDB database.

□ To find out the status of the Variant server:

$ variant status

3. Configuring Variant Experiment Server

Variant server is configured using the Lightbend Config library . The following table lists all config properties recognized by Variant server.