Monarch Of The Hill - base infrastructure for computer-based puzzle contests
Go to file
John Donaldson 152da3667c Adding some issue templates 2020-02-28 23:14:05 +00:00
.github Adding some issue templates 2020-02-28 23:14:05 +00:00
contrib Modify smash script to trigger the bug 2019-04-30 03:49:59 +00:00
devel Revert "Add a few things for new CyFi theme" 2020-02-28 22:49:48 +00:00
docs Adding dependencies into devel instructions 2019-12-18 22:32:28 +00:00
example-puzzles Merge pull request #80 from int00h5525/add_local_python_library_support 2019-10-18 16:23:54 -05:00
src Added id parameter to points.json to return only a team's score 2019-11-19 19:16:21 -07:00
theme Make top-scoring team take full width 2019-11-20 16:23:01 -08:00
.dockerignore More dockering 2017-09-11 16:12:22 +00:00
.gitignore Reworked some basics of how the Puzzle class works. Shouldn't look to different from the outside. 2016-10-17 13:24:54 -06:00 Updating changelog with info about autobuild 2020-02-28 21:57:51 +00:00 @nealey 's spelling is impractical 2020-02-21 21:25:13 +00:00
Dockerfile.moth Adding license to Docker images 2020-01-30 00:03:07 +00:00
Dockerfile.moth-devel Merge branch 'v3.5_devel' of into add_contributing_document 2020-02-21 18:33:34 +00:00 Change license to comply with LANL legal request 2017-09-08 20:58:33 +00:00 Adding workflows that build Docker images and display a badge on the 2020-02-28 21:52:25 +00:00 Throttle submissions per team (more...) 2019-03-07 22:03:48 -05:00
VERSION Releasing v3.4.3 2019-11-20 18:30:48 -06:00 No, I meant push latest 2018-10-03 01:26:40 +00:00 update usage message 2017-09-15 10:27:53 -06:00

Dirtbags Monarch Of The Hill Server



This is a set of thingies to run our Monarch-Of-The-Hill contest, which in the past has been called "Tracer FIRE", "Project 2", "HACK", "Queen Of The Hill", "Cyber Spark", "Cyber Fire", "Cyber Fire Puzzles", and "Cyber Fire Foundry".

Information about these events is at

This software serves up puzzles in a manner similar to Jeopardy. It also tracks scores, and comes with a JavaScript-based scoreboard to display team rankings.

Running a Development Server

To use example puzzles

docker run --rm -it -p 8080:8080 dirtbags/moth-devel

or, to use your own puzzles

docker run --rm -it -p 8080:8080 -v /path/to/puzzles:/puzzles:ro dirtbags/moth-devel

And point a browser to http://localhost:8080/ (or whatever host is running the server).

The development server includes a number of Python libraries that we have found useful in writing puzzles.

When you're ready to create your own puzzles, read the devel server documentation.

Click the [mb] link by a puzzle category to compile and download a mothball that the production server can read.

Running a Production Server

docker run --rm -it -p 8080:8080 -v /path/to/moth/state:/state -v /path/to/moth/balls:/mothballs:ro dirtbags/moth

You can be more fine-grained about directories, if you like. Inside the container, you need the following paths:

  • /state (rw) Where state is stored. Read the overview to learn what's what in here.
  • /mothballs (ro) Mothballs (puzzle bundles) as provided by the development server.
  • /resources (ro) Overrides for built-in HTML/CSS resources.

Getting Started Developing

If you don't have a puzzles directory, you can copy the example puzzles as a starting point:

$ cp -r example-puzzles puzzles

Then launch the development server:

$ python3 devel/

Point a web browser at http://localhost:8080/ and start hacking on things in your puzzles directory.

More on how the devel sever works in the devel server documentation

Running A Production Server

Run dirtbags/moth (Docker) or mothd (native).

mothd assumes you're running a contest out of /moth. For Docker, you'll need to bind-mount your actual directories (state, mothballs, and optionally resources) into /moth/.

You can override any path with an option, run mothd -help for usage.

State Directory

Pausing scoring

Create the file state/disabled to pause scoring, and remove it to resume. You can use the Unix touch command to create the file:

touch state/disabled

When scoring is paused, participants can still submit answers, and the system will tell them whether the answer is correct. As soon as you unpause, all correctly-submitted answers will be scored.

Resetting an instance

Remove the file state/initialized, and the server will zap everything.

Setting up custom team IDs

The file state/teamids.txt has all the team IDs, one per line. This defaults to all 4-digit natural numbers. You can edit it to be whatever strings you like.

We sometimes to set teamids.txt to a bunch of random 8-digit hex values:

for i in $(seq 50); do od -x /dev/urandom | awk '{print $2 $3; exit;}'; done

Remember that team IDs are essentially passwords.

Enabling offline/PWA mode

If the file state/export_manifest is found, the server will expose the endpoint /current_manifest.json?id=<teamId>. This endpoint will return a list of all files, including static theme content and JSON and content for currently-unlocked puzzles. This is used by the native PWA implementation and Cache button on the index page to cache all of the content necessary to display currently-open puzzles while offline. Grading will be unavailable while offline. Some puzzles may not function as expected while offline. A valid team ID must be provided.

Mothball Directory

Installing puzzle categories

The development server will provide you with a .mb (mothball) file, when you click the [mb] link next to a category.

Just drop that file into the mothballs directory, and the server will pick it up.

If you remove a mothball, the category will vanish, but points scored in that category won't!

Contributing to MOTH

Please read