cyber-dojo web server default  start-points

  • This page holds the choices where you select your language and test framework (eg C#, NUnit) and exercise (eg Fizz Buzz).
  • This start-point is called languages.
  • By default, the languages+testFrameworks is created from the languages_list file which contains a list of repo-URLs in the cyber-dojo-languages github organization, each of which contain a manifest.json file.
  • By default, the exercises list is created from the start-points-exercises github repo which contains instructions text files.



  • This page holds the customized choices.
  • This start-point is called custom
  • By default, custom is created from the start-points-custom github repo which contains manifest.json files.



creating a new default start-point

To use a different default start-point simply bring down the server, delete the one you wish to replace, create a new one with that name, and bring the server back up. For example, to create a new languages start-point:
$ ./cyber-dojo down $ ./cyber-dojo start-point rm languages $ ./cyber-dojo start-point create languages --dir=... $ ./cyber-dojo up


$ ./cyber-dojo start-point ...

Start-points are controlled using the start-point command of the cyber-dojo script.
$ ./cyber-dojo start-point Use: cyber-dojo start-point [COMMAND] Manage cyber-dojo start-points Commands: create Creates a new start-point inspect Displays details of a start-point latest Updates pulled docker images named inside a start-point ls Lists the names of all start-points pull Pulls all the docker images named inside a start-point rm Removes a start-point Run 'cyber-dojo start-point COMMAND --help' for more information on a command

For example:
$ ./cyber-dojo start-point ls NAME TYPE SRC custom custom https://github.com/cyber-dojo/start-points-custom.git exercises exercises https://github.com/cyber-dojo/start-points-exercises.git languages languages https://github.com/cyber-dojo/start-points-languages.git

For example:
$ ./cyber-dojo start-point inspect languages DISPLAY_NAME IMAGE_NAME PULLED? Asm, assert cyberdojofoundation/nasm_assert yes BCPL, all_tests_passed cyberdojofoundation/bcpl_all_tests_passed yes Bash, bash_unit cyberdojofoundation/bash_unit yes ... C (clang), Cgreen cyberdojofoundation/clang_cgreen yes ... C (gcc), Cgreen cyberdojofoundation/gcc_cgreen yes ... C#, Moq cyberdojofoundation/csharp_moq yes ... C++ (clang++), Cgreen cyberdojofoundation/clangpp_cgreen yes ... C++ (g++), Boost.Test cyberdojofoundation/gpp_boosttest yes ... Clojure, Midje cyberdojofoundation/clojure_midje yes ... CoffeeScript, jasmine cyberdojofoundation/coffeescript_jasmine yes D, unittest cyberdojofoundation/d_unittest yes Erlang, eunit cyberdojofoundation/erlang_eunit yes F#, NUnit cyberdojofoundation/fsharp_nunit yes Fortran, FUnit cyberdojofoundation/fortran_funit yes Go, testing cyberdojofoundation/go_testing yes Groovy, JUnit cyberdojofoundation/groovy_junit yes ... Haskell, hunit cyberdojofoundation/haskell_hunit yes Java, Cucumber cyberdojofoundation/java_cucumber yes ... Javascript, Mocha+chai+sinon cyberdojofoundation/javascript-node_mocha_chai_sinon yes ... PHP, PHPUnit cyberdojofoundation/php_phpunit yes Perl, Test::Simple cyberdojofoundation/perl_test_simple yes Python, py.test cyberdojofoundation/python_pytest yes Python, unittest cyberdojofoundation/python_unittest yes R, RUnit cyberdojofoundation/r_runit yes Ruby, Cucumber cyberdojofoundation/ruby_cucumber yes ... Rust, test cyberdojofoundation/rust_test yes Swift, XCTest cyberdojofoundation/swift_xctest yes VHDL, assert cyberdojofoundation/vhdl_assert yes VisualBasic, NUnit cyberdojofoundation/visual-basic_nunit yes


$ ./cyber-dojo start-point create Use: cyber-dojo start-point create NAME --list=URL|FILE Creates a start-point named NAME from git-clones of all the URLs listed in URL|FILE Use: cyber-dojo start-point create NAME --git=URL Creates a start-point named NAME from a git clone of URL Use: cyber-dojo start-point create NAME --dir=DIR Creates a start-point named NAME from a copy of DIR NAME's first letter must be [a-zA-Z0-9] NAME's remaining letters must be [a-zA-Z0-9_.-] NAME must be at least two letters long


cyber-dojo new release

The new release of cyber-dojo just went live :-)




creating your own server start-points

cyber-dojo's new architecture has customisable start-points.
If you want to use your own start-points you do not need to build a new web server image.

