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 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 names as they appear in the start-point setup pages where you select your language and 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 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).


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

The extensions of filenames that identify source files which are listed above the 'output' file 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. Cannot be greater than 20.
Defaults to 10.


"tab_size": int

The number of spaces a tab character expands to in the browser's textarea editor.
Defaults to 4.


"progress_regexs": [ string, string ]

Two 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. 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.
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.
A strict subset of "visible_filenames".
For example
"highlight_filenames": [ "buffer.cpp", "buffer.hpp" ]
The appearance of "highlight_filenames" is controlled by the CSS in kata.css.scss
div[class~='filename'][class~='highlight'] { ... }
Defaults to [ ].

running your own cyber-dojo web server