README.md 3.02 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
# 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.


Julien Palard's avatar
Julien Palard committed
35
36
# How to contribute

Antoine Angot's avatar
Antoine Angot committed
37
38
39

## Requirements

40
This project requires Python 3.6 at least.
Antoine Angot's avatar
Antoine Angot committed
41

42
43

## Install
Antoine Angot's avatar
Antoine Angot committed
44

Julien Palard's avatar
Julien Palard committed
45
46
47
```
pip install -r requirements.txt
./manage.py migrate
Julien Palard's avatar
Julien Palard committed
48
./manage.py loaddata initial  # To get some users and exercises
Julien Palard's avatar
Julien Palard committed
49
50
# (Initial data can be updated using:
   ./manage.py dumpdata -e contenttypes -e auth.Permission -e sessions.session > website/fixtures/initial.json)
Julien Palard's avatar
Julien Palard committed
51
./manage.py createsuperuser
Jérôme's avatar
Jérôme committed
52
./manage.py runserver
Julien Palard's avatar
Julien Palard committed
53
54
```

55
To also run the moulinette, you'll need to install `firejail` and `redis` then run:
Julien Palard's avatar
Julien Palard committed
56

57
58
59
```
celery -A hkis worker
```
Julien Palard's avatar
Julien Palard committed
60

Julien Palard's avatar
Julien Palard committed
61

Julien Palard's avatar
Julien Palard committed
62
63
## Translations

Julien Palard's avatar
Julien Palard committed
64
65
Templates are translated using django `makemessages` and `compilemessages` commands:

Julien Palard's avatar
Julien Palard committed
66
```
Julien Palard's avatar
Julien Palard committed
67
$ ./manage.py makemessages --locale fr
68
$ ./manage.py makemessages --locale fr --domain djangojs
Julien Palard's avatar
Julien Palard committed
69
# Edit the .po files
Julien Palard's avatar
Julien Palard committed
70
$ ./manage.py compilemessages
Julien Palard's avatar
Julien Palard committed
71
72
```

Julien Palard's avatar
Julien Palard committed
73
74
Exercises (title and wording) are translated via the admin (or the
API), we use django-modeltranslation.
75
76
77
78
79
80
81
82
83
84
85
86
87
88


## 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
89
90
91
92
93
94
  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.
95
96
97
98
99

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.