more details

Author: PatWie

docs/content/guides/overview.md

@@ -99,10 +99,15 @@ The backend acts as a Restful JSON web server and is written in [Go](https://gol
 - It uses [Redis](https://redis.io/) as a light-weight key-value memory store.
 - [Docker](https://www.docker.com/) is used as a light-weight sandbox to run auto-tests of  solutions to programming assignments in an isolated environment.
 
-Part of the backend are **workers**, which are separate processes that handle the auto-testing of uploads. These worker *can* be distributed across multiple machines. We recommend using one worker process for 100 students. The workers can be added or removed at any time.
-
 Each exercise task can be linked to a docker-image and a zip file containing the test code to support testing. See the Administrator Guide for more details.
 
+## Workers
+
+Part of the backend are **workers**, which are separate processes that handle the auto-testing of uploads. These worker *can* be distributed across multiple machines.
+We recommend using one worker process for 100 students. The workers can be added or removed at any time. Infomark uses AMPQ as a message broker. Each submission will be held in a queue and each worker will execute one job concurrently to avoid too much system load. Our recommendation is one worker per available CPU core.
+
+The used amount of memory per submission can be configured. Memory-swapping is deactivated.
+
 ## Console
 
 To avoid manual interaction with the database InfoMark provides a console to run several commands like enrolling a student into a course/group, set the role of a user.
@@ -141,4 +146,12 @@ using [Swagger](https://swagger.io/).
 
 # Development
 
-This system was developed in the [computer graphics groups](https://uni-tuebingen.de/en/faculties/faculty-of-science/departments/computer-science/lehrstuehle/computergrafik/computer-graphics/) of the University of Tübingen because there are no comparable systems that meet our requirements.
+This system was developed in the [computer graphics groups](https://uni-tuebingen.de/en/faculties/faculty-of-science/departments/computer-science/lehrstuehle/computergrafik/computer-graphics/) of the University of Tübingen because there are no comparable systems that meet our requirements.
+
+# Requirements
+
+InfoMark has the following minimal requirements:
+- one core for server `infomark serve`  (1GB RAM)
+- one core for each backgound worker `infomark work` (depending on your docker-image size for the programming assignments)
+
+You might want to sp

docs/content/guides/tutor.md

@@ -7,6 +7,24 @@ layout: subpage
 
 # Unit - Tests
 
+Unit-tests consists of
+- a submission `<STUDENT_UPLOAD.ZIP>` made by a student
+- a testing framework `<TASK_SEPCIFIC_TEST.ZIP>` written by one of the tutors/instructors
+- a docker-image name `<YOUR_DOCKER_IMAGE>`
+
+Each infomark-worker will fetch a submission from a queue and execute a command which is equal to
+
+```bash
+docker run --rm -it --net="none" \
+  -v <STUDENT_UPLOAD.ZIP>:/data/submission.zip:ro \
+  -v <TASK_SEPCIFIC_TEST.ZIP>:/data/unittest.zip:ro  \
+  <YOUR_DOCKER_IMAGE>
+```
+
+and capture the output which is store in the database and displayed the student resp. the tutor who grades the solution.
+
+## Overview
+
 There are some ways to ease the task of writing unit-tests.
 A clear directory structure and a Makefile to automatically pack all necessary archives or/and run the unit-test locally can dramatically speed up the entire process and avoid debugging steps on the server.
 The *makefile* should be able to clean temporary files, zip files and simulate the test result locally using the correct docker-image.
@@ -297,6 +315,22 @@ FAILED (failures=1)
 ## C++
 
 Testing in C++ is a bit tricky, doing reflections is difficult. A basic example is provided in out [git-repository](https://github.com/cgtuebingen/infomark/tree/master/unittests/cpp).
+The final directory structure *inside* the docker container will be
+
+```
+/src
+  lib/             # from the upload/student_template
+    divide.cpp     # from the upload/student_template
+    divide.hpp     # from the upload/student_template
+  hello.cpp        # from the upload/student_template
+  hello_test.cpp   # from the test
+  catch.hpp        # from the test
+  CMakeLists.txt   # from the test
+  run.sh           # from the test
+```
+
+Any file from the testing-zip will override a file from the uploaded submission if such a file exists. Further, we automatically remove any "*.sh" from the submission file in our Docker-setup.
+
 Any submission consists of a main file
 
 ```cpp