Skip to content
This repository
tree: 8befdb1bc6
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 358 lines (309 sloc) 14.551 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357
===========================================================
   VERY VERY IMPORTANT
   VERY VERY IMPORTANT
===========================================================
Cyber-Dojo clients have full rights on the Cyber-Dojo server. If you
setup your own server you are strongly advised to consider using
o) a dedicated server.
o) a virtual box.
o) a dedicated network segment.


Running your own VirtualBox TurnKey Linux Cyber-Dojo server
==========================================================
Install VirtualBox from http://www.virtualbox.org/
Download the TurnKey Linux image from
http://dl.dropbox.com/u/11033193/CyberDojo/Turnkey-CyberDojo-20120515.ova (817MB)
This image supports 13 languages (C, C++, C#, Coffeescript, Erlang, Go, Haskell,
Java, Javascript, Perl, PHP, Python, Ruby).
Run the ova file in VirtualBox. Mike Long has written some instructions for this here
http://www.jaggersoft.com/CyberDojoTurnKeyLinuxVirtualBoxserverimageInstructions.pdf
The Virtual Box screen will tell you its IP address, eg 192.168.2.13
Put the URL into your browser. That's it!


Pulling the latest github source onto your Turnkey server
=========================================================
Add port 12320 to the URL you put into your browser above, eg
192.168.2.13:12320
Now you need the username and password.
I will happily tell you these if you email me: jon@jaggersoft.com
Pull the latest Cyber-Dojo source code from github onto your TurnKey image
>cd /var/www/cyberdojo
>git pull origin master
Occasionally this will pull new directories. You must ensure these
have the correct rights
>cd /var/www
>chgrp -R www-data cyberdojo
>chown -R www-data cyberdojo
And don't forget to reboot apache
>service apache2 restart



Configuring a practice-kata
===========================
The server will ask you to choose
o) your language (eg C++)
   Each language corresponds to a sub-directory of cyberdojo/languages/
   (see below)
o) your exercise (eg Prime Factors)
   Each exercise corresponds to a sub-directory of cyberdojo/exercises/
   (see below)


Entering a practice-kata (Start Coding)
=======================================
The server will assign you an animal 'avatar' (eg Panda).
The animal provides identity for each codebase.
You can resume coding at any time by choosing the animal.
This is handy if a laptop has to retire as a new laptop can easily and
instantly replace it.


Traffic Lights
==============
The display of each run-tests increment uses a traffic light, with meanings
for the three colours as follows:
  (o) red - tests ran but at least one failed
  (o) amber - syntax error somewhere, tests not run
  (o) green - tests ran and all passed
The colours are positional, top red, middle amber, bottom green.
This means you can still read the display if you are colour blind.
Note: you will also get an amber traffic light if the tests do not
complete within 10 seconds.


View-Dashboard
==============
The dashboard shows a periodically updating display of all traffic lights for
all the computers in the practice-kata.
If you want to collapse the horizontal time gaps simply enter
a very large value for the seconds_per_column value.


Diff-view
=========
Clicking on a traffic light opens a new page showing the diffs for that increment
together with < and > buttons to step backwards and forwards through the diffs.
The diff-view page does not work properly in Internet Explorer 8.
A diff-view will automatically open the file with the most changes.
Selecting a file in the diff-view auto-scrolls to the first diffed lines.

   
Versions
========
After Johannes Brodwall's sterling upgrade work my server reports...
>rake about
Ruby version 1.9.3 (i686-linux)
RubyGems version 1.8.24
Rack version 1.4
Rails version 3.2.3
JavaScript Runtime therubyracer (V8)


Installing Languages
====================
The base rails3 image is available here (417MB)
http://dl.dropbox.com/u/11033193/CyberDojo/Turnkey-CyberDojo-20120515.base.ova
(see http://jonjagger.blogspot.co.uk/2012/05/building-rails-3-turnkey-image.html
for details on how I built it) and supports for C, C++,
Python, Perl and Ruby. I installed the other 8 languages onto this baseline
rails 3 image (to create the larger 817MB ova file above) as follows...

#apt-get update
-----Java (125MB)
#apt-get install default-jdk
-------C# (27MB)
#apt-get install mono-gmcs
#apt-get install nunit-console
#cd /var/www/cyberdojo/languages/C#
#rm *.dll
#cp /usr/lib/cli/nunit.framework-2.4/nunit.framework.dll .
I edited the /var/www/cyberdojo/languages/C#/manifest.rb file this
   :support_filenames => %w( nunit.framework.dll )
