diff --git a/Wiki/CLI-user-documentation.md b/Wiki/CLI-user-documentation.md new file mode 100644 index 0000000000000000000000000000000000000000..42a87c86d9bdde1f86edd17bfc658f58523b809f --- /dev/null +++ b/Wiki/CLI-user-documentation.md @@ -0,0 +1,230 @@ +# How to use the dojo CLI (version 2.0) + +There are four different parts covered in this chapter: +- [Installation](#installation) +- [Authentication](#authentication) +- [Create an assignment](#create-an-assignment) +- [Create an exercise](#create-an-exercise) + +## Installation + +1. Download the latest stable version (without "-dev" suffix) from the releases: <https://gitedu.hesge.ch/dojo_project/projects/ui/dojocli/-/releases> + + + +2. Download the executable corresponding to your OS and architecture. + - ℹ️ For macOS users you can use the pkg version that install the binary at the right place (so you can ignore the next point). +3. Put it in your path. For + - ℹ️ Linux user this may be `$HOME/.local/bin` for example. +4. 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. + +## Authentication + +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! + +## Create an assignment + +The assignment is created by a teacher typically 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 +``` + +## Create an exercise + +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 +``` +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. + diff --git a/Wiki/Home.md b/Wiki/Home.md deleted file mode 100644 index ec072aec5347c5ca75c7fe301cb07585dc56fad6..0000000000000000000000000000000000000000 --- a/Wiki/Home.md +++ /dev/null @@ -1 +0,0 @@ -# Wiki of the CLI of Dojo \ No newline at end of file diff --git a/Wiki/figures/releases.png b/Wiki/figures/releases.png new file mode 100644 index 0000000000000000000000000000000000000000..8950a930ee305be9aeb50317502a57d90ce2d853 Binary files /dev/null and b/Wiki/figures/releases.png differ diff --git a/Wiki/home.md b/Wiki/home.md new file mode 100644 index 0000000000000000000000000000000000000000..e85c2a412f02b1f94f36ae630225567f82b9a575 --- /dev/null +++ b/Wiki/home.md @@ -0,0 +1,6 @@ +# Documentation of the `dojo` cli utility + +In this wiki you will find the documentation related to the `dojo` CLI. + +* [User documentation](CLI-user-documentation) +* [Developer documentation](cli_dev_doc) \ No newline at end of file