Prepare for a start-points re-architecture

A change to the cyber-dojo start-points architecture is coming.
The plan is to phase out the old architecture completely in a few months time.
Until then both architectures will work "side by side".
Here's how to try out the new architecture.

Recap: Retiring Architecture

  • cyber-dojo stores its start-points as docker volumes.
  • You create three start-point volumes by naming the sources using the --dir, --git, --list options.
    For example:
    $ ./cyber-dojo start-point create tutorials --dir=file:///Users/fred/custom-tutorials $ ./cyber-dojo start-point create tdd --git=https://github.com/org/repo/exercises-tdd.git $ ./cyber-dojo start-point create ruby --list=https://raw.githubusercontent.com/org/repo/master/langs-ruby-urls
  • You bring up your cyber-dojo server by naming (up to) three start-point volumes, one for each start-point type.
    You can omit any of the three -- settings and it will use its default.
    For example:
    $ ./cyber-dojo up \ --custom=tutorials \ --exercises=tdd \ --languages=ruby

Overview: Incoming Architecture

  • cyber-dojo will store it's start-points as docker images.
  • The --dir,--git,--list options will not be supported.
  • You will create one start-points image by naming all sources as git-repo-urls in a new bash script.
    Again, you can omit any of the three -- settings and it will use its default.
    For example:
    $ ./cyber_dojo_start_points_create.sh \ acme/my-start-points \ --custom \ file:///Users/fred/custom-tutorials \ --exercises \ https://github.com/org/repo/exercises-tdd.git \ --languages \ $(curl --silent https://raw.githubusercontent.com/org/repo/master/langs-ruby-urls)
  • You will bring up your cyber-dojo server by also naming the one start-points docker image.
    Leave the other three -- settings (all of which are optional) the same as in the retiring architecture.
    For example:
    $ ./cyber-dojo up \ --starter=acme/my-start-points \ --custom=tutorials \ --exercises=tdd \ --languages=ruby

Do an update

On your server, do an update:
$ ./cyber-dojo update

Install the new bash script

$ curl -O https://raw.githubusercontent.com/cyber-dojo/start-points-base/master/cyber_dojo_start_point_create.sh $ chmod 700 cyber_dojo_start_point_create.sh

To get detailed help:
$ ./cyber_dojo_start_points_create.sh --help Use: $ ./cyber_dojo_start_points_create.sh \ <image-name> \ [--custom <git-repo-url>...]... \ [--exercises <git-repo-url>...]... \ [--languages <git-repo-url>...]... ...

Create a manifest.json file for each exercise

In the retiring architecture, each --exercises start-point is simply a file called instructions. The name associated with each instructions file (when you set up a practice session) is the name of the directory where it lives (with underscores replaced by spaces).
In the incoming architecture, each -exercises start-point is specified by a manifest.json file. Its format is a subset of the --custom and --languages manifest.json files and has only two entries:
  • You must specify a display_name
  • You must specify the visible_filenames
  • visible_filenames cannot contain a file called cyber-dojo.sh
For example:
{ "display_name": "Fizz Buzz", "visible_filenames": [ "instructions" ] }

--dir=DIR details

Suppose you currently create an (exercises) start-point docker-volume named tdd with:
$ ./cyber-dojo start-point create \ tdd \ --dir=file:///Users/fred/tdd-exercises
and you bring up your cyber-dojo server with:
$ ./cyber-dojo up \ ... --exercises=tdd ...

--dir=DIR will not be supported.
To use the named DIR as a git-repo-url, DIR must contain a git repo.
$ cd /Users/fred/tdd-exercises $ git init $ git add . $ git config --global user.email "EMAIL" $ git config --global user.name "NAME" $ git commit -m "initial commit"
Create a new start-point docker-image named acme/my-start-points containing these (--exercises) start-points with:
$ ./cyber_dojo_start_points_create.sh \ acme/my-start-points \ --custom \ ... \ --exercises \ file:///Users/fred/tdd-exercises \ --languages \ ...
Bring up your cyber-dojo server by also naming the start-point image:
$ ./cyber-dojo up \ --starter=acme/my-start-points \ --custom=... \ --exercises=tdd \ --languages=...

--git=URL details

Suppose you currently create a (custom) start-point docker-volume named my-ruby-tutorials with:
$ ./cyber-dojo start-point create \ my-ruby-tutorials \ --git=https://github.com/org/repo/ruby-tutorials.git
and you bring up your cyber-dojo server with:
$ ./cyber-dojo up \ ... --custom=my-ruby-tutorials ...

--git=URL will not be supported.
Simply use the URL as a git-repo-url.
Create a new start-point docker-image named acme/my-start-points containing these (--custom) start-points with:
$ ./cyber_dojo_start_points_create.sh \ acme/my-start-points \ --custom \ https://github.com/org/repo/ruby-tutorials.git \ --exercises \ ... \ --languages \ ...
Bring up your cyber-dojo server by also naming the start-point image:
$ ./cyber-dojo up \ --starter=acme/my-start-points \ --custom=my-ruby-tutorials \ --exercises=... \ --languages=...


--list=LIST_URL details

Suppose you currently create a (languages) start-point docker-volume named common-langs with:
$ ./cyber-dojo start-point create \ common-langs \ --list=https://raw.githubusercontent.com/org/repo/master/common-langs-urls
where:
$ curl --silent https://raw.githubusercontent.com/org/repo/master/common-langs-urls https://github.com/cyber-dojo-languages/csharp-nunit.git https://github.com/cyber-dojo-languages/java-junit.git https://github.com/cyber-dojo-languages/javascript-cucumber.git https://github.com/cyber-dojo-languages/python-pytest.git https://github.com/cyber-dojo-languages/ruby-minitest.git
and you bring up your cyber-dojo server with:
$ ./cyber-dojo up \ ... --languages=common-langs ...

--list=LIST_URL will not be supported.
Simply use curl to get the URLs inside LIST_URL.
Create a new start-point docker-image named acme/my-start-points containing these (--languages) start-points with:
$ ./cyber_dojo_start_points_create.sh \ acme/my-start-points \ --custom \ ... \ --exercises \ ... \ --languages \ $(curl --silent https://raw.githubusercontent.com/org/repo/master/common-langs-urls)
which expands to:
$ ./cyber_dojo_start_points_create.sh \ acme/my-start-points \ --custom \ ... \ --exercises \ ... \ --languages \ https://github.com/cyber-dojo-languages/csharp-nunit.git \ https://github.com/cyber-dojo-languages/java-junit.git \ https://github.com/cyber-dojo-languages/javascript-cucumber.git \ https://github.com/cyber-dojo-languages/python-pytest.git \ https://github.com/cyber-dojo-languages/ruby-minitest.git
Bring up your cyber-dojo server by also naming the new start-point image:
$ ./cyber-dojo up \ --starter=acme/my-start-points \ --custom=... \ --exercises=... \ --languages=common-langs

Summary

  • A change to the cyber-dojo start-points architecture is coming.
  • To prepare for this change you can, for a while, use either architecture.
  • Do a [./cyber-dojo update]
  • Install the new bash script, cyber_dojo_start_points_create.sh
  • Create a manifest.json file for each exercise.
  • Note down all the --dir,--git,--list values you use when creating your three start-point docker volumes.
  • Create your new start-point docker image using only git-repo URLs:
    • --dir=DIR will not be supported. Create a git repository in DIR. The git-repo-url will be file://DIR
    • --git=URL will not be supported. The git-repo-url will be URL.
    • --list=LIST_URL will not be supported. Use curl to get the git-repo-urls inside LIST_URL.
  • Bring up your cyber-dojo server by also naming the new start-point image.