There was a permission issue. Using strace suggested the following
which fixed the problem
#mkdir /var/www/.mono
#chgrp www-data .mono
#chown www-data .mono
-------Erlang(26MB)
#apt-get install erlang
(thanks to Kalervo Kujala)
------Haskell (111MB)
#apt-get install libghc6-hunit-dev
(thanks to Miika-Petteri Matikainen)
------Go (44MB)
#cd ~
#wget http://go.googlecode.com/files/go.go1.linux-386.tar.gz
#tar -C /usr/local -xzf go.go1.linux-386.tar.gz
#rm go.go1.linux-386.tar.gz
I then had to add the following line to /etc/apache2/envvars/
#export PATH=$PATH:/usr/local/go/bin
-----Javascript (63MB)
#cd ~
#git clone git://github.com/joyent/node.git
#cd node
#git checkout v0.6.17
#./configure
#make
#make install
#cd ~
#rm -r node
(see https://github.com/joyent/node/wiki/Installation)
-----CoffeeScript (3MB)
#npm install --global jasmine-node
(thanks to Johannes Brodwall)
(ensure JavaScript node is installed first as per instructions above)
-----PHP (3MB)
#apt-get install phpunit


Adding a new exercise
=====================
1. Create a new sub-directory under cyberdojo/exercises/
  Example: cyberdojo/exercises/FizzBuzz
2. Create a text file called instructions in this directory.
  Example: cyberdojo/exercises/FizzBuzz/instructions


Adding a new language
=====================
Create a new sub-directory under cyberdojo/languages/
  For example: cyberdojo/languages/Lisp
Create a manifest.rb file in this directory.
  For example: cyberdojo/languages/Lisp/manifest.rb
Each manifest.rb file contains an inspected ruby object.
Example: cyberdojo/languages/Java/manifest.rb looks like this:
{
  :visible_filenames => %w( Untitled.java UntitledTest.java cyberdojo.sh ),
  :support_filenames => %w( junit-4.7.jar ),
  :unit_test_framework => 'junit',
  :tab_size => 4
}

The intention is to use a specific structure for the contents of the
manifests to enable an automated check to see what is correctly installed
and working, and to only offer installed and working languages when you
configure a new practice-kata. However at the moment when you configure a
new practice-kata all language/ subfolders are offered.

For each language...
o) Cyber-Dojo searches through its manifests' :visible_filenames,
   in sequence, looking for any that contain the string '42'
o) If it doesn't find any it will not offer that language when
   you configure a new kata.
o) If it finds at least one file containing '42' it will pick the
   first one as "the-42-file"
o) It will then use the manifest to create a kata and run-the-tests
   three times as follows:
   test-1 - with the files unchanged.
   test-2 - with the 42 in the-42-file replaced by 54
   test-3 - with the 42 replaced by 4typo2
o) If test-1 generates a red traffic-light and
      test-2 generates a green traffic-light and
      test-3 generates an amber traffic-light then
   then the Cyber-Dojo server assumes the language is installed and working
   and it will offer that language when you create a new kata.
o) If the three tests return three amber traffic-lights then
   the Cyber-Dojo server assumes the language is not installed
   and it won't offer that language when you configure a new kata.
o) If the three tests return any other combination of traffic-lights
   the Cyber-Dojo server assumes the language is installed but not working.
   
You can test if a languages' initial fileset is correctly setup as follows
>cd cyberdojo/test/unit
>ruby installation_tests.rb
(NB this is out of date and needs reworking after the rails 3 upgrade.)
Note: this may issue the following error
   sh: Syntax error: Bad fd number
when this happened to me I fixed it as follows
>sudo rm /bin/sh
>sudo ln -s /bin/bash /bin/sh


manifest.rb Parameters
======================
:visible_filenames
  The names of the text files that will be visible in the browser's editor
  at startup. Each of these files must exist in the directory.
  The filename cyberdojo.sh must be present, either as a visible filename or a
  hidden filename. This is because cyberdojo.sh is the name of the shell file
  assumed by the ruby code (in the server) to be the start point for running
  the tests. You can write any actions in the cyberdojo.sh file but clearly
  any programs it tries to run must be installed on the server.
  For example, if cyberdojo.sh runs gcc to compile C files then gcc has
  to be installed. If cyberdojo.sh runs javac to compile java files then javac
  has to be installed.

:hidden_filenames
  The names of text files that are not visible in the browser's editor but
  which will nonetheless be available each time the player runs their tests.
  Each of these files must exist in the directory.
  For example, test framework library code.
  Not required if you do not need hidden files.
  
