Press "Enter" to skip to content

Variant CVM Server Installation
and Configuration Guide

Release 1.0.1, December 2023

1. Installing Variant CVM 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:

1. 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:

DirectoryDescription
bin/Contains the server startup shell script variant along with dependent scripts which you should never have to use.
conf/Configuration directory, containing the server config file variant.conf, logging config file logback.xml, and other dependent configuration artifacts.
lib/System libraries.
spi/User provided Java classes, developed on top of the Server-side SPI, and their dependencies. The distribution contains the the standard extension library variant-spi-stdlib-<release>.jar. All JAR files in the spi/ directory are added to Variant server’s runtime classpath.
log/Default destination for the server log files.
schemata/Default location of the variation schema files. The distribution contains the bookworms.yaml file used in conjunction with the [todo] Bookworms demo application.
  1. 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/bookworms.yaml]
2024-01-05 13:58:50,608 INFO - c.v.s.schema.ServerFlusherService - [431] Initialized flusher [TraceEventFlusherCsv] for schema [bookworms]
2024-01-05 13:58:50,615 INFO - c.v.s.schema.Schemata - [422] Deployed schema [bookworms] from file [bookworms.yaml]
2024-01-05 13:58:50,645 INFO - c.v.s.impl.VariantServerImpl - [410] Variant CVM Server release 1.0.1 started on port [5377] in 1.477s

The schemata/bookworms.yaml file contains the variation schema used in conjunction with the [todo] Bookworms demo application. You may remove it at any time if you are not planning to use the Bookworms application. 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, you must change the value of the configuration parameter variant.http.port as described in [todo].

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

$ curl localhost:5377
{
  "name" : "Variant CVM Server",
  "version" : "1.0.1",
  "uptimeSeconds" : 10,
  "build" : {
    "timestamp" : "2023-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 window

$ bin/variant.sh stop

Either will trigger a graceful shutdown whereby the Variant server.

2. Variant CVM 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 start Variant server:

$ bin/variant start

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

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.sh 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.

Additionally, each 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

$ bin/variant stop

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

  1. Each currently mounted variation 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 trace events are flushed to disk
  3. The embedded RocksDB is properly closed.

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

$ bin/variant halt

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

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

It is recommended that you avoid using non-maskable interrupts such as KILL (i.e. running kill -9.

To find out the status of the Variant server:

$ bin/variant status

3. Configuring Variant CVM Server

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

PropertyDefault Value / Description
variant.event.flusher.class.namecom.variant.server.api.EventFlusherAppLogger Default event flusher implementation, implicitly provided to those variation schemata that do not define their own.
variant.event.flusher.nameThe name by which this flusher will be referred to in logs. The default is the simple name of the flusher class.
variant.event.flusher.class.initnull Arbitrary JSON object, whose parsed representation will be passed to the constructor of the event flusher implementation. Not required by the default com.variant.server.api.EventFlusherAppLogger above.
variant.event.writer.buffer.sizeMemory size in bytes allocated for each schema’s event buffers.
variant.event.writer.flush.size500 Maximum number of trace events passed to a single call to flush().
variant.event.writer.max.delay30 Maximum delay in seconds between the time when a trace event is triggered and the time it is passed to an event flusher. This ensures that events triggered by a low-traffic schema and not stuck in the asynchronous event writer for exessively long periods of time.
variant.event.writer.flush.parallelism2 The size of the flush thread pool. Event writer schedules calls to the flush() methods to be executed concurrently in a dedicated thread pool of this size. Buffers are flushed in the order they fill up. The flush pool is shared between all schemata.
variant.http.port5377 Variant server HTTP port.
variant.https.port5378 Variant server HTTPS port.
variant.schemata.dir"schemata" The directory where Variant server looks for variation schemata, as an OS file name. If starts with a slash, interpreted as an absolute path. Otherwise, as relative path to the server startup directory.
variant.session.timeout900 Session timeout. User sessions are expired after this many seconds of inactivity.
variant.session.vacuum.interval10 The session vacuum thread is woken up no less frequently than this many seconds. The session vacuum thread expires inactive sessions and reclaims the memory taken by them.