Containers - Handbook - Project configuration

This is a technical reference for Sphere Engine Containers project configuration. You will find here a detailed description covering:

  • file structure,
  • parameters (meaning, type, validation rules, description),
  • examples.

The project configuration is specified by a single JSON file (config.json) of a well-defined structure.

General overview

Let's start by presenting the complete config.json configuration file based on an example. This is to demonstrate a general document structure.

{
    // configuration version
    "version": 2.1,

    // collection of run configurations
    "scenarios": {
        // first run configuration
        "scenario_1": {
            // whether to run this scenario by default
            "default": true,
            // whether to allow Internet connection
            "network": false,
            // list of services (e.g. database)
            "services": ["mysql"],
            // a sequence of consecutive Workspace execution stages
            "stages": {
                // configuration of an "init" stage
                "init": {
                    "command": null
                },
                // configuration of a "build" stage
                "build": {
                    "command": null
                },
                // configuration of a "run" stage
                "run": {
                    // a path to a script or shell command to run
                    "command": ".sphere-engine/run.sh",
                    // where should the data be redirected
                    "redirect_streams_to": "console",
                    // whether to skip this stage
                    "skip": false,
                    // how long should the stage be allowed to execute
                    "timeout": 10
                },
                // configuration of a "test" stage
                "test": {
                    "command": null
                },
                // configuration of a "post" stage
                "post": {
                    "command": null
                }
            },
            "output": {
                // type of the Workspace's output data
                "type": "file",
                // output data location
                "path": "my_output.csv",
                //  whether to present the output when the Workspace loads
                "show_at_startup": false
            },
            // configuration for tests required if you use WeightedScoreTestsGrader
            // if you don't use WeightedScoreTestsGrader the key is not used
            // please see WeightedScoreTestsGrader docs for more information
            // tests weights are specififed as selector. Each selector can match specific unit tests
            "tests_weights": [
                {
                    // optional name of the test case to match (or wildcard: "*")
                    "name": "test_add_operation",
                    // optional name of the test case classname to match (or wildcard: "*")
                    "classname": "TestClass",
                    // optional status of the test case to match (or wildcard: "*")
                    "status": "ok",
                    // score assigned by this selector
                    "weight": 20
                },
                {
                    "name": "other_test",
                    "weight": 0
                }
            ]
        },
        // second run configuration
        "scenario_2": {
            "default": false,
            ...
        }
    },

    // settings related to files
    "files": {
        // list of files that should be hidden in the file explorer
        "hidden": [".env", ".gitignore"],
        // list of files that should automatically open after launching the Workspace
        "open_at_startup": ["README.md"],
        // list of read-only files
        "read_only": ["config.yaml"]
    },

    // any custom data of any type
    "custom": {
        "internal_tag": "3317c1863f8dd227c2e438e6cabf466b",
        "categories": ["simple programming", "data processing", "algorithms"]
    }
}

Detailed specification

In the following section we present a detailed information regarding the config.json configuration file structure.

config.json (root)

A configuration file of the Sphere Engine Containers project.

type: object
required: yes
parameters:

Name Type Description Required Default
version number Version of the config file Yes -
scenarios object A collection of scenarios that will be run by the user of the Workspace Yes -
files object Settings related to Workspace files No {}
custom object Any custom data No {}

example:

{
  "version": 2.1,

  "scenarios": {
    "simple_run": {
      "stages": {
        "run": {
          "command": ".sphere-engine/run.sh"
        }
      }
    }
  }
}

root.version

Version of the config file.

type: number
required: yes
values: 2.1

example:

"version": 2.1

root.scenarios

A collection of scenarios that will be run by the user of the Workspace.

type: object
required: yes
parameters:

Name Type Description Required
_scenarioName1_ object(scenario) Definition of scenario #1 No
... ... ... ...
_scenarioName2_ object(scenario) Definition of scenario #N No

example:

