Docker is software which runs another software
inside a container: an independent, executable package of software.
When a software, like web server, Sphinx, or A+, runs inside a container,
it thinks it has a computer of its own. The container has all the files
that the software requires, like some particular directory structure and
particular versions of some software libraries. When a container is built
for a software, it will always run the similar way regardless of what kind
of hardware and software is outside the container.
Docker versus virtual machines
A technical remark: Docker is not a typical virtual machine or emulator,
which creates a whole imaginary computer inside another physical computer.
Different Docker containers running on the same computer utilise the hardware
operating system kernel (the software which controls the other software
resources, like memory, disk and processor time efficiently. They share the
same and shares those resources by their request).
The Docker home page also has a short explanation of containers.
The reasons for using Docker in A+ are the following:
If you have an existing course in A+ which does not use Docker, see the chapter
</converting/virtualenv_to_docker>`_ for reasons to convert it to
File format: YAML
YAML is a human-friendly language for defining data
for computer programs. In Docker and A+ it is used for writing
configuration files, that is, files which control the behaviour of
A+ and some types of exercises. The file suffix is .yml or
.yaml. For a short introduction to the grammar of YAML, see
part “Preview” of the YAML specification” .
This A+ manual itself will not describe the basics of Docker. This is
because most of the time the person who is writing or updating a course
for A+ actually just needs to install Docker, Docker Compose and
execute the ./docker-compile.sh and ./docker-up.sh commands.
To actually learn Docker, begin with the “Get started” tutorial at Docker
It is good to know a little what happens inside your computer when you
develop a course. This is required if you plan to include your course
exercises that are more than simple quizzes.
The image above shows the software architecture of A+. The course directory
on your computer has RST files. When you run docker-compile.sh, it
requests Docker to run a container called compile-rst. Inside that
container is a minimal Debian GNU/Linux operating system, Python programming language interpreter,
Sphinx and Python libraries for producing YAML files. The container
is allowed to access the a-plus-rst-tools directory which contain
essential Sphinx directives for producing right kind of HTML and YAML
files for A+. Sphinx runs inside the container and writes its results
to the directory _build in the course directory.
Next, when you start A+ with docker-up.sh, two containers are started.
The container run-aplus-front is similar to the compile-rst container,
but it contains the A+ software - the one you can access at
Another container that docker-up.sh starts is run-mooc-grader.
It runs the typical work pair of A+, the mooc-grader.
This container is allowed to read the HTML and YAML
files at the _build directory. It is good to know that those files
specify the actual structure and contents of the course.
The share of work between A+ and mooc-grader is the following. A+ is
a front-end, the component that students see. It knows who is
logged in, which students are taking which course, which students
have answered to some exercises and how many points they got. A+ does
all the bookkeeping.
Meanwhile, mooc-grader receives exercise files from
students. For each submit, it starts a Python grader in the container
grading-python. Inside that container the student’s program is
actually run and unit tests executed. The results of the unit tests
are passed to mooc-grader which passes them to A+. Then A+ shows
the score and feedback to the student.
This means that exercise solutions that students have submitted will not remain
on mooc-grader after grading; instead, they are stored in A+. Mooc-grader
also hosts the so-called static content: HTML files and images
which do not change - the ones in the course _build directory.
Mooc-grader also reads exercise configurations from the course directory.
Each exercise has its own directory named exercises/exercisename/,
which contains typically the following files:
The grading-python container has other Python libraries, like
A+ Python grader utils.
In the top of the architecture image, there is the Aalto Gitlab
service at https://version.aalto.fi , where your work will be copied
by the command git push. Moreover, some courses use a
which automatically copies the course material to the A+ production
server, when the author pushes the material to version.aalto.fi at some
predefined git branch, like “publish”. At least course
CS-A1141 Tietorakenteet ja algoritmit Y uses this technique.
If you author a course which includes programming exercises, it is nice
to know that there are already many containers for grading programming
exercises in different languages. The source code and documentation for
these containers exists the A-plus LMS Github directory . For example, there is support for
automatic testing and grading for Clingo, Java, MiniZinc, Scala, and
even Python-based web applications with Selenium. These container images
are of course available at Docker hub, meaning that Docker will
automatically download them if you define in the course configuration
files that you will need them. If your course needs software which is
not yet available as containers for A+, see the
A-plus LMS Github page for