preparing your custom/languages start-point

  • Create a folder for the start-point
    eg
    $ md douglas
  • In the top-level folder create a file start_point_type.json
    eg
    $ touch douglas/start_point_type.json
    This file must specify the type of start-point.
    • languages (the type where setup will ask for an exercise)
      { 'type' : 'languages' }
    • custom (the type where setup will not ask for an exercise)
      { 'type' : 'custom' }
  • Create a sub-folder for each start-point entry
    eg
    $ md douglas/first
  • Create a manifest.json file in each folder
    eg
    $ nano douglas/first/manifest.json
  • Here's an example. Here's an explanation of the manifest.json format.
  • In each folder create the visible files named in manifest.json
    Here's an example



preparing your exercises start-point

  • Create a folder for the start-point
    eg
    $ md arthur
  • In the top-level folder create a file start_point_type.json
    eg
    $ touch arthur/start_point_type.json
    This file must specify the type of start-point.
    { 'type' : 'exercises' }
  • Create a sub-folder for each exercise
    eg
    $ md arthur/first
  • Create an instructions file in each folder
    $ nano arthur/first/instructions
    Here's an example



creating your start-point

Use the cyber-dojo script to create a new start-point. For example
$ cd douglas $ [sudo] ./cyber-dojo start-point create adams --dir=${PWD}
which attempts to create a start-point called adams from all the files in the douglas directory. If the creation fails the cyber-dojo script will print diagnostics.


starting your server with your start-point

eg with a type=custom start-point called hiker
$ [sudo] ./cyber-dojo up --custom=hiker
eg with a type=languages start-point named adams
$ [sudo] ./cyber-dojo up --languages=adams
eg with a type=exercises start-point named arthur
$ [sudo] ./cyber-dojo up --exercises=arthur
eg with a combination
$ [sudo] ./cyber-dojo up --languages=adams --exercises=arthur


adding a new language + test-framework to cyber-dojo

THE INFORMATION BELOW IS OUT OF DATE.
It will be updated properly soon.
Meanwhile, follow step 0 below, and then look at these examples from the cyber-dojo-languages github organization: Note how each repo's .travis.yml file simply runs the run_build_image.sh script which builds and tests the docker image and any associated start-point code. In particular the script augments the Dockerfile commands in various ways (eg adding users for the 64 avatars). Alternatively, if you are building your docker-image using a raw [docker build] command you must base your docker-image FROM a cyber-dojo-languages dockerhub image.


0. Install docker



1. Create a docker-image for just the language

Make this docker-image unit-test-framework agnostic.
If you are adding a new unit-test-framework to an existing language skip this step.
For example, suppose you were building Lisp
  • Create a new folder for your language
    eg.
    $ md lisp
  • In your language's folder, create a file called Dockerfile
    $ cd Lisp $ touch Dockerfile
    If you can, base your new image on Alpine-linux as this will help keep images small. To do this make the first line of Dockerfile as follows
    FROM cyberdojofoundation/language-base
    Here's one based on Alpine-linux (217 MB: C#) Dockerfile
    Here's one not based on Alpine (Ubuntu 1.26 GB: Python) Dockerfile
  • Use the Dockerfile to build a docker-image for your language.
    For example
    $ docker build -t cyberdojofoundation/lisp .
    which, if it completes, creates a new docker-image called cyberdojofoundation/lisp using the Dockerfile (and build context) in . (the current folder).


2. Create a docker-image for the language and test-framework

Repeat the same process, building FROM the docker-image you created in the previous step.
For example, suppose your Lisp unit-test framework is called lunit
  • Create a new folder underneath your language folder
    $ cd lisp $ md lunit
  • In your new test folder, create a file called Dockerfile
    $ cd lunit $ touch Dockerfile
    The first line of this file must name the language docker-image you built in the previous step.
    Add lines for all the commands needed to install your unit-test framework...
    FROM cyberdojofoundation/lisp RUN apt-get install -y lispy-lunit RUN apt-get install -y ...
  • Create a file called red_amber_green.rb
    $ touch red_amber_green.rb
  • In red_amber_green.rb write a Ruby lambda accepting three arguments. For example, here is the C#-NUnit red_amber_green.rb:
    lambda { |stdout,stderr,status| output = stdout + stderr return :red if /^Errors and Failures:/.match(output) return :green if /^Tests run: (\d+), Errors: 0, Failures: 0/.match(output) return :amber }
    cyber-dojo uses this to determine the test's traffic-light colour by passing it the stdout, stderr, and status outcomes of the test run.
  • The Dockerfile for your language+testFramework must COPY red_amber_green.rb into the /usr/local/bin folder of your image. For example:
    FROM cyberdojofoundation/lisp RUN apt-get install -y lispy-lunit RUN apt-get install -y ... COPY red_amber_green.rb /usr/local/bin
    I usually start with a red_amber_green.rb that simply returns :red. Then, once I have a start-point using the language+testFramework docker-image, I use cyber-dojo to gather outputs which I use to build up a working red_amber_green.rb
  • Use the Dockerfile to try and build your language+testFramework docker-image.
    The name of an image takes the form hub-name/image-name. Do not include a version number in the image-name. For example
    $ docker build -t cyberdojofoundation/lisp_lunit .
    which, if it completes, creates a new docker image called cyberdojofoundation/lisp_lunit using the Dockerfile in . (the current folder).


