2022 MIT Mystery Hunt

About

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!)

Getting started

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, run set DJANGO_ENV=dev first, and then run the commands below without any prefix. However, bash commands like mkdir 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.

Initial setup

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.

1. 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 typing python into a command prompt.
2. Make a directory to store hunt code.

   mkdir -p path/to/hunt
   cd path/to/hunt
   

3. Clone the 2022-hunt repository.

   git clone https://github.com/Palindrome-Puzzles/2022-hunt.git
   

4. Move into the 2022-hunt repo. All following commands will be run from this directory.

   cd 2022-hunt
   

5. (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.
6. Set up a virtual environment.

   python -m venv env
   

   • Why: This lets Python dependencies can be installed and isolated from the system Python installation.
7. Activate the virtual environment.
   • In PowerShell and cmd.exe, run env\Scripts\activate.
   • In bash, run source env/bin/activate.
   • (To deactivate, run env\Scripts\deactivate\ or source env/bin/deactivate.)
8. 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.
9. Setup your new database. This will create and use an SQLite db.sqlite3 file in the path/to/hunt/2022-hunt directory.

   DJANGO_ENV=dev python manage.py migrate
   

10. "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
    

Building puzzles

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.

1. Install Node. This was developed using Node 14, but newer versions should be fine too.
2. Install dependencies for this repository.

   cd path/to/hunt/2022-hunt
   npm install
   

3. 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!)

Note: The script will automatically minify bundles and include sourcemaps if your DJANGO_ENV starts with prod_.

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.

Running the server

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.

Further documentation

Some modules have further documentation:

• .github/workflows for our CI/CD setup using Github Actions
• hunt/app for the code and infrastructure for the 2022 hunt website
• hunt/app/special_puzzles for a framework for writing interactive puzzles
• hunt/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 generate metadata.json and hints.json files automatically
• hunt/data_loader contains utilities to load hunt data in a packaging-agnostic way
• hunt/deploy is a thin wrapper Django project. It contains scripts and configs to start the hunt server locally, or to deploy to staging/production environments
• hunt/puzzleviewer is a tool to postprod and factcheck puzzles without going through the full hunt website
• hunt/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

Acknowledgements

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).

Similar projects

An incomplete list of other hunt websites:

• Galactic: https://github.com/galacticpuzzlehunt/gph-site
• Teammate: https://gitlab.com/teammate/tph-site

Contributors

Tech lead

• Sahil Bhasin

Tech team

• Dan Lepage
• Jacob Ford
• James Sugrono
• Isaac Garfinkle
• Matt Cleinman
• Sandy Weisz
• Shai Nir Hana
• Shawn Ligocki

Postproduction team

• 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

License

This project has different licenses for different sections of the codebase.

1. The following puzzles are licensed under the Creative Commons Attribution Non-Commercial No-Derviatives license.

   • Curious and Determined
   • Sorcery for Dummies
   • The Times They Had

2. All images, sounds, and videos are licensed under the Creative Commons Attribution Non-Commercial No-Derviatives license.

3. All fonts are co-located with their own license.

4. Anything else within the hunt/data folder is licensed under Creative Commons Attribution Non-Commercial license.

5. Everything else in the repository is licensed under the MIT license.

If there are questions about the licensing, please contact Palindrome.