# Using HackInScience First step after creating a superuser (using `./manage.py createsuperuser` is to login to `/admin`, from here you can change everything about your installation: manage users, create pages, create exercises, teams, review answers, and so on. A `/exercises` page, and a `/help` page has been created automatically for you, you may want to start by adding some exercises to the `exercises` page. ## The pages A page is literaly a URL in your site, it can contain text (stored Markdown) and/or exercises. For example the automatically created page at `/help` is aimed to store text but no exercises, and the page at `/exercises` is aimed to present some exercises, maybe after an intro text, or without any text. You can live with only those two pages, or create a whole set of pages like one exercise page per programming language, or per topic, per student class, ... ## The categories Inside a page, you can optionally group exercises in categories, instead of displaying them as a whole single big list. It becomes handy around 50~70 exercises. # How to contribute ## Requirements This project requires Python 3.6 at least. ## Install ``` pip install -r requirements.txt ./manage.py migrate ./manage.py loaddata initial # To get some users and exercises # (Initial data can be updated using: ./manage.py dumpdata -e contenttypes -e auth.Permission -e sessions.session > website/fixtures/initial.json) ./manage.py createsuperuser ./manage.py runserver ``` To also run the moulinette, you'll need to install `firejail` and `redis` then run: ``` celery -A hkis worker ``` ## Translations Templates are translated using django `makemessages` and `compilemessages` commands: ``` $ ./manage.py makemessages --locale fr $ ./manage.py makemessages --locale fr --domain djangojs # Edit the .po files $ ./manage.py compilemessages ``` Exercises (title and wording) are translated via the admin (or the API), we use django-modeltranslation. ## How does the checker bot work? The answers are load-balanced to correction workers using Celery, so you can have multiple machines dedicated to correct loads of answers. Once received by a worker the worker runs two things: - An optional `pre_check.py` script, that sets-up anything specific for this answers (required files and directories, translations, whatever is needed). - A `check.py` script is then started in a sandbox (no internet connectivity, restricted filesystem, CPU, memory usage, …). This is the script that check the student answer, the protocol is simple: if the script exits with non-zero, then then answer is wrong. And what's been printed (both stdout and stderr) is displayed, as Markdown, to the student. If the answer is right and nothing is printed, a default congratulation message is used. Both `pre_check.py` and `check.py` are in Python, but they're not limited to check for Python answers, if you want to check for shell script or C, or whatever, the `check.py` can use `subprocess` to run the answer script, or compile the answer code, or whatever needed.