From 277d385334e50ed5a7eeb8f481e84a753b263efb Mon Sep 17 00:00:00 2001 From: Martin Polanka Date: Thu, 26 Jan 2017 16:24:12 +0100 Subject: [PATCH 01/10] Better student user doc division --- Rewritten-docs.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/Rewritten-docs.md b/Rewritten-docs.md index eb261e8..d860f2d 100644 --- a/Rewritten-docs.md +++ b/Rewritten-docs.md @@ -1921,7 +1921,7 @@ sign. In the second column there is a list of assigned exercises with its deadlines. If you want to quickly get to the groups page you might want to use provided "Show group's detail" button. -### Join Group and Start Solving Assignments +### Join Group To be able to submit solutions you have to be a member of the right group. Each instance has its own group hierarchy, so you can choose only those within your @@ -1946,6 +1946,8 @@ the list of fellow students. If the supervisors of the group allowed students to statistic of their fellow students then there will also be the number of points each of the students has gained so far. +### Start Solving Assignments + In the "Assignments" box on the group detail page there is a list of assigned exercises which students are supposed to solve. The assignments are displayed with their names and deadlines. There are possibly two deadlines, the first one @@ -1976,6 +1978,8 @@ your browser which will be displayed in another dialog window. When the whole execution is finished then a "See the results" button will appear and you can look at the results of your solution. +### View Results of Submission + On the results detail page there are a lot of information. Apart from assignment description, which is not connected to your results, there is also the solution submitter name (supervisor can submit a solution on your behalf), further there From dc03438129c3c1799d0f11d46a91a59b89a28817 Mon Sep 17 00:00:00 2001 From: Martin Polanka Date: Thu, 26 Jan 2017 16:25:10 +0100 Subject: [PATCH 02/10] format --- Rewritten-docs.md | 39 ++++++++++++++++++++------------------- 1 file changed, 20 insertions(+), 19 deletions(-) diff --git a/Rewritten-docs.md b/Rewritten-docs.md index d860f2d..9e60638 100644 --- a/Rewritten-docs.md +++ b/Rewritten-docs.md @@ -1658,20 +1658,21 @@ for implementation of a website. There are two basic ways how to create a website these days: -- **server-side approach** - the actions of the user are processed on the server and the - HTML code with the results of the action is generated on the server and sent - back to the web browser of the user. The client does not handle any logic - (apart from rendering of the user interface and some basic user interaction) - and is therefore very simple. The server can use the API server for processing - of the actions so the business logic of the server can be very simple as well. - A disadvantage of this approach is that a lot of redundant data is transferred - across the requests although some parts of the content can be cached (e.g., - CSS files). This results in longer loading times of the website. +- **server-side approach** - the actions of the user are processed on the server + and the HTML code with the results of the action is generated on the server + and sent back to the web browser of the user. The client does not handle any + logic (apart from rendering of the user interface and some basic user + interaction) and is therefore very simple. The server can use the API server + for processing of the actions so the business logic of the server can be very + simple as well. A disadvantage of this approach is that a lot of redundant + data is transferred across the requests although some parts of the content can + be cached (e.g., CSS files). This results in longer loading times of the + website. - **server-side rendering with asynchronous updates (AJAX)** - a slightly different approach is to render the page on the server as in the previous case - but then execute the actions of the user asynchronously using the `XMLHttpRequest` - JavaScript functionality. Which creates a HTTP request and transfers only the - part of the website which will be updated. + but then execute the actions of the user asynchronously using the + `XMLHttpRequest` JavaScript functionality. Which creates a HTTP request and + transfers only the part of the website which will be updated. - **client-side approach** - the opposite approach is to transfer the communication with the API server and the rendering of the HTML completely from the server directly to the client. The client runs the code (usually @@ -1938,13 +1939,13 @@ clicking on "See group's page" link following with "Join group" link. in hierarchy and membership cannot be established by students themselves. Management of students in this type of groups is in the hands of supervisors. -On the group detail page there are multiple interesting things for you. The first -one is a brief overview containing the information describing the group, there is a list of -supervisors and also the hierarchy of the subgroups. The most important section -is the "Student's dashboard" section. This section contains the list of assignments and -the list of fellow students. If the supervisors of the group allowed students to see the -statistic of their fellow students then there will also be the number of -points each of the students has gained so far. +On the group detail page there are multiple interesting things for you. The +first one is a brief overview containing the information describing the group, +there is a list of supervisors and also the hierarchy of the subgroups. The most +important section is the "Student's dashboard" section. This section contains +the list of assignments and the list of fellow students. If the supervisors of +the group allowed students to see the statistic of their fellow students then +there will also be the number of points each of the students has gained so far. ### Start Solving Assignments From 814fba5b3e307e52ae769648216c5bd86dbd9f26 Mon Sep 17 00:00:00 2001 From: Petr Stefan Date: Thu, 26 Jan 2017 20:42:52 +0100 Subject: [PATCH 03/10] Formatting --- Rewritten-docs.md | 188 +++++++++++++++++----------------------------- 1 file changed, 69 insertions(+), 119 deletions(-) diff --git a/Rewritten-docs.md b/Rewritten-docs.md index 9e60638..dc00ebc 100644 --- a/Rewritten-docs.md +++ b/Rewritten-docs.md @@ -1,56 +1,3 @@ - - # Introduction 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 standard output") and to browse this database - _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 their students (members of their groups), including all submitted solutions - _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 particular solution as accepted (used for grading the assignment) by the supervisor -- _solution resubmission_ -- teachers should be able edit the solutions of the student - and privately resubmit them, optionally saving all results (including +- _solution resubmission_ -- teachers should be able edit the solutions of the + student and privately resubmit them, optionally saving all results (including temporary ones); this feature can be used to quickly fix obvious errors in the solution and see if it is otherwise viable - _localization_ -- all texts (UI and exercises) should be translatable @@ -310,10 +258,10 @@ addons (mostly administrative features). OAuth, should be supported - _querying SIS_ -- loading user data from the university information system should be supported -- _sandboxing_ -- there should be a safe environment in which the - solutions of the students are executed to prevent system failures due to malicious code being - submitted; the sandboxed environment should have the least possible impact on - measurement results (most importantly on measured times) +- _sandboxing_ -- there should be a safe environment in which the solutions of + the students are executed to prevent system failures due to malicious code + being submitted; the sandboxed environment should have the least possible + impact on measurement results (most importantly on measured times) - _heterogeneous worker pool_ -- there must be support for submission evaluation in multiple programming environments in a single installation to avoid 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. - _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 - software + accessible on the computers of the users without the need to install any + additional software - _performance_ -- the system must be ready for at least hundreds of students and tens of supervisors using it at once - _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 development of a web application. There are several open source options 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 -considering: +options (Backbone, Ember, Vue, Cycle.js, ...) there are two main frameworks +worth considering: - **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 @@ -2030,10 +1978,10 @@ available only for group administrators. 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 -their points. Student names are clickable with redirection to the profile of the user -where further information about his/hers assignments and solution can be found. -To quickly jump onto groups page, use "Show group's detail" button at the bottom -of the matching group box. +their points. Student names are clickable with redirection to the profile of the +user where further information about his/hers assignments and solution can be +found. To quickly jump onto groups page, use "Show group's detail" button at +the bottom of the matching group box. ### 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 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 -a note, validity status (if it is valid or revoked by superadministrator) and +multiple lines with all licences assigned to this instance. Each line consists +of a note, validity status (if it is valid or revoked by superadministrator) and the last date of licence validity. 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 -that belong to the `group_1` hardware group . Reference files are downloaded -from the default location configured in API (such as -`http://localhost:9999/exercises`) if not stated explicitly otherwise. Job +that belong to the `group_1` hardware group . Reference files are downloaded +from the default location configured in API (such as +`http://localhost:9999/exercises`) if not stated explicitly otherwise. Job execution log will not be saved to result archive. 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. - **boost-filesystem** -- Boost filesystem is used for managing logging directory (create if necessary) and parsing filesystem paths from strings as - written in the configuration of the broker. Filesystem operations will be included in - future releases of C++ standard, so this dependency may be removed in the - future. + written in the configuration of the broker. Filesystem operations will be + included in future releases of C++ standard, so this dependency may be + removed in the future. - **boost-program_options** -- Boost program options is used for 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 @@ -2689,9 +2637,9 @@ maintain backward compatibility). Fileserver stores its data in following structure: -- `./submissions//` -- folder that contains files submitted by users - (the solutions to the assignments of the student). `` is an identifier received from - the REST API. +- `./submissions//` -- folder that contains files submitted by users (the + solutions to the assignments of the student). `` is an identifier received + from the REST API. - `./submission_archives/.zip` -- ZIP archives of all submissions. These are created automatically when a submission is uploaded. `` is an identifier of the corresponding submission. @@ -2705,9 +2653,9 @@ Fileserver stores its data in following structure: ## Worker -The job of the worker is to securely execute a job according to its configuration and -upload results back for latter processing. After receiving an evaluation -request, worker has to do following: +The job of the worker is to securely execute a job according to its +configuration and upload results back for latter processing. After receiving an +evaluation request, worker has to do following: - download the archive containing submitted source files and configuration file - 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 restricted to use only a specific (evaluation) directory. -The following directory structure is used for execution. The working -directory of the worker (root of the following paths) is shared for multiple instances on the -same computer. +The following directory structure is used for execution. The working directory +of the worker (root of the following paths) is shared for multiple instances on +the same computer. - `downloads/${WORKER_ID}/${JOB_ID}` -- place to store the downloaded archive 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 at least ZIP and TAR.GZ should be available. - **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 all of the logging, both system and job logs. It is highly customizable and configurable from the configuration of the worker. - **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 manipulation with files and directories. However, these operations will be - included in future releases of C++ standard, so this dependency may be - removed in the future. + included in future releases of C++ standard, so this dependency may be removed + in the future. - **boost-program_options** -- Boost program options is used for multi-platform parsing of command line positional arguments. It is not necessary to use it, 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 of messages are missed quite often. -Messages from the queue of the client are sent through corresponding WebSocket connection -via main event loop as soon as possible. This approach with separate queue per -connection is easy to implement and guarantees reliability and order of message -delivery. +Messages from the queue of the client are sent through corresponding WebSocket +connection via main event loop as soon as possible. This approach with separate +queue per connection is easy to implement and guarantees reliability and order +of message delivery. ## Cleaner -Cleaner component is tightly bound to the worker. It manages the cache folder of the worker, -mainly deletes outdated files. Every cleaner instance maintains one +Cleaner component is tightly bound to the worker. It manages the cache folder of +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 there can be numerous instances of workers with the same cache folder, but there 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 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) -message from broker to worker must be target the socket identity of the worker (which is -saved on its **init** command). +message from broker to worker must be target the socket identity of the worker +(which is saved on its **init** command). #### Commands from Broker to Worker: @@ -3238,13 +3188,13 @@ capable to send corresponding credentials with each request. #### Worker Side -Workers comunicate with the file server in both directions -- they download -the submissions of the student and then upload evaluation results. Internally, worker is -using libcurl C library with very similar setup. In both cases it can verify -HTTPS certificate (on Linux against system cert list, on Windows against -downloaded one from CURL website during installation), support basic HTTP -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 +Workers comunicate with the file server in both directions -- they download the +submissions of the student and then upload evaluation results. Internally, +worker is using libcurl C library with very similar setup. In both cases it can +verify HTTPS certificate (on Linux against system cert list, on Windows against +downloaded one from CURL website during installation), support basic HTTP +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 available file servers in its config file. - 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. 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 -`fs.recodex.org` with SSL support, getting input file for one task could look as -GET request to +description is root of the domain of the file server. If the domain is for +example `fs.recodex.org` with SSL support, getting input file for one task could +look as GET request to `https://fs.recodex.org/tasks/8b31e12787bdae1b5766ebb8534b0adc10a1c34c`. ### Broker - Monitor Communication -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 -communication, its IP address and port are configurable in the config of the monitor -file. ZeroMQ socket ID (set on the side of the monitor) is "recodex-monitor" and must be -sent as first frame of every multipart message -- see ZeroMQ ROUTER socket -documentation for more info. +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 +communication, its IP address and port are configurable in the config of the +monitor file. ZeroMQ socket ID (set on the side of the monitor) is +"recodex-monitor" and must be sent as first frame of every multipart message -- +see ZeroMQ ROUTER socket documentation for more info. 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 @@ -3421,12 +3371,12 @@ Message format: ### Web App - Web API Communication -The provided web application runs as a JavaScript process inside the browser of the user. -It communicates with the REST API on the server through the standard 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 -returned encoded in JSON which is simply processed by the web application and -presented to the user in an appropriate way. +The provided web application runs as a JavaScript process inside the browser of +the user. It communicates with the REST API on the server through the standard +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 returned encoded in JSON which is simply processed by the web application +and presented to the user in an appropriate way.