LEdoian
/
recodex-wiki
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Formatting

Browse Source
master
Petr Stefan 8 years ago
parent dc03438129
commit 814fba5b3e
1 changed files with 69 additions and 119 deletions
Show Stats Download Patch File Download Diff File

188
Rewritten-docs.md
Unescape Escape View File

@ -1,56 +1,3 @@
<!---
Notes:
* Dvoustrankovy uvod - co by to melo umet
* Analýza - co se rozhodneme delat, jak by se to dalo delat, pridelit dulezitost
- pak se da odkazat na to, proc jsme co nestihli, zahrnout i advanced featury
- odkazovat se u featur, ze to je v planu v pristich verzi - co je dulezite
a co ne!! Zduvodnit tim, jakou podmnozinu featur nechat, snaze se pak bude
popisovat architektura
* V analyze vysvetlit architekturu
* Related works nechat jako samostatnou kapitolu
* Poradi - pozadavky -> related works -> analyza
* Provazani komponent musi rozumet administrator a tvurce ulohy - obecna
kapitola v analyze - puvodni kapitola o analyze byla povedena, jen se tam
micha seznam zprav nebo co - to nezajima vsechny
* Po obecnym uvodu - rozdelit podle potencialniho ctenare - uzivatel ucitel, pak
uzivatel admin
* Instalacni dokumentace stranou, jako posledni
* Uzivatelaka dokumentace - admin: popis prav, autor uloh: nejobsahlejsi, format
skriptu - ale formulovat tak, ze bude popis na co kde kliknout, jazyk popsat
separatne - v budoucnu to bude irelevantni, je potreba daleko hloubeji - je
treba popsat detailne co eelaji, i treba relativni/absolutni adresy, makra,
kde vidi prekladac knihovny a headery... - kapitola na konci
* Uzivatelska dokumentace pro studenta: vysvetleni
* Jak se boduje uloha - tezko rict, kam to patri - nekde na zacatku? Ale zajima
to vsechny role, ucitel musi vedet, jak to nakonfigurovat - zminit treba i jak
bodovat podle casu a pameti (v analyze nebo v uvodu) - vice vystupu od judge,
interpolace bodu podle vyuziti pameti... je to spis mimo uživatelskou
* Nepsat kde na jake tlacitko kliknout
* Tutorialy - scenare, co udelat kdyz chci neco, vzorove pruchody
* U formularu je nejlepsi kdyz zadna dokumentace neni, doplnit popisky k polim
formularu
* V dokumentaci popsat konfigy nekde separatne - skore, yaml - referencni
dokumentace
* Urcite ne FAQ, vic strukturovane
* Instalaci dohromady na konec
* Programatorska dokumentace - "nejmene ctenaru" - neco uz tam mame, neni to
treba davat do tistene dokumentace - do tistene dokumentace dat odkaz na wiki,
neco v tistene ale byt musi - jaky jazyk, designové rozhodnutí - zdůvodnění
nedávat do úvodní analýzy - k referencnim dokumentacim udelat uvod - "restove
API jsme pojali timto zpusobem, deli se to na tyto skupiny, ..."
* Co zvolena architektura znamena, neco to ma dat i uzivateli, ktery
architekturu nezna, kde je drzenej stav
* Z dokumentace musi byt patrne, co dela knihovna a co se musi udelat rucne -
kolik je to prace - psat to vic pro uzivatele, ktery zna technologie, nezna
knihovny
* Mit soucit s tema, ktery to toho tolik neznaji - jak technologie, tak
architekturu a system CodExu
* Nesedi cisla stranek
* Stazeni ZIPu s vystupy Backendu - roztridit na verejne a tajne, verejne i pro
studenta
-->
# Introduction # Introduction
Generally, there are many different ways and opinions on how to teach people Generally, there are many different ways and opinions on how to teach people
@ -276,7 +223,8 @@ addons (mostly administrative features).
(for example "sum all numbers from given file and write the result to the (for example "sum all numbers from given file and write the result to the
standard output") and to browse this database standard output") and to browse this database
- _customizable grading system_ -- teachers need to specify the way of - _customizable grading system_ -- teachers need to specify the way of
computation of the final score, which will be awarded to the submissions of the student depending on their quality computation of the final score, which will be awarded to the submissions of
the student depending on their quality
- _viewing student details_ -- teachers should be able to view the details of - _viewing student details_ -- teachers should be able to view the details of
their students (members of their groups), including all submitted solutions their students (members of their groups), including all submitted solutions
- _awarding additional points_ -- adding (or subtracting) points from the final - _awarding additional points_ -- adding (or subtracting) points from the final
@ -284,8 +232,8 @@ addons (mostly administrative features).
- _marking a solution as accepted_ -- the system should allow marking one - _marking a solution as accepted_ -- the system should allow marking one
particular solution as accepted (used for grading the assignment) by the particular solution as accepted (used for grading the assignment) by the
supervisor supervisor
- _solution resubmission_ -- teachers should be able edit the solutions of the student - _solution resubmission_ -- teachers should be able edit the solutions of the
and privately resubmit them, optionally saving all results (including student and privately resubmit them, optionally saving all results (including
temporary ones); this feature can be used to quickly fix obvious errors in the temporary ones); this feature can be used to quickly fix obvious errors in the
solution and see if it is otherwise viable solution and see if it is otherwise viable
- _localization_ -- all texts (UI and exercises) should be translatable - _localization_ -- all texts (UI and exercises) should be translatable
@ -310,10 +258,10 @@ addons (mostly administrative features).
OAuth, should be supported OAuth, should be supported
- _querying SIS_ -- loading user data from the university information system - _querying SIS_ -- loading user data from the university information system
should be supported should be supported
- _sandboxing_ -- there should be a safe environment in which the - _sandboxing_ -- there should be a safe environment in which the solutions of
solutions of the students are executed to prevent system failures due to malicious code being the students are executed to prevent system failures due to malicious code
submitted; the sandboxed environment should have the least possible impact on being submitted; the sandboxed environment should have the least possible
measurement results (most importantly on measured times) impact on measurement results (most importantly on measured times)
- _heterogeneous worker pool_ -- there must be support for submission evaluation - _heterogeneous worker pool_ -- there must be support for submission evaluation
in multiple programming environments in a single installation to avoid in multiple programming environments in a single installation to avoid
unacceptable workload for the administrator (maintaining a separate unacceptable workload for the administrator (maintaining a separate
@ -334,8 +282,8 @@ not know about these features if they work properly, but would be at least
annoyed if they did not. annoyed if they did not.
- _no installation_ -- the primary user interface of the system must be - _no installation_ -- the primary user interface of the system must be
accessible on the computers of the users without the need to install any additional accessible on the computers of the users without the need to install any
software additional software
- _performance_ -- the system must be ready for at least hundreds of students - _performance_ -- the system must be ready for at least hundreds of students
and tens of supervisors using it at once and tens of supervisors using it at once
- _automated deployment_ -- all of the components of the system must be easy to - _automated deployment_ -- all of the components of the system must be easy to
@ -1699,8 +1647,8 @@ modern web applications.
We examined several frameworks which are commonly used to speed up the We examined several frameworks which are commonly used to speed up the
development of a web application. There are several open source options development of a web application. There are several open source options
available with a large number of tools, tutorials, and libraries. From the many available with a large number of tools, tutorials, and libraries. From the many
options (Backbone, Ember, Vue, Cycle.js, ...) there are two main frameworks worth options (Backbone, Ember, Vue, Cycle.js, ...) there are two main frameworks
considering: worth considering:
- **Angular 2** - it is a new framework which was developed by Google. This - **Angular 2** - it is a new framework which was developed by Google. This
framework is very complex and provides the developer with many tools which framework is very complex and provides the developer with many tools which
@ -2030,10 +1978,10 @@ available only for group administrators.
On "Dashboard" page you can find "Groups you supervise" section. Here there are On "Dashboard" page you can find "Groups you supervise" section. Here there are
boxes representing your groups with the list of students attending course and boxes representing your groups with the list of students attending course and
their points. Student names are clickable with redirection to the profile of the user their points. Student names are clickable with redirection to the profile of the
where further information about his/hers assignments and solution can be found. user where further information about his/hers assignments and solution can be
To quickly jump onto groups page, use "Show group's detail" button at the bottom found. To quickly jump onto groups page, use "Show group's detail" button at
of the matching group box. the bottom of the matching group box.
### Manage Group ### Manage Group
@ -2357,8 +2305,8 @@ appear in "Groups hierarchy" box at the top of the page.
On the instance details page, there is a box "Licences". On the first line, it On the instance details page, there is a box "Licences". On the first line, it
shows it this instance has currently valid licence or not. Then, there are shows it this instance has currently valid licence or not. Then, there are
multiple lines with all licences assigned to this instance. Each line consists of multiple lines with all licences assigned to this instance. Each line consists
a note, validity status (if it is valid or revoked by superadministrator) and of a note, validity status (if it is valid or revoked by superadministrator) and
the last date of licence validity. the last date of licence validity.
A box "Add new licence" is used for creating new licences. Required fields are A box "Add new licence" is used for creating new licences. Required fields are
@ -2499,9 +2447,9 @@ submission:
``` ```
Basically it means, that the job _hello-world-job_ needs to be run on workers Basically it means, that the job _hello-world-job_ needs to be run on workers
that belong to the `group_1` hardware group . Reference files are downloaded that belong to the `group_1` hardware group . Reference files are downloaded
from the default location configured in API (such as from the default location configured in API (such as
`http://localhost:9999/exercises`) if not stated explicitly otherwise. Job `http://localhost:9999/exercises`) if not stated explicitly otherwise. Job
execution log will not be saved to result archive. execution log will not be saved to result archive.
Next the tasks have to be constructed under _tasks_ section. In this demo job, Next the tasks have to be constructed under _tasks_ section. In this demo job,
@ -2649,9 +2597,9 @@ Broker implementation depends on several open-source C and C++ libraries.
YAML format. YAML format.
- **boost-filesystem** -- Boost filesystem is used for managing logging - **boost-filesystem** -- Boost filesystem is used for managing logging
directory (create if necessary) and parsing filesystem paths from strings as directory (create if necessary) and parsing filesystem paths from strings as
written in the configuration of the broker. Filesystem operations will be included in written in the configuration of the broker. Filesystem operations will be
future releases of C++ standard, so this dependency may be removed in the included in future releases of C++ standard, so this dependency may be
future. removed in the future.
- **boost-program_options** -- Boost program options is used for - **boost-program_options** -- Boost program options is used for
parsing of command line positional arguments. It is possible to use POSIX parsing of command line positional arguments. It is possible to use POSIX
`getopt` C function, but we decided to use boost, which provides nicer API and `getopt` C function, but we decided to use boost, which provides nicer API and
@ -2689,9 +2637,9 @@ maintain backward compatibility).
Fileserver stores its data in following structure: Fileserver stores its data in following structure:
- `./submissions/<id>/` -- folder that contains files submitted by users - `./submissions/<id>/` -- folder that contains files submitted by users (the
(the solutions to the assignments of the student). `<id>` is an identifier received from solutions to the assignments of the student). `<id>` is an identifier received
the REST API. from the REST API.
- `./submission_archives/<id>.zip` -- ZIP archives of all submissions. These are - `./submission_archives/<id>.zip` -- ZIP archives of all submissions. These are
created automatically when a submission is uploaded. `<id>` is an identifier created automatically when a submission is uploaded. `<id>` is an identifier
of the corresponding submission. of the corresponding submission.
@ -2705,9 +2653,9 @@ Fileserver stores its data in following structure:
## Worker ## Worker
The job of the worker is to securely execute a job according to its configuration and The job of the worker is to securely execute a job according to its
upload results back for latter processing. After receiving an evaluation configuration and upload results back for latter processing. After receiving an
request, worker has to do following: evaluation request, worker has to do following:
- download the archive containing submitted source files and configuration file - download the archive containing submitted source files and configuration file
- download any supplementary files based on the configuration file, such as test - download any supplementary files based on the configuration file, such as test
@ -2803,9 +2751,9 @@ directories (tasks can do whatever is allowed on the target system), but it is
advised not to write outside them. In addition, sandboxed tasks are usually advised not to write outside them. In addition, sandboxed tasks are usually
restricted to use only a specific (evaluation) directory. restricted to use only a specific (evaluation) directory.
The following directory structure is used for execution. The working The following directory structure is used for execution. The working directory
directory of the worker (root of the following paths) is shared for multiple instances on the of the worker (root of the following paths) is shared for multiple instances on
same computer. the same computer.
- `downloads/${WORKER_ID}/${JOB_ID}` -- place to store the downloaded archive - `downloads/${WORKER_ID}/${JOB_ID}` -- place to store the downloaded archive
with submitted sources and job configuration with submitted sources and job configuration
@ -2870,16 +2818,18 @@ them are multi-platform, so both Linux and Windows builds are possible.
Actual supported formats depends on installed packages on target system, but Actual supported formats depends on installed packages on target system, but
at least ZIP and TAR.GZ should be available. at least ZIP and TAR.GZ should be available.
- **cppzmq** -- Cppzmq is a simple C++ wrapper for core ZeroMQ C API. It - **cppzmq** -- Cppzmq is a simple C++ wrapper for core ZeroMQ C API. It
basicaly contains only one header file, but its API fits into the object architecture of the worker. basicaly contains only one header file, but its API fits into the object
architecture of the worker.
- **spdlog** -- Spdlog is small, fast and modern logging library. It is used for - **spdlog** -- Spdlog is small, fast and modern logging library. It is used for
all of the logging, both system and job logs. It is highly customizable and all of the logging, both system and job logs. It is highly customizable and
configurable from the configuration of the worker. configurable from the configuration of the worker.
- **yaml-cpp** -- Yaml-cpp is used for parsing and creating text files in YAML - **yaml-cpp** -- Yaml-cpp is used for parsing and creating text files in YAML
format. That includes the configuration of the worker, the configuration and the results of a job. format. That includes the configuration of the worker, the configuration and
the results of a job.
- **boost-filesystem** -- Boost filesystem is used for multi-platform - **boost-filesystem** -- Boost filesystem is used for multi-platform
manipulation with files and directories. However, these operations will be manipulation with files and directories. However, these operations will be
included in future releases of C++ standard, so this dependency may be included in future releases of C++ standard, so this dependency may be removed
removed in the future. in the future.
- **boost-program_options** -- Boost program options is used for multi-platform - **boost-program_options** -- Boost program options is used for multi-platform
parsing of command line positional arguments. It is not necessary to use it, parsing of command line positional arguments. It is not necessary to use it,
similar functionality can be implemented be ourselves, but this well known similar functionality can be implemented be ourselves, but this well known
@ -2938,15 +2888,15 @@ command (normally FINISHED) is received, then are permanently deleted. This
caching mechanism was implemented because early testing shows, that first couple caching mechanism was implemented because early testing shows, that first couple
of messages are missed quite often. of messages are missed quite often.
Messages from the queue of the client are sent through corresponding WebSocket connection Messages from the queue of the client are sent through corresponding WebSocket
via main event loop as soon as possible. This approach with separate queue per connection via main event loop as soon as possible. This approach with separate
connection is easy to implement and guarantees reliability and order of message queue per connection is easy to implement and guarantees reliability and order
delivery. of message delivery.
## Cleaner ## Cleaner
Cleaner component is tightly bound to the worker. It manages the cache folder of the worker, Cleaner component is tightly bound to the worker. It manages the cache folder of
mainly deletes outdated files. Every cleaner instance maintains one the worker, mainly deletes outdated files. Every cleaner instance maintains one
cache folder, which can be used by multiple workers. This means on one server cache folder, which can be used by multiple workers. This means on one server
there can be numerous instances of workers with the same cache folder, but there there can be numerous instances of workers with the same cache folder, but there
should be only one cleaner instance. should be only one cleaner instance.
@ -3133,8 +3083,8 @@ no empty frames (unles explicitly specified otherwise).
Broker acts as server when communicating with worker. Listening IP address and Broker acts as server when communicating with worker. Listening IP address and
port are configurable, protocol family is TCP. Worker socket is of DEALER type, port are configurable, protocol family is TCP. Worker socket is of DEALER type,
broker one is ROUTER type. Because of that, very first part of every (multipart) broker one is ROUTER type. Because of that, very first part of every (multipart)
message from broker to worker must be target the socket identity of the worker (which is message from broker to worker must be target the socket identity of the worker
saved on its **init** command). (which is saved on its **init** command).
#### Commands from Broker to Worker: #### Commands from Broker to Worker:
@ -3238,13 +3188,13 @@ capable to send corresponding credentials with each request.
#### Worker Side #### Worker Side
Workers comunicate with the file server in both directions -- they download Workers comunicate with the file server in both directions -- they download the
the submissions of the student and then upload evaluation results. Internally, worker is submissions of the student and then upload evaluation results. Internally,
using libcurl C library with very similar setup. In both cases it can verify worker is using libcurl C library with very similar setup. In both cases it can
HTTPS certificate (on Linux against system cert list, on Windows against verify HTTPS certificate (on Linux against system cert list, on Windows against
downloaded one from CURL website during installation), support basic HTTP downloaded one from CURL website during installation), support basic HTTP
authentication, offer HTTP/2 with fallback to HTTP/1.1 and fail on error authentication, offer HTTP/2 with fallback to HTTP/1.1 and fail on error
(returned HTTP status code is >=400). Worker have list of credentials to all (returned HTTP status code is >=400). Worker have list of credentials to all
available file servers in its config file. available file servers in its config file.
- download file -- standard HTTP GET request to given URL expecting file content - download file -- standard HTTP GET request to given URL expecting file content
@ -3269,20 +3219,20 @@ with proper configuration. Relevant commands for communication with workers:
successful upload returns JSON `{ "result": "OK" }` as body of returned page. successful upload returns JSON `{ "result": "OK" }` as body of returned page.
If not specified otherwise, `zip` format of archives is used. Symbol `/` in API If not specified otherwise, `zip` format of archives is used. Symbol `/` in API
description is root of the domain of the file server. If the domain is for example description is root of the domain of the file server. If the domain is for
`fs.recodex.org` with SSL support, getting input file for one task could look as example `fs.recodex.org` with SSL support, getting input file for one task could
GET request to look as GET request to
`https://fs.recodex.org/tasks/8b31e12787bdae1b5766ebb8534b0adc10a1c34c`. `https://fs.recodex.org/tasks/8b31e12787bdae1b5766ebb8534b0adc10a1c34c`.
### Broker - Monitor Communication ### Broker - Monitor Communication
Broker communicates with monitor also through ZeroMQ over TCP protocol. Type of Broker communicates with monitor also through ZeroMQ over TCP protocol. Type of
socket is same on both sides, ROUTER. Monitor is set to act as server in this socket is same on both sides, ROUTER. Monitor is set to act as server in this
communication, its IP address and port are configurable in the config of the monitor communication, its IP address and port are configurable in the config of the
file. ZeroMQ socket ID (set on the side of the monitor) is "recodex-monitor" and must be monitor file. ZeroMQ socket ID (set on the side of the monitor) is
sent as first frame of every multipart message -- see ZeroMQ ROUTER socket "recodex-monitor" and must be sent as first frame of every multipart message --
documentation for more info. see ZeroMQ ROUTER socket documentation for more info.
Note that the monitor is designed so that it can receive data both from the Note that the monitor is designed so that it can receive data both from the
broker and workers. The current architecture prefers the broker to do all the broker and workers. The current architecture prefers the broker to do all the
@ -3421,12 +3371,12 @@ Message format:
### Web App - Web API Communication ### Web App - Web API Communication
The provided web application runs as a JavaScript process inside the browser of the user. The provided web application runs as a JavaScript process inside the browser of
It communicates with the REST API on the server through the standard HTTP requests. the user. It communicates with the REST API on the server through the standard
Documentation of the main REST API is in a separate HTTP requests. Documentation of the main REST API is in a separate
[document](https://recodex.github.io/api/) due to its extensiveness. The results are [document](https://recodex.github.io/api/) due to its extensiveness. The results
returned encoded in JSON which is simply processed by the web application and are returned encoded in JSON which is simply processed by the web application
presented to the user in an appropriate way. and presented to the user in an appropriate way.
<!--- <!---

Write Preview
Loading…
Cancel
Save