README.md 3.54 KB
Newer Older
1
# HackInScience
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
## Setup

First `firejail` and `redis` (from your package manager), like:

    apt install firejail redis

Install the dependencies:

    python -m pip install requirements.txt

Then run the classical Django things:

    ./manage.py migrate
    ./manage.py loaddata initial
    ./manage.py compilemessages --ignore '.tox' --ignore '.venv'
    ./manage.py createsuperuser

Then in two distinct terminals, or by detaching one of them:

    ./manage.py correction_bot

and:

    ./manage.py runserver


Now you can login to `/admin`, from here you can change everything
about your installation: manage users, create pages, create exercises,
teams, review answers, and so on.
32
33
34
35
36

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.

37
38
39
40
41
42
Alternatively, one can use the `hkis` app alone, in order to
personalize registration, urls, and so on, for this you can install
hkis as a django app in your own project:

    pip install django-hkis

43
44
45
46
A simple example project can be seen at:

=> https://framagit.org/hackinscience/hkis-example

47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

## 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, ...

62
63
64
Once logged, the users are redirected to the first page (the one with
the smallsest `position`).

65
66
67
68
69
70
71
72

## 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
73
74
# How to contribute

Antoine Angot's avatar
Antoine Angot committed
75

76
## Updating the intial fixture
77

78
To save the initial.json file, use:
Antoine Angot's avatar
Antoine Angot committed
79

80
    ./manage.py dumpdata --indent 4 -e admin -e auth.Permission -e contenttypes -e sessions -o hkis/fixtures/initial.json
Julien Palard's avatar
Julien Palard committed
81

Julien Palard's avatar
Julien Palard committed
82

Julien Palard's avatar
Julien Palard committed
83
84
## Translations

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

Julien Palard's avatar
Julien Palard committed
87
```
Julien Palard's avatar
Julien Palard committed
88
$ ./manage.py makemessages --locale fr
89
$ ./manage.py makemessages --locale fr --domain djangojs
Julien Palard's avatar
Julien Palard committed
90
# Edit the .po files
91
$ ./manage.py compilemessages --ignore '.tox' --ignore '.venv'
Julien Palard's avatar
Julien Palard committed
92
93
```

Julien Palard's avatar
Julien Palard committed
94
95
Exercises (title and wording) are translated via the admin (or the
API), we use django-modeltranslation.
96
97
98
99
100
101
102
103
104
105
106
107
108
109


## 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
110
111
112
113
114
115
  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.
116
117
118
119
120

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.