3. Use the language+testFramework docker-image in a new start-point

Use the new image name (eg cyberdojofoundation/lisp_lunit) in a new manifest.json file in a new start-point.





cyber-dojo start-points manifest.json entries explained

Example: the manifest.json file for Java/JUnit currently looks like this:

{ "display_name": "Java, JUnit", "visible_filenames": [ "Hiker.java", "HikerTest.java", "cyber-dojo.sh" ], "image_name": "cyberdojofoundation/java_junit", "runner_choice": "stateless", "filename_extension": ".java", "tab_size": 4, "progress_regexs" : [ "Tests run\\: (\\d)+,(\\s)+Failures\\: (\\d)+", "OK \\((\\d)+ test(s)?\\)" ] }



Required entries


"display_name": string

The name as it appears in the start-point setup pages where you select your language-plus-test-framework. For example, "Java, JUnit" means that "Java, JUnit" will appear as a selectable entry. A single string with the major name first, then a comma, then the minor name.


"visible_filenames": [ string, string, ... ]

Filenames that will be visible in the browser's editor when an animal initially enter's a cyber-dojo. Each of these files must exist in the manifest.json's directory. Filenames can be in nested sub-directories, eg "tests/HikerTest.java". Must include cyber-dojo.sh. This is because cyber-dojo.sh is the name of the shell file assumed by the runner to be the start point for running the tests. You can write any actions inside cyber-dojo.sh but clearly any programs it tries to run must be installed in the docker image_name. For example, if cyber-dojo.sh runs gcc to compile C files then gcc has to be installed. If cyber-dojo.sh runs javac to compile java files then javac has to be installed.


"image_name": string

The name of the docker image used to run a container in which cyber-dojo.sh is executed. Do not include any version numbers (eg of the compiler or test-framework). The docker image must contain a file called red_amber_green.rb in the /usr/local/bin directory. The runner uses this to determine the traffic-light colour of each test run outcome. For example, here's the one for Java-JUnit.


"runner_choice": string

The string "stateless" or "stateful". Each test run is handled by either the stateless-runner or the stateful-runner. The stateless runner does not maintain state between test runs, the stateful runner does. In other words, when using the stateless runner the binary files produced by your cyber-dojo.sh script (eg .o files created from .c files via a makefile) do not exist at the start of the next test run. With the stateful runner, they do. Use the stateless runner unless you can gain a significant speed up with the stateful runner (which requires extra disk-space and cpu from the host server).
Deprecated.
In the next release this will be ignored and the only runner will be the stateless runner.


"filename_extension": [ string, string, ... ]

The extensions of filenames that identify source files which are listed above the output file(s) in the filename list. The first entry is also used when creating a new filename. For example, if set to ".java" the new filename will be filename.java. If you only have a single filename extension you can use a single string instead of an array containing a single string.


Optional entries


"max_seconds": int

The maximum number of seconds cyber-dojo.sh has to complete the tests.
An integer between 1 and 20.
Defaults to 10.


"tab_size": int

The number of spaces a tab character expands to in the browser's textarea editor.
An integer between 1 and 12.
Defaults to 4.


"hidden_filenames": [ string, string, ... ]

When the runner runs cyber-dojo.sh, it it often creates files. All text-files that are created are returned to the browser unless their name matches any of the string regexs.
An array of strings used to create Ruby regexs, used by cyber-dojo, like this Regexp.new(string). For example, to hide files ending in .d you can use the following string ".*\\.d"
Defaults to [ ].


"progress_regexs": [ string, string ]

Used on the dashboard to show the test output line (which often contains the number of passing and failing tests) of each animal's most recent red/green traffic light. Useful when your practice session starts from a large number of pre-written tests and you wish to monitor the progress of each animal.
An array of two strings used to create Ruby regexs. The first one to match a red traffic light's test output, and the second one to match a green traffic light's test output.
Defaults to [ ].


"highlight_filenames": [ string, string, ... ]

Filenames whose appearance is highlighted in the browser. This can be useful if you have many "visible_filenames" and want to mark which files form the focus of the practice.
An array of strings. A strict subset of "visible_filenames".
Defaults to [ ].

running your own cyber-dojo web server