{
  "my_custom_scenario_1": {
    "stages": {
      "run": {
        "command": ".sphere-engine/run1.sh"
      }
    }
  },
  "my_custom_scenario_2": {
    "stages": {
      "build": {
        "command": ".sphere-engine/build.sh"
      },
      "run": {
        "command": ".sphere-engine/run2.sh"
      }
    }
  }
}

Note: It is necessary to define at least one scenario

Note: You can use any custom name for a key in the scenarios JSON structure.

root.scenarios._scenarioName_

A definition of a single execution scenario.

type: object
required: yes
parameters:

Name Type Description Required Default
default boolean If set to true, this scenario will be run on Ctrl+Enter keyboard shortcut in the Workspace No false
network boolean Should the Workspace have access to the Internet No false
services array[string] Services needed in a scenario; e.g. database No []
output object Settings related to scenario output data No {}
stages object Stages that will be run one after another in a given scenario Yes -
auxdata object Collection of directories that should be collected and archived among other scenario execution results No {}
tests_weights array[test_selector] List of test case selectors used to assign scores to test cases No []

example:

{
  "stages": {
    "build": {
      "command": ".sphere-engine/build.sh"
    },
    "run": {
      "command": ".sphere-engine/run2.sh"
    }
  }
}

Note: It is necessary to define at least one stage.

root.scenarios._scenarioName_.default

Whether this scenario should be run on Ctrl+Enter keyboard shortcut in the Workspace.

type: boolean
required: no
default: false

example:

"default": true

root.scenarios._scenarioName_.network

Should the Workspace have access to the Internet.

type: boolean
required: no
default: false

example:

"network": true

root.scenarios._scenarioName_.services

Services needed in a scenario; e.g. database

type: array[string]
required: no
default: []
available services:

Service name Description Details
mysql MySQL database server port: 3306
mongodb MongoDB database server port: 27017
vnc VNC (Virtual Network Computing) server port: 5901
nginx nginx web server port: TODO

example:

"services": ["mysql", "mongodb"]

root.scenarios._scenarioName_.output

Settings related to scenario output data

type: object
required: no
default: {}
parameters:

Name Type Description Required Default
type string Type of the Workspace's output data Yes -
path string Path to the output file or url to the server No _empty_
show_at_startup boolean Whether to present the output when the Workspace loads No false

example:

{
  "type": "file",
  "path": "my_output.csv",
  "show_at_startup": true
}

root.scenarios._scenarioName_.output.type

Type of the Workspace's output data.

type: string
required: yes
values: console, file, none, tests, vnc, web

example:

"type": "web"

root.scenarios._scenarioName_.output.path

Path to the output file or url to the server.

type: string
required: no
default: _empty_

example:

"path": "my_output.csv"

Note: The value should contain relative or absolute path to the file or url on the server.

Note: The value can be omitted if the output type is set to tests.

root.scenarios._scenarioName_.output.show_at_startup

Whether to present the output when the Workspace loads

type: boolean
required: no
default: false

example:

"show_at_startup": true

root.scenarios._scenarioName_.stages

A sequence of consecutive Workspace execution stages

type: object
required: yes
parameters:

Name Type Description Required Default
init object(stage) Stage #1 - init No {}
build object(stage) Stage #2 - build No {}
run object(stage) Stage #3 - run No {}
test object(stage) Stage #4 - test No {}
post object(stage) Stage #5 - post No {}

example:

{
  "build": {
    "command": ".sphere-engine/build.sh"
  },
  "run": {
    "command": ".sphere-engine/run.sh"
  }
}

Note: It is necessary to define at least one stage.

root.scenarios._scenarioName_.stages._stageName_

Configuration of an individual stage.

stage_name: init, build, run, test, post
type: object
required: no
parameters:

Name Type Description Required Default
command string Path to a a script or shell command to run Yes -
skip boolean Whether to skip the stage No false
timeout number Timeout of a stage in seconds No 30
redirect_streams_to string Where the standard output stream of a stage should be redirected No console

example:

