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"]
}