:support_filenames
  The names of necessary supporting non-text files. Each of these files must
  exist in the directory. For example, junit jar files or nunit assemblies.
  Not required if you do not need support files.
  
:unit_test_framework
  The name of the unit test framework used. This name partially determines the
  name of the ruby function (in the Cyber-Dojo server) used to parse the
  run-tests output (to see if the increment generates a red/green/amber
  traffic light). For example, if the value is 'cassert' then
      cyberdojo/lib/CodeOutputParser.rb
  must contain a method called parse_cassert() and will be called to parse the
  output of running the tests via the cyberdojo.sh shell file.
  Required. No default.

:tab_size
  This is the number of spaces a tab character expands to in the editor textarea.
  Not required. Defaults to 4 spaces.


Katas Directory Structure
=========================
The rails code does NOT use a database.
Instead each kata lives in a git-like directory structure based
on the first 10 characters of a uuidgen. For example
  cyberdojo/katas/82/B583C347
Each started avatar has a sub-directory underneath this, for example
  cyberdojo/katas/82/B583C347/wolf
  

Git Repositories
================
Each started animal avatar has its own git respository, eg
  cyberdojo/katas/82/B583C347/wolf/.git
The starting files (as loaded from the wolf/manifests.rb file) form
tag 0 (zero). Each run-the-tests event causes a new git commit and tag, with a
message and tag which is simply the increment number. For example, the fourth
time the wolf computer presses the run-the-tests button causes
>git commit -a -m '4'
>git tag -m '4' 4 HEAD
From an avatar's directory you can issue the following commands:
To look at filename for tag 4
>git show 4:sandbox/filename
To look at filename's differences between tag 4 and tag 3
>git diff 4 3 sandbox/filename
It's much easier and more informative to just click on a traffic light.
  

Sandboxes
=========
It used to be the case that a run-the-tests event would cause all the browser's
visible files to be saved into the avatar's sandbox folder along with the
language's hidden files and then the cyberdojo.sh file would be run on those
files. This is no longer the case. Now, the browser's visible files and the
language's hidden files are saved to a temporary dir under cyberdojo/sandboxes/
and the cyberdojo.sh file is run from there. This run generates output which is
captured and parsed to determine the appropriate traffic-light colour (red,
amber, or green). Then, the visible files (with the output added to it) and the
red/amber/green status is saved in the avatar's sandbox folder and git
committed. Running the tests is deliberately separated out to its own folder.
This separation offers an easy future route to running dedicated servers just
to run the tests.


Getting dojos off the VirtualBox TurnKey Linux server
=====================================================
You will need the username and password info to SSH and SFTP.
I will happily tell you it if you email me: jon@jaggersoft.com
1. SSH onto the server
2. cd /var/www/cyberdojo
3. to create a zip file of all dojos
     #ruby zipup.rb true 0 0
   will create zipped_dojos.zip
4. to create a zip file of just one dojo, eg 2F725592E3
     #zip -r zipped_dojo.zip katas/2F/725592E3
5. SFTP the zip file off the server



How to Turn off Chrome Spell-Checking in Chrome
===============================================
To turn it off (and avoid annoying red underlines the code editor)
1. Right click in the editor
2. Under Spell-checker Options>
3. Deselect 'Check Spelling in this Field'


How to Turn off Spell-checking in Opera/Firefox
===============================================
To turn it off (and avoid annoying red underlines the code editor)
1. Right click in the editor
2. Deselect 'Check spelling'


Misc Notes
==========
o) http://vimeo.com/15104374 has a video of me doing the Roman Numerals
   exercise in Ruby in a very early version of Cyber-Dojo
o) http://vimeo.com/8630305 has a video of an even earlier version of Cyber-Dojo
   I submitted as a proposal to the Software Craftsmanship conference 2010.
o) When I started Cyber-Dojo I didn't know any ruby, any rails, or any javascript
   (and not much css or html either). I'm self employed so I've have no-one to
   pair with (except google) while developing this in my limited spare time.
   Some of what you find is likely to be non-idiomatic. Caveat emptor!
o) I have worked hard to <em>remove</em> features from Cyber-Dojo. My idea is that
   the simpler the environment the more players will concentrate on the practice
   and the more they will need to collaborate with each other. Remember the aim
   of a Cyber-Dojo is <em>not</em> to ship something. The aim of Cyber-Dojo is to
   deliberately practice developing software collaboratively.
o) Olve Maudal, Mike Long and Johannes Brodwall have been enthusiastic about
   Cyber-Dojo and have provided lots of help right from the very early days.
   Olve, Mike and Johannes - I really appreciate all your help and encouragement.
Something went wrong with that request. Please try again.