This repository contains the Django project, website, CI/CD configuration, build scripts, and management commands for Palindrome's 2022 MIT Mystery Hunt.
You can learn more about the MIT Mystery Hunt, or view the 2022 Hunt website and puzzles.
You may be interested if this repository if you're:
- re-running the hunt for your team with hunt-style unlocking and managing the hunt as it runs,
- creating your own hunt and want to fork this codebase,
- merging some of our features into your own hunt, or
- reading about the tech stack and infrastructure as a guide for running your own MITMH-scale event.
This repository is not formally maintained and responding to emails or PRs is best-effort. (But we'll especially do our best to merge in fixes for the recently-broken copy-to-clipboard feature!)
Note: When running the server or managing it, you need to provide a DJANGO_ENV
environment variable. The commands below will show how to do this in bash. If you're using a different platform, make sure to change how you pass the environment variable as follows:
- In bash, run
DJANGO_ENV=dev python manage.py runserver
- In PowerShell, run
$env:DJANGO_ENV='dev'; python manage.py runserver
- In Window's
cmd.exe
, runset DJANGO_ENV=dev
first, and then run the commands below without any prefix. However, bash commands likemkdir
won't work, so really just use PowerShell instead.
Note: You may need to use python3
instead of python
in the commands below, depending on how Python is installed in your environment.
Note: The public version of this repository does not enable Git Large File Storage (LFS), so it can be cloned without counting against Palindrome's LFS bandwidth. If forking to make changes, we recommend enabling LFS by following these instructions and if necessary, migrate files.
Our
.gitattributes
config was:*.wav filter=lfs diff=lfs merge=lfs -text *.mp3 filter=lfs diff=lfs merge=lfs -text *.mp4 filter=lfs diff=lfs merge=lfs -text *.pdf filter=lfs diff=lfs merge=lfs -text
The first-time you want to develop or run the server, do the following.
- Install
Python 3.9+
and if needed,pip
(which should be part of your Python install already).- On Windows, make sure you add the Python install location to the
PATH
. You can tell if it worked by typingpython
into a command prompt.
- On Windows, make sure you add the Python install location to the
- Make a directory to store hunt code.
mkdir -p path/to/hunt cd path/to/hunt
- Clone the
2022-hunt
repository.git clone https://github.com/Palindrome-Puzzles/2022-hunt.git
- Move into the
2022-hunt
repo. All following commands will be run from this directory.cd 2022-hunt
- (Windows only) Fix symlinks if necessary. In an admin PowerShell, run the following script.
bin\fix-symlink-windows.ps1
- Why: This repository uses symlinks so that puzzles and rounds can be postprodded ergonomically while also making the files available where Django expects them to be.
- In Windows, symlinks require admin rights to create, so Git doesn't create them unless you were already an admin when you cloned/pulled the repo. This script repairs the symlinks.
- Set up a virtual environment.
python -m venv env
- Why: This lets Python dependencies can be installed and isolated from the system Python installation.
- Activate the virtual environment.
- In PowerShell and
cmd.exe
, runenv\Scripts\activate
. - In bash, run
source env/bin/activate
. - (To deactivate, run
env\Scripts\deactivate\
orsource env/bin/deactivate
.)
- In PowerShell and
- Install Python dependencies.
pip install -r requirements/dev.txt
- Why: This repository supports multiple environments, and uses a minimal set of dependencies in the dev environment. For example, we use SQLite instead of Postgres for portability and ease-of-setup.
- Setup your new database. This will create and use an SQLite
db.sqlite3
file in thepath/to/hunt/2022-hunt
directory.DJANGO_ENV=dev python manage.py migrate
- "Launch" the hunt locally. This imports some admin teams, the 2022 puzzles, and configures the website state so that teams can register and solve puzzles.
DJANGO_ENV=dev python manage.py importteams DJANGO_ENV=dev python manage.py importpuzzles DJANGO_ENV=dev python manage.py launch registration DJANGO_ENV=dev python manage.py launch rd0 DJANGO_ENV=dev python manage.py launch rd0-released DJANGO_ENV=dev python manage.py launch hunt
Some puzzles in the hunt have a separate build process that compiles Typescript and SCSS code to raw Javascript and CSS. If you'd like to view and solve these puzzles, then perform the following steps.
- Install Node. This was developed using Node 14, but newer versions should be fine too.
- Install dependencies for this repository.
cd path/to/hunt/2022-hunt npm install
- Then either:
- Run
npm run build
to build puzzle files. - Run
npm run watch
to continuously build puzzle files, and re-build them whenever they are changed. (This is useful when actively developing!)
- Run
Note: The script will automatically minify bundles and include sourcemaps if your
DJANGO_ENV
starts withprod_
.
Warning: Running the build process on Windows can give a different output compared to non-Windows machines (say Github Actions or Heroku). This is because
esbuild
uses\n
or\r\n
depending on the environment, which changes content hashes and so filenames. This can be avoided if you minify bundles and skip sourcemaps.
To run the server, use the following command.
DJANGO_ENV=dev python manage.py runserver
The following URLs will be available.
- http://localhost:8000 to access the solver-facing hunt website.
- http://registration.localhost:8000 to access the hunt registration website.
- http://localhost:8000/hq/ to access the hunt management interface (HQ). This is for the hunt team during the hunt to see how solvers are progressing, mark off interactions as complete, process hints, respond to incoming emails or help requests, and more.
- http://localhost:8000/hq/admin/ to access the Django admin panel. This is for viewing and editing database models directly. Please be very careful in here, as it has the potential to break the hunt.
- http://localhost:8000/puzzlelzzup/ to see Puzzleviewer. This lets you browse postprodded puzzles regardless of the hunt state. This is great for postprodders or factcheckers who don't need the whole hunt website running.
For the solver-facing hunt website, you can either use a team defined in teams.tsv, or register a new team. The admin teams in teams.tsv have special privileges like accessing puzzles that are still locked, or shortcuts to auto-solve puzzles.
For the admin panels, you will need to log in as a team with admin rights from teams.tsv. For Puzzleviewer, you will need to log in as any non-public team from teams.tsv.
Note: On Macs using browsers other than Chrome, you probably need to edit /etc/hosts
to allow sub-domains of .localhost
to be resolved.
Some modules have further documentation:
.github/workflows
for our CI/CD setup using Github Actionshunt/app
for the code and infrastructure for the 2022 hunt websitehunt/app/special_puzzles
for a framework for writing interactive puzzleshunt/data
for all 2022 hunt puzzle and round related data including postprodded puzzle bundles. Some of the data is automatically pushed to this repo. For example, PuzzUp will push puzzle content when a postprodded bundle is uploaded, and generatemetadata.json
andhints.json
files automaticallyhunt/data_loader
contains utilities to load hunt data in a packaging-agnostic wayhunt/deploy
is a thin wrapper Django project. It contains scripts and configs to start the hunt server locally, or to deploy to staging/production environmentshunt/puzzleviewer
is a tool to postprod and factcheck puzzles without going through the full hunt websitehunt/registration
is the 2022 registration website
The spoilr
package is a hunt-agnostic Django project to manage hunt state, and provide an admin panel for managing a live hunt.
There is also project-level documentation:
- archiving the hunt website
- deployment guide for how to run your own version of the 2022 hunt
- editor setup for tips on setting up your editor
- features for a summary of new and enhanced features in the 2022 hunt. You may be interested if running your own hunt, as it provides ideas and code links
- forking guide for some tips on forking this codebase to run your own hunt
- future work for future work and TODO tasks
- management guide for how to manage a live hunt
- postproduction guide for an export of the internal postproduction guide we developed for our postprodding team
- tech stack overview for an overview of our tech stack, as a starting point if you're running an MITMH-scale event
This project draws from and is inspired by earlier Hunt websites. Much of the direction was influenced in particular by Galactic's 2021 MIT Mystery Hunt (and their secondary repo).
An incomplete list of other hunt websites:
- Galactic: https://github.com/galacticpuzzlehunt/gph-site
- Teammate: https://gitlab.com/teammate/tph-site
- Dan Lepage
- Jacob Ford
- James Sugrono
- Isaac Garfinkle
- Matt Cleinman
- Sandy Weisz
- Shai Nir Hana
- Shawn Ligocki
- Aaron Fuegi
- Ashley Davis
- Ben Smith
- Daniel Hunt
- Deborah Levinson
- Foggy Brume
- Isaac Garfinkle
- Jacob Ford
- James Sugrono
- Jen McTeague
- Joe Cabrera
- Kieran Boyd
- Mike Seplowitz
- Phil Steindel
- Sahil Bhasin
- Sandy Weisz
- Shai Nir Hana
- Shawn Ligocki
This project has different licenses for different sections of the codebase.
-
The following puzzles are licensed under the Creative Commons Attribution Non-Commercial No-Derviatives license.
-
All images, sounds, and videos are licensed under the Creative Commons Attribution Non-Commercial No-Derviatives license.
-
All fonts are co-located with their own license.
-
Anything else within the
hunt/data
folder is licensed under Creative Commons Attribution Non-Commercial license. -
Everything else in the repository is licensed under the MIT license.
If there are questions about the licensing, please contact Palindrome.