{
  "command": ".sphere-engine/stage_script.sh",
  "skip": false,
  "timeout": 10
}

root.scenarios._scenarioName_.stages._stageName_.command

Path to a a script or shell command to run

type: string
required: no

example:

"command": ".sphere-engine/stage_script.sh"

Note: The value should contain relative or absolute path to the Bash script or a shell command to run.

root.scenarios._scenarioName_.stages._stageName_.skip

Whether to skip the stage

type: string
required: no
default: false

example:

"skip": true

root.scenarios._scenarioName_.stages._stageName_.timeout

Timeout of a stage in seconds

type: string
required: no
default: 30

example:

"timeout": 90

Note: For the value, provide an integer representing the number of seconds.

root.scenarios._scenarioName_.stages._stageName_.redirect_streams_to

Where the standard output stream of a stage should be redirected

type: string
required: no
default: console
values: console, files

example:

"redirect_streams_to": "files"

root.scenarios._scenarioName_.auxdata

A collection of directories that should be collected and archived among other scenario execution results. It is provided as key: value pairs, where the key is a name under which the directory pointed by the value should be stored.

For more information, please refer to a extended description of this parameter.

type: object
required: no
default: {}

example:

{
  "custom_dir1": "d1",
  "custom_dir2": "d2",
  "custom_dir3": "/tmp/xyz"
}

root.scenarios._scenarioName_.tests_weights

A collection of selectors for WeightedScoreTestsGrader that specify what scores assign to what unit tests.

You can find complete weighted unit tests example here

type: array
required: no
parameters:

Name Type Description Required
[0] object(test_selector) Definition of unit test case selector #1 No
... ... ... ...
[N] object(test_selector) Definition of unit tests case selector #N No

example:

[
  {
    "name": "test_add_operation",
    "weight": 20
  },
  {
      "name": "test_add_operation",
      "status": "failure",
      "weight": -20
  },
  {
      "name": "test_mul_operation",
      "weight": 20
  }
]

root.scenarios._scenarioName_.tests_weights[i]

A definition of a single test case selector. You can learn more here WeightedScoreTestsGrader.

type: object
required: yes
parameters:

Name Type Description Required Default
name string Test case name to be matched No "*"
classname string Test case class name to be matched No "*"
status "ok" | "failure" | "error" Test case status to be matched No "ok"
weight number Score that will be assigned to a test matched by this test case selector Yes

example:

{
    "name": "test_add_operation",
    "status": "failure",
    "classname": "*",
    "weight": -20
}

Note: It is necessary to define weight, all other properties are optional.

root.files

Settings related to Workspace files.

type: object
required: no
default: {}
parameters:

Name Type Description Required Default
hidden array[string] Files that will be hidden from the file explorer No []
open_at_startup array[string] Files that will be open when the Workspace loads No []
read_only array[string] Files that are read only - cannot be modified in the Workspace No []

example:

{
  "hidden": [".env", ".gitignore"],
  "open_at_startup": ["README.md"],
  "read_only": ["config.yaml"]
}

root.files.hidden

Files that will be hidden from the file explorer.

type: array[string]
required: no
default: []

example:

"hidden": [".env", ".gitignore"]

Note: Each element of the list should contain relative or absolute path to the project file or directory that should be hidden in the file directory.

root.files.open_at_startup

Files that will be open when the Workspace loads.

type: array[string]
required: no
default: []

example:

"open_at_startup": ["README.md"]

Note: Each element of the list should contain relative or absolute path to the project file that should automatically open during Workspace's launch.

root.files.read_only

Files that are read only - cannot be modified in the Workspace

type: array[string]
required: no
default: []

example:

"read_only": ["config.yaml"]

Note: Each element of the list should contain relative or absolute path to the project file whose permissions should be limited to read-only.

root.custom

Any data of any structure.

type: object
required: no
default: {}
parameters: any

example:

{
  "internal_tag": "3317c1863f8dd227c2e438e6cabf466b",
  "categories": ["simple programming", "data processing", "algorithms"]
}