moth/README.md

168 lines
4.5 KiB
Markdown
Raw Normal View History

2016-01-31 20:45:35 -07:00
Dirtbags Monarch Of The Hill Server
2016-01-31 20:41:22 -07:00
=====================
2016-01-31 20:45:35 -07:00
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",
2016-10-21 14:38:19 -06:00
"Cyber Spark",
2018-09-17 17:00:08 -06:00
"Cyber Fire",
"Cyber Fire Puzzles",
and "Cyber Fire Foundry".
2016-01-31 20:41:22 -07:00
2016-01-31 20:45:35 -07:00
Information about these events is at
http://dirtbags.net/contest/
This software serves up puzzles in a manner similar to Jeopardy.
2016-10-21 14:38:19 -06:00
It also tracks scores,
2016-01-31 20:41:22 -07:00
and comes with a JavaScript-based scoreboard to display team rankings.
2018-09-20 10:15:34 -06:00
Running a Development Server
============================
2019-06-11 16:58:15 -06:00
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
2018-09-20 10:15:34 -06:00
And point a browser to http://localhost:8080/ (or whatever host is running the server).
2019-03-21 11:18:14 -06:00
The development server includes a number of Python libraries that we have found useful in writing puzzles.
2018-09-20 10:15:34 -06:00
When you're ready to create your own puzzles,
read [the devel server documentation](docs/devel-server.md).
Click the `[mb]` link by a puzzle category to compile and download a mothball that the production server can read.
Running a Production Server
===========================
2018-10-02 11:52:31 -06:00
docker run --rm -it -p 8080:8080 -v /path/to/moth/state:/state -v /path/to/moth/balls:/mothballs:ro dirtbags/moth
2018-09-20 10:15:34 -06:00
You can be more fine-grained about directories, if you like.
Inside the container, you need the following paths:
2018-10-02 11:52:31 -06:00
* `/state` (rw) Where state is stored. Read [the overview](docs/overview.md) 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.
2018-09-20 10:15:34 -06:00
2016-01-31 20:41:22 -07:00
Getting Started Developing
-------------------------------
2016-12-01 16:22:35 -07:00
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:
2019-12-18 15:30:08 -07:00
$ python3 devel/devel-server.py
2016-12-01 16:22:35 -07:00
Point a web browser at http://localhost:8080/
and start hacking on things in your `puzzles` directory.
2016-10-21 14:38:19 -06:00
More on how the devel sever works in
[the devel server documentation](docs/devel-server.md)
Running A Production Server
====================
2018-09-17 17:00:08 -06:00
Run `dirtbags/moth` (Docker) or `mothd` (native).
2018-09-17 17:00:08 -06:00
`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/`.
2016-01-31 20:41:22 -07:00
2018-09-17 17:00:08 -06:00
You can override any path with an option,
run `mothd -help` for usage.
2016-01-31 20:41:22 -07:00
2018-09-17 17:00:08 -06:00
State Directory
===============
2018-09-17 17:00:08 -06:00
Pausing scoring
-------------------
2018-09-17 17:00:08 -06:00
Create the file `state/disabled`
to pause scoring,
and remove it to resume.
You can use the Unix `touch` command to create the file:
2018-09-17 17:00:08 -06:00
touch state/disabled
2018-09-17 17:00:08 -06:00
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.
2018-09-17 17:00:08 -06:00
Resetting an instance
-------------------
2018-09-17 17:00:08 -06:00
Remove the file `state/initialized`,
and the server will zap everything.
2018-09-17 17:00:08 -06:00
Setting up custom team IDs
-------------------
2018-09-17 17:00:08 -06:00
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.
2016-01-31 20:41:22 -07:00
2018-09-17 17:00:08 -06:00
We sometimes to set `teamids.txt` to a bunch of random 8-digit hex values:
2016-01-31 20:41:22 -07:00
2018-09-17 17:00:08 -06:00
for i in $(seq 50); do od -x /dev/urandom | awk '{print $2 $3; exit;}'; done
2016-01-31 20:41:22 -07:00
2018-09-17 17:00:08 -06:00
Remember that team IDs are essentially passwords.
2016-01-31 20:41:22 -07:00
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.
2018-09-17 17:00:08 -06:00
Mothball Directory
==================
2016-01-31 20:41:22 -07:00
2018-09-17 17:00:08 -06:00
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!
2019-12-17 10:48:22 -07:00
Contributing to MOTH
==================
2018-09-17 17:00:08 -06:00
2019-12-17 10:48:22 -07:00
Please read [CONTRIBUTING.md](CONTRIBUTING.md)