repo for the cyberdojo/runner_stateful docker image.
Switch branches/tags
Nothing to show
Clone or download
Failed to load latest commit information.

Build Status

cyber-dojo yin/yang logo

cyberdojo/runner-stateful docker image

  • A docker-containerized stateful micro-service for cyber-dojo.
  • Runs an avatar's tests.
  • A docker-volume holds the state of each practice session.


  • All methods receive their named arguments in a json hash.
  • All methods return a json hash.
    • If the method completes, a key equals the method's name.
    • If the method raises an exception, a key equals "exception".

GET sha

Returns the git commit sha used to create the docker image.

  • parameters, none
  • returns the sha, eg
  { "sha": "b28b3e13c0778fe409a50d23628f631f87920ce5" }

POST kata_new

Sets up the kata with the given kata_id. Must be called once before any call to avatar_new with the same kata_id.

  • parameters, eg
  { "image_name": "cyberdojofoundation/gcc_assert",
       "kata_id": "15B9AD6C42"

POST kata_old

Tears down the kata with the given kata_id.

  • parameters, eg
  { "image_name": "cyberdojofoundation/gcc_assert",
       "kata_id": "15B9AD6C42"

POST avatar_new

Sets up the avatar with the given avatar_name, in the kata with the given kata_id, with the given starting files. Must be called once before any call to run_cyber_dojo_sh with the same kata_id and avatar_name.

  • parameters, eg
  {     "image_name": "cyberdojofoundation/gcc_assert",
           "kata_id": "15B9AD6C42",
       "avatar_name": "salmon",
    "starting_files": { "hiker.h": "#ifndef HIKER_INCLUDED...",
                        "hiker.c": "#include...",

POST avatar_old

Tears down the avatar with the given avatar_name, in the kata with the given kata_id.

  • parameters, eg
  {  "image_name": "cyberdojofoundation/gcc_assert",
        "kata_id": "15B9AD6C42",
    "avatar_name": "salmon"

POST run_cyber_dojo_sh

Saves the unchanged files, the changed_files, and the new files, deletes the deleted_files, and runs as the avatar with the given avatar_name.

  • parameters, eg
  {        "image_name": "cyberdojofoundation/gcc_assert",
              "kata_id": "15B9AD6C42",
          "avatar_name": "salmon",
            "new_files": { ... },
        "deleted_files": { ... },
      "unchanged_files": { "" => "make" },
        "changed_files": { "fizz_buzz.c" => "#include...",
                           "fizz_buzz.h" => "#ifndef FIZZ_BUZZ_INCLUDED...",
          "max_seconds": 10
  • returns [stdout, stderr, status, colour] as the results of executing
  • returns [new_files, deleted_files, changed_files] which are text files altered by executing
  • if the execution completed in max_seconds, colour will be "red", "amber", or "green".
  • if the execution did not complete in max_seconds, colour will be "timed_out".


    { "run_cyber_dojo_sh": {
        "stdout": "makefile:17: recipe for target 'test' failed\n",
        "stderr": "invalid suffix sss on integer constant",
        "status": 2,
        "colour": "amber",
        "new_files":{ ... },
        "changed_files":{ ... }


    { "run_cyber_dojo_sh": {
        "stdout": "...",
        "stderr": "...",
        "status": 137,

The traffic-light colour is determined by passing stdout, stderr, and status to a Ruby lambda, read from the named image, at /usr/local/bin/red_amber_green.rb. eg

lambda { |stdout, stderr, status|
  output = stdout + stderr
  return :red   if /(.*)Assertion(.*)failed./.match(output)
  return :green if /(All|\d+) tests passed/.match(output)
  return :amber
  • If this file does not exist in the named image, the colour is "amber".
  • If the contents of this file raises an exception when eval'd or called, the colour is "amber".
  • If the lambda returns anything other than :red, :amber, or :green, the colour is "amber".

build the docker images

Builds the runner-server image and an example runner-client image.

$ ./sh/

bring up the docker containers

Brings up a runner-server container and a runner-client container.

$ ./sh/

run the tests

Runs the runner-server's tests from inside a runner-server container and then the runner-client's tests from inside the runner-client container.

$ ./sh/

run the demo

$ ./sh/

Runs inside the runner-client's container. Calls the runner-server's micro-service methods and displays their json results and how long they took. If the runner-client's IP address is then put into your browser to see the output.

  • grey: tests did not complete (in 3 seconds)
  • red: tests ran but failed
  • amber: tests did not run (syntax error)
  • green: tests ran and passed

demo screenshot

red amber green demo home page