Skip to content
Snippets Groups Projects
Commit d37f34fb authored by michael.minelli's avatar michael.minelli
Browse files

Merge branch 'add_wiki_doc' into v2.1.0

parents 217eae33 e6ad3784
Branches
Tags
No related merge requests found
Pipeline #26518 canceled
Stage: test
Show whitespace changes
Inline Side-by-side
Showing
with 858 additions and 1 deletion
.gitignore
+ 1
− 0
View file @ d37f34fb
aws.xml aws.xml
workspace.xml workspace.xml
.gitlab-ci-local .gitlab-ci-local
Wiki/.idea
############################ MacOS ############################ MacOS
# General # General
......
Wiki/0-Dojo-presentation.md 0 → 100644
+ 37
− 0
View file @ d37f34fb
# Dojo: a platform to practice programming
The dojo platform is an online tool built to help practice programming by
allowing users to propose assignments and perform them as exercises.
The tool is very flexible and allows for proposing exercises for any language
and does not impose any limitation on a framework to be heavily relying
on Docker and Gitlab. These tools used in combination allow for automatic
correction of assignments in order to give immediate feedback to users
performing exercises. Solved exercises can then be shared among the community
of users such that they can inspire other users or give hints on ways to solve
a given exercise.
The two major concepts of the platform are the **assignments** and the **exercises**.
The principal way to interact with the Dojo platform is currently the `dojo` CLI.
## The assignment
An assignment is written by a user that wants to propose an exercise. It is typically composed of a written description of the work to be performed,
and tests that must be passed once the exercise is successfully performed (and some configuration files for the infrastructure of the tests
such as docker files). At its core, an assignment is
nothing else than a git repository that can be forked in the form of an exercise and modified using standard git commands.
For a more detailed description please see the [CLI documentation](home).
An assignment can be proposed by any user.
In the future a dependency tree of assignments can be created, as well as tagging for filtering purposes.
## The exercise
An exercise is an instance of an assignment which the learner will modify in order to make it pass the automatic tests.
It can be run locally on any user's machine using the dojo CLI. When the exercise is completed
it is pushed on the dojo where the CI/CD tools of Gitlab can evaluate it automatically and
notify the dojo platform of the result. The exercises can then be shared with other users
in order to propose a wide variety of solutions and can be a base for discussion among users
and with teachers.
For a more detailed description please see the [CLI documentation](home).
\ No newline at end of file
Wiki/Home.md deleted 100644 → 0
+ 0
− 1
View file @ 217eae33
# Wiki of the CLI of Dojo
\ No newline at end of file
Wiki/Tutorials/0-Exercise-perform.md 0 → 100644
+ 154
− 0
View file @ d37f34fb
# How to perform an exercise
In this tutorial we quickly explain the workflow for performing an exercise by a student (or a professor).
The exercise is based on the `c_hello_world` assignment created in [assignment creation](1-Assignment-creation) tutorial.
## Exercise "creation"
To perform an exercise the student must first create the exercise. Under the hood, this operation consist in making
a fork of a published assignment in the student's namespace.
This is performed by the following `dojo` command:
```bash
$ dojo exercise create --assignment c_hello_world
```
```console
Please wait while we verify and retrieve data...
ℹ Checking Dojo session:
✔ The session is valid
✔ Student permissions
ℹ Checking Gitlab token:
✔ Read access
✔ Write access
ℹ Checking assignment:
✔ Assignment "c_hello_world" exists
✔ Assignment "c_hello_world" is published
Please wait while we are creating the exercise...
✔ Exercise successfully created
ℹ Id: 8d3f53a0-0d32-4455-a251-e1a1c5a97c6a
ℹ Name: DojoEx - c_hello_world - orestis.malaspin - 1
ℹ Web URL: https://gitedu.hesge.ch/dojo/exercise/dojo-ex_c_hello_world_8d3f53a0-0d32-4455-a251-e1a1c5a97c6a
ℹ HTTP Repo: https://gitedu.hesge.ch/dojo/exercise/dojo-ex_c_hello_world_8d3f53a0-0d32-4455-a251-e1a1c5a97c6a.git
ℹ SSH Repo: ssh://git@ssh.hesge.ch:10572/dojo/exercise/dojo-ex_c_hello_world_8d3f53a0-0d32-4455-a251-e1a1c5a97c6a.git
```
## To perform the exercise
The exercise is nothing else than a git repository so the workflow is pretty straightforward.
1. Clone the repository (see the repo link above)
```bash
$ git clone ssh://git@ssh.hesge.ch:10572/dojo/exercise/dojo-ex_c_hello_world_8d3f53a0-0d32-4455-a251-e1a1c5a97c6a.git
```
```console
Cloning into 'dojo-ex_c_hello_world_8d3f53a0-0d32-4455-a251-e1a1c5a97c6a'...
remote: Enumerating objects: 33, done.
remote: Counting objects: 100% (33/33), done.
remote: Compressing objects: 100% (26/26), done.
remote: Total 33 (delta 6), reused 16 (delta 3), pack-reused 0
Receiving objects: 100% (33/33), 7.32 KiB | 7.32 MiB/s, done.
Resolving deltas: 100% (6/6), done.
```
2. Read the `README.md` file to understand what is expected by the teacher.
3. Modify/create the appropriate code.
4. (Optional but recommended) Execute the pipeline locally
```bash
$ dojo exercise run
```
```console
Please wait while we are checking and creating dependencies...
ℹ Checking exercise content:
✔ The exercise folder contains all the needed files
✔ The dojo_assignment.json file is valid
✔ The Docker deamon is running
Please wait while we are running the exercise...
✔ Docker Compose file run successfully
✔ Linked services logs acquired
✔ Containers stopped and removed
Please wait while we are checking the results...
✔ Results file found
✔ Results file is valid
✔ Results folder size is in bounds
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Results ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ┃
┃ Global result : ❌ Failure ┃
┃ ┃
┃ Execution exit code : 0 ┃
┃ ┃
┃ Execution results folder : /home/student/DojoExecutions/dojo_execLogs_2023-08-30T18_58_05_764Z ┃
┃ ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
```
Currently the exercise is a failure which is sad but expected since there was no modification in any file.
One can see that we have access to a `results` folder in `/home/student/DojoExecutions/dojo_execLogs_2023-08-30T18_58_05_764Z`.
This directory contains the output of the pipeline execution
```console
/home/student/DojoExecutions/dojo_execLogs_2023-08-30T18_58_05_764Z
├── Dojo
│ ├── dockerComposeLogs.txt
│ └── results.json
└── Exercise
└── diff_output.txt
2 directories, 3 files
```
In particular one can find the output the teacher wanted us (students) to see in the `Exercise` folder.
It contains any output file that can be used for debugging for example. In this case it contains
```console
< ./hello_world
< (null)
\ No newline at end of file
---
> Hello world!
\ No newline at end of file
```
One can see that there is an `Hello world!` expected and that no `Hello world!` was provided by our program.
One can also see the complete
logs of the `docker compose` command in `Dojo/dockerComposeLogs.txt` which may (or may not)
provide additional informations.
In order to complete this assignment we have to modify the `src/function.c` file such that it becomes
```c
#include "function.h"
char *hello_world()
{
return "Hello world!";
}
```
Rerunning the pipeline now yields
```bash
$ dojo exercise run
```
```console
Please wait while we are checking and creating dependencies...
ℹ Checking exercise content:
✔ The exercise folder contains all the needed files
✔ The dojo_assignment.json file is valid
✔ The Docker deamon is running
Please wait while we are running the exercise...
✔ Docker Compose file run successfully
✔ Linked services logs acquired
✔ Containers stopped and removed
Please wait while we are checking the results...
✔ Results file found
✔ Results file is valid
✔ Results folder size is in bounds
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Results ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ┃
┃ Global result : ✅ Success ┃
┃ ┃
┃ Execution exit code : 0 ┃
┃ ┃
┃ Execution results folder : /home/student/DojoExecutions/dojo_execLogs_2023-08-30T19_20_25_104Z ┃
┃ ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
```
5. Now that we are happy with the state of our exercise, we can commit and push our modifications and
the exercise will be run through the Gitlab CI pipeline and one can see the "official" result
of our exercise.
![The Gitlab CI pipeline succeeded!](pipeline.png)
It is not necessary to have a successful pipeline to commit and push the code. We can do it at any time
which is particularly useful when doing long assignments that take many iterations to finish.
Wiki/Tutorials/1-Assignment-creation.md 0 → 100644
+ 414
− 0
View file @ d37f34fb
# How to create an assignment
We will describe how to create a very simple assignment with dojo.
Here we will build a `Hello world!` in the C programming language. We will describe how one must
modify the default template to have an exercise.
The exercise will be to fill a function to return the `Hello world!` string.
The output of the function will be printed on the standard output.
The structure will be provided to the students as well as a very simple `Makefile`
to compile and run the code.
The success or failure of this assignment will be tested by comparing the output
of our program with an the expected output (the famous `Hello world!`).
To build this exercise we need to perform several steps that will be described below in great details.
## Empty assignment creation
First create a new assignment with the command
```bash
$ dojo assignment create --name c_hello_world
```
```console
Please wait while we verify and retrieve data...
ℹ Checking Dojo session:
✔ The session is valid
✔ Teaching staff permissions
ℹ Checking Gitlab token:
✔ Read access
✔ Write access
✔ Assignment name "c_hello_world" is available
Please wait while we are creating the assignment...
✔ Assignment successfully created
ℹ Name: c_hello_world
ℹ Web URL: https://gitedu.hesge.ch/dojo/assignment/c_hello_world
ℹ HTTP Repo: https://gitedu.hesge.ch/dojo/assignment/c_hello_world.git
ℹ SSH Repo: ssh://git@ssh.hesge.ch:10572/dojo/assignment/c_hello_world.git
```
## Clone the assignment locally
The assignment is nothing more than a git repository. We just clone it and start
modifying it
```bash
$ git clone ssh://git@ssh.hesge.ch:10572/dojo/assignment/c_hello_world.git
```
```console
Cloning into 'c_hello_world'...
remote: Enumerating objects: 18, done.
remote: Counting objects: 100% (18/18), done.
remote: Compressing objects: 100% (12/12), done.
remote: Total 18 (delta 3), reused 18 (delta 3), pack-reused 0
Receiving objects: 100% (18/18), 4.37 KiB | 4.37 MiB/s, done.
Resolving deltas: 100% (3/3), done.
```
The `c_hello_world` assignment has now the following structure
```bash
$ tree c_hello_world/
```
```console
c_hello_world/
├── docker-compose.yml
├── Dockerfile
├── dojo.assignment
└── README.md
```
## Build the development environment
In order to execute a C program we need a working compiler and `make`. In order to
produce a special result file to be parsed by the `dojo` tool to produce nicely formatted output
we will use `jq`, a command-line json creation/edition/reding tool. Our `Dockerfile`
contains
```dockerfile
FROM ubuntu:latest
RUN apt update && apt install gcc make jq -y
COPY . /
ENTRYPOINT ["./run.sh"]
```
We see that we start by installing the required packages on top of the latest Ubuntu image.
We then proceed to copy the complete assignment into the docker container, finall we run
a yet to be created `run.sh` script.
We can test our `Dockerfile` by running the command
```bash
$ docker compose run --build hello_world
```
```console
[+] Building 20.5s (8/8) FINISHED
=> [hello_world internal] load build definition from Dockerfile
=> => transferring dockerfile: 134B
=> [hello_world internal] load .dockerignore
=> => transferring context: 2B
=> [hello_world internal] load metadata for docker.io/library/ubuntu:latest
=> CACHED [hello_world 1/3] FROM docker.io/library/ubuntu:latest@sha256:ec050c32e4a6085b423d36ecd025c0d3ff00c38ab93a3d71a460ff1c44fa6d77
=> [hello_world internal] load build context
=> => transferring context: 39.87kB
=> [hello_world 2/3] RUN apt update && apt install gcc make jq -y
=> [hello_world 3/3] COPY . /
=> [hello_world] exporting to image
=> => exporting layers
=> => writing image sha256:4b561113c7123da08206a2cf2642cb4f331670fe44350646437eaa78e44aff3a
=> => naming to docker.io/library/c_hello_world-hello_world
ERRO[0021] error waiting for container:
Error response from daemon: failed to create task for container: failed to create shim task: OCI runtime create failed: runc create failed: unable to start container process: exec: "./run.sh": stat ./run.sh: no such file or directory: unknown
```
We see an error at the end of the command which is perfectly normal. We did not create the `run.sh` file et (let's leave that for later).
We then need to focus on the `docker-compose.yml` file which will take care of all the hard work
needed if complex workflows are required. Here it is as simple as possible and should contain
```yml
services:
hello_world:
container_name: hello_world
build:
context: ./
dockerfile: Dockerfile
volumes:
- hello_world_volume:/result # <hello_world_volume> must be the same as below but
# the name may be arbitrary. This volume must be
# present in the dojo_assignment.json file under the field
# "result": {
# "volume": "hello_world_volume",
# ...
# }
volumes:
hello_world_volume:
```
In this file, we see the definition of a `hello_world_volume` this is an arbitrary name and can be changed but it
must be coherent in this file and in the `dojo_assignment.json` file (more on this later configuration file in [The dojo configuration file](#the-dojo-configuration-file)).
This volume is responsible of mounting `/result/` directory which will contain all
the output generated by our assignment (again the name can be changed). In particular
in this director e will be required to create a `dojo_assignment.json` file
that contains at least if the assignment was successfully performed (more on that at the end of the [Creating the assignment files](#creating-the-assignment-files) section).
## The dojo configuration file
The `dojo_assignment.json` file contains the general configuration of the assignment.
The important configuration parameters are:
- the *immutable files* which are files that will be overwritten when the compilation pipeline is run (even if the student
modifies these files the modifications will not be taken into account),
- the *results* which is the volume corresponding to the `docker-compose.yml` file.
In its default form `dojo_assignment.json` file contains
```json
{
"dojoAssignmentVersion": 1,
"version": 1,
"immutable": [
{
"description": "Dockerfile of the unique container",
"path": "Dockerfile",
"isDirectory": false
}
],
"result": {
"container": "hello_world",
"volume": "hello_world_volume"
}
}
```
Here we see only one immutable file which is the `Dockerfile` (the `isDirectory` field is `false` but it is possible to make
complete directories immutable) and we see that:
* the value of the `container` field (`hello_world`) corresponds to
the value of the `container_name` field in the `docker-compose.yml` file,
* the value of the `volume` field (`hello_world_volume`) corresponds to the `volumes` field in the `docker-compose.yml` file.
This file will be completed in [The immutable files](#the-immutable-files) sectino with the files of our assignment that will be
created in the [next section](#creating-the-assignment-files).
## Creating the assignment files
For this assignment we will create the following files with the following content:
- `src/Makefile`
```makefile
CC:=gcc
CFLAGS:=-Wall -Wextra -Wpedantic -fsanitize=address -Werror -g
LDFLAGS:=-fsanitize=address
hello_world: hello_world.o function.o
gcc -o $@ $^ $(LDFLAGS)
hello_world.o: function.h
function.o: function.h
run: hello_world
./hello_world
clean:
rm -f *.o hello_world
```
- `src/hello_world.c`
```c
#include <stdio.h>
#include <stdlib.h>
#include "function.h"
int main()
{
printf("%s", hello_world());
return EXIT_SUCCESS;
}
```
- `src/function.h`
```c
#ifndef _FUNCTION_H_
#define _FUNCTION_H_
char *hello_world();
#endif
```
- `src/function.c`
```c
#include "function.h"
char *hello_world()
{
// TODO: Replace 0 here to return "Hello world!"
return 0;
}
```
- `src/expected_output.txt`
```
Hello world!
```
These files will be used to create an executable that will be run by the custom execution script, `run.sh`, see the `Dockerfile` in
the [Build the environment](#build-the-development-environment) section.
All these files have arbitrary names and it's completely up to the teacher to make a coherent exercise.
The only missing file is `run.sh` (do not forget to make it executable, `chmod +x run.sh`) that contains the following code
```bash
#!/bin/bash
echo "Starting tests."
GLOBAL_SUCCESS=false
make -C src clean -s
make -C src -s
if [ $? -eq 0 ]; then
make run -C src > src/output.txt -s
if [ $? -eq 0 ]; then
diff --color src/output.txt src/expected_output.txt > result/diff_output.txt
if [ $? -ne 0 ]; then
echo "Output is wrong:";
cat result/diff_output.txt
else
echo "All tests were a complete success"
GLOBAL_SUCCESS=true
fi
else
echo "Execution failed";
fi
else
echo "Compilation failed."
fi
jq --null-input --arg success $GLOBAL_SUCCESS \
'{"success": $success | test("true")}' > /result/results.json
```
Here one can see the creation of two different files that are located in the `result` directory:
- `result/results.json`
- `result/diff_output.txt`
The `results.json` is mandatory to be created and must at least contain the
`success` field must be `true` or `false` and determines whether the
assignment is a success or a failure. The other files present in the `result` folder
can be retrieved by the students.
To test if everything works according to plan, one can again use the command
```bash
$ docker compose run --build hello_world
```
```console
[+] Building 1.8s (8/8) FINISHED
=> [hello_world internal] load build definition from Dockerfile
=> => transferring dockerfile: 134B
=> [hello_world internal] load .dockerignore
=> => transferring context: 2B
=> [hello_world internal] load metadata for docker.io/library/ubuntu:latest
=> [hello_world 1/3] FROM docker.io/library/ubuntu:latest@sha256:ec050c32e4a6085b423d36ecd025c0d3ff00c38ab93
=> [hello_world internal] load build context
=> => transferring context: 3.23kB
=> CACHED [hello_world 2/3] RUN apt update && apt install gcc make jq -y
=> [hello_world 3/3] COPY . /
=> [hello_world] exporting to image
=> => exporting layers
=> => writing image sha256:5499aa3aa0b2f2021584dbf46b4b05ab83dc0a5ad4d6c81a3466c56673c3f562
=> => naming to docker.io/library/c_hello_world-hello_world
Starting tests.
Output is wrong:
1c1
< (null)
\ No newline at end of file
---
> Hello world!
\ No newline at end of file
```
where we see that the execution fails. This will be improved in the future and the actual execution as expected to be
run by the students will be added.
## The immutable files
There is only one file that should be modified by the students in this example: the `function.c` file. Therefore we can safely
add all the created files in the `src` except `src/function.c` which is precisely
the file that the student must modify, as well as the `run.sh` file. The `dojo_assignment.json` file becomes
```json
{
"dojoAssignmentVersion": 1,
"version": 1,
"immutable": [
{
"description": "Dockerfile of the unique container",
"path": "Dockerfile",
"isDirectory": false
},
{
"description": "The entry point of the Dockerfile",
"path": "run.sh",
"isDirectory": false
},
{
"description": "The makefile for compilation/execution purposes",
"path": "src/Makefile",
"isDirectory": false
},
{
"description": "Entry point of the code",
"path": "src/hello_world.c",
"isDirectory": false
},
{
"description": "The header file fot the program's assignment",
"path": "src/function.h",
"isDirectory": false
},
{
"description": "The expected output file for comparing with the actual output",
"path": "src/expected_output.txt",
"isDirectory": false
}
],
"result": {
"container": "hello_world",
"volume": "hello_world_volume"
}
}
```
## The `README.md` file
The `README.md` file is used to provide informations on the assignment and the way the teacher wants students to accomplish
the assignment and its content is completely free. It is recommended to use the `Markdown` syntax as the
file extension suggests.
In this assignment the `README.md` file reads
```markdown
# Hello world!
C'est le premier vrai exercice jamais créé sur le Dojo!
Il sert de tutoriel pour créer un exercice simple en C.
## But
Le but est de faire afficher "Hello world!" à notre programme en C.
Pour ce faire, il faut modifier le fichier `src/function.c` sous la ligne
annotée avec `TODO`. Bonne chance!
```
## Publish the work
Now that the assignment is ready, we must publish it. First add/commit/push all the
files needed for your exercise. In this case, it should be:
```console
c_hello_world/
├── docker-compose.yml
├── Dockerfile
├── dojo_assignment.json
├── README.md
├── run.sh
└── src
├── expected_output.txt
├── function.c
├── function.h
├── hello_world.c
└── Makefile
```
Then one must *publish* the assignment for the students to be able to perform to get the exercise.
```bash
$ dojo assignment publish c_hello_world
```
```console
? Are you sure you want to publish this assignment? Yes
Please wait while we verify and retrieve data...
ℹ Checking Dojo session:
✔ The session is valid
ℹ Checking assignment:
ℹ c_hello_world
✔ The assignment exists
✔ You are in the staff of this assignment
Please wait while we publish the assignment...
✔ Assignment c_hello_world successfully published
```
The assignment is now ready to be performed by students!
Wiki/UserDocumentation/0-Installation.md 0 → 100644
+ 38
− 0
View file @ d37f34fb
# Installation of the Dojo CLI
1. Download the latest stable version (without "-dev" suffix) from the releases: <https://gitedu.hesge.ch/dojo_project/projects/ui/dojocli/-/releases>
![releases](../figures/releases.png)
1. Download the executable corresponding to your OS and architecture.
- ℹ️ For these OS you can use specific packaged release that install the binary at the right place (so you can ignore the next point).
- **Debian / Ubuntu** : You can use the `deb` package named `Debian / Ubuntu (YOUR_ARCH) package`.
- **macOS**: You can use the `pkg` version named `macOS (YOUR_ARCH) package`.
2. Put it in your path. For
- For exemple:
- ℹ️ **Linux**: `$HOME/.local/bin`
- ℹ️ **macOS**: `/usr/local/bin`
3. Verify your installation is working correctly by calling the `dojo` CLI.
```bash
dojo
```
```console
Usage: dojo [options] [command]
CLI of the Dojo application
Options:
-h, --help display help for command
-H, --host <string> override the Dojo API endpoint (default: "https://rdps.hesge.ch/dojo/api")
-V, --version output the version number
Commands:
assignment manage an assignment
exercise manage an exercise
help [command] display help for command
session manage Dojo and Gitlab sessions
```
As you can see calling the `dojo` command shows the help menu.
\ No newline at end of file
Wiki/UserDocumentation/1-Authentification.md 0 → 100644
+ 49
− 0
View file @ d37f34fb
# Authentication to the Dojo
The authentication is done in two steps: login into the dojo app and into https://gitedu.hesge.ch (through an API token).
1. Login into the dojo application:
```bash
dojo session application login --user <email>
```
```console
? Please enter your password [hidden]
Please wait while we are logging in you to Dojo...
✔ Logged in
✔ Teaching staff permissions
✔ Student permissions
```
2. Register the API token (see below) for Gitlab
```bash
dojo session gitlab login <token>
```
```console
Please wait while we are testing your Gitlab token...
ℹ Checking Gitlab token:
✔ Read access
✔ Write access
```
The API token can be created by (see <https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html> for more informations):
- Logging into <https://gitedu.hesge.ch>
- **Preferences -> Access Tokens**
- Give a name to your token and a validity
- Tick the **api** box
- Click the **Create personal access token**
3. Test if it is working
```bash
dojo session test
```
```console
ℹ Checking Dojo session:
✔ The session is valid
✔ Teaching staff permissions
✔ Student permissions
ℹ Checking Gitlab token:
✔ Read access
✔ Write access
```
Good news. You can use the Dojo!
Wiki/UserDocumentation/2-Assignment-creation.md 0 → 100644
+ 66
− 0
View file @ d37f34fb
# Assignment creation
The assignment is created by a member of the teaching staff and is the basis for students to perform their exercise.
1. To create an assignment
```bash
dojo assignment create --name <unique_name>
```
```console
Please wait while we verify and retrieve data...
ℹ Checking Dojo session:
✔ The session is valid
✔ Teaching staff permissions
ℹ Checking Gitlab token:
✔ Read access
✔ Write access
✔ Assignment name "unique_name" is available
Please wait while we are creating the assignment...
✔ Assignment successfully created
ℹ Name: unique_name
ℹ Web URL: https://gitedu.hesge.ch/dojo/assignment/unique_name
ℹ HTTP Repo: https://gitedu.hesge.ch/dojo/assignment/unique_name.git
ℹ SSH Repo: ssh://git@ssh.hesge.ch:10572/dojo/assignment/unique_name.git
```
where `<unique_name>` is the name of the assignment. By default only the creator of the exercise is added to
the assignment (which is just a git repository with some configuration files in it).
There are several other options that can be provided:
```bash
dojo assignment create --name <unique_name> --template <url>
```
where `<url>` is the url of the template repository one may want to use as a basis for the assignment-
```bash
dojo assignment create --name <unique_name> --members_username <usernames>
```
where `<usernames>` is a list of gitedu usernames that will be given the same permissions as the
user creating the assignment.
As usual one can show the help menu by typing
```bash
dojo assignment create --help
```
Or you may just enter (`--help` is implicit in most commands)
```bash
dojo assignment create
```
2. Clone the repository of the assignment that was just created:
```bash
git clone ssh://git@ssh.hesge.ch:10572/dojo/assignment/unique_name.git
```
3. Modify the `unique_name` assignment as you want (modify the Dockerfile, docker-compose.yml files, add a readme, source code, compilation tools, etc.). Commit and push our work (soon™ more details will be provided on how to create assignment).
4. Once the assignment is done it must be published to be available to students:
```bash
dojo assignment publish unique_name
```
```console
? Are you sure you want to publish this assignment? Yes
Please wait while we verify and retrieve data...
ℹ Checking Dojo session:
✔ The session is valid
ℹ Checking assignment:
ℹ unique_name
✔ The assignment exists
✔ You are in the staff of this assignment
Please wait while we publish the assignment...
✔ Assignment unique_name successfully published
```
\ No newline at end of file
Wiki/UserDocumentation/3-Exercise-creation.md 0 → 100644
+ 74
− 0
View file @ d37f34fb
# Exercise creation
The exercise is an instance of a **published assignment** to be performed by students (or group of students).
1. Create an exercise
```bash
dojo exercise create --assignment unique_name
```
```console
Please wait while we verify and retrieve data...
ℹ Checking Dojo session:
✔ The session is valid
✔ Student permissions
ℹ Checking Gitlab token:
✔ Read access
✔ Write access
ℹ Checking assignment:
✔ Assignment "unique_name" exists
✔ Assignment "unique_name" is published
Please wait while we are creating the exercise...
✔ Exercise successfully created
ℹ Id: some-long-hash
ℹ Name: DojoEx - unique_name - your.name
ℹ Web URL: https://gitedu.hesge.ch/dojo/exercise/dojo-ex_unique_name_some-long-hash
ℹ HTTP Repo: https://gitedu.hesge.ch/dojo/exercise/dojo-ex_unique_name_some-long-hash.git
ℹ SSH Repo: ssh://git@ssh.hesge.ch:10572/dojo/exercise/dojo-ex_unique_name_some-long-hash.git
```
**Tips**: You cas use the --members_username or --members_id options to add other students of the group to the exercise.
2. Make changes and try solving the exercise.
3. The complete tests can be run with the following command.
```bash
dojo exercise run
```
```console
Please wait while we are checking and creating dependencies...
ℹ Checking exercise content:
✔ The exercise folder contains all the needed files
✔ The dojo_assignment.json file is valid
✔ The Docker deamon is running
Please wait while we are running the exercise...
✔ Docker Compose file run successfully
✔ Linked services logs acquired
✔ Containers stopped and removed
Please wait while we are checking the results...
✔ Results file found
✔ Results file is valid
✔ Results folder size is in bounds
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Results ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ┃
┃ Global result : ✅ Success ┃
┃ ┃
┃ Execution exit code : 0 ┃
┃ ┃
┃ Tests passed : 3 ┃
┃ Tests failed : 1 ┃
┃ ┃
┃ Tests : ┃
┃ - ✅ ListeOrdonnee ┃
┃ - ✅ ListeVide ┃
┃ - ✅ ListeOrdreInverse ┃
┃ - ❌ ListeRandom ┃
┃ ┃
┃ Execution results folder : /home/username/DojoExecutions/dojo_execLogs_2023-08-21T21_33_38_684Z ┃
┃ ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
```
This command runs the exercise in the current directory or in the path provided by the `--path` option.
4. Once confident enough in the solution, one can commit/push the solution.
This triggers the CI/CD pipeline on gitedu. In the CI/CD all immutable files are overwritten and
the docker-compose is executed (only logs from the current container are given) then other logs
are retrieved from the other images that may be used. The error code of the docker container is retrieved.
Wiki/figures/releases.png 0 → 100644
+ 0
− 0
View file @ d37f34fb
Wiki/figures/releases.png

522 KiB

Wiki/home.md 0 → 100644
+ 25
− 0
View file @ d37f34fb
# Documentation of the `dojo` CLI utility
In this wiki you will find the documentation related to the `dojo` CLI.
## Dojo Project
The dojo platform is an online tool built to help practice programming by allowing users to propose assignments and perform them as exercises.
The two major concepts of the platform are the **assignments** (provided by teaching staff) and the **exercises** (performed by students).
More details here : [Dojo detailed presentation](0-Dojo-presentation)
## User documentation
* [Installation of the CLI](UserDocumentation/0-Installation)
* [Authentification](UserDocumentation/1-Authentification)
* [Assignment creation](UserDocumentation/2-Assignment-creation)
* [Exercice creation](UserDocumentation/3-Exercise-creation)
## Tutorials / Exemples
### Students / Everyone
* [How to perform an exercise](Tutorials/0-Exercise-perform)
### Teaching staff
* [How to create and publish an assignment](Tutorials/1-Assignment-creation)
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment