README.md 3.1 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
# 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, ...

27
28
29
Once logged, the users are redirected to the first page (the one with
the smallsest `position`).

30
31
32
33
34
35
36
37

## 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
38
39
# How to contribute

Antoine Angot's avatar
Antoine Angot committed
40
41
42

## Requirements

43
This project requires Python 3.6 at least.
Antoine Angot's avatar
Antoine Angot committed
44

45
46

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

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

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

60
61
62
```
celery -A hkis worker
```
Julien Palard's avatar
Julien Palard committed
63

Julien Palard's avatar
Julien Palard committed
64

Julien Palard's avatar
Julien Palard committed
65
66
## Translations

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

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

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


## 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
92
93
94
95
96
97
  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.
98
99
100
101
102

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.