diff --git a/.idea/.gitignore b/.idea/.gitignore new file mode 100644 index 0000000000000000000000000000000000000000..b58b603fea78041071d125a30db58d79b3d49217 --- /dev/null +++ b/.idea/.gitignore @@ -0,0 +1,5 @@ +# Default ignored files +/shelf/ +/workspace.xml +# Editor-based HTTP Client requests +/httpRequests/ diff --git a/.idea/DojoDoc.iml b/.idea/DojoDoc.iml new file mode 100644 index 0000000000000000000000000000000000000000..24643cc37449b4bde54411a80b8ed61258225e34 --- /dev/null +++ b/.idea/DojoDoc.iml @@ -0,0 +1,12 @@ +<?xml version="1.0" encoding="UTF-8"?> +<module type="WEB_MODULE" version="4"> + <component name="NewModuleRootManager"> + <content url="file://$MODULE_DIR$"> + <excludeFolder url="file://$MODULE_DIR$/.tmp" /> + <excludeFolder url="file://$MODULE_DIR$/temp" /> + <excludeFolder url="file://$MODULE_DIR$/tmp" /> + </content> + <orderEntry type="inheritedJdk" /> + <orderEntry type="sourceFolder" forTests="false" /> + </component> +</module> \ No newline at end of file diff --git a/.idea/inspectionProfiles/Project_Default.xml b/.idea/inspectionProfiles/Project_Default.xml new file mode 100644 index 0000000000000000000000000000000000000000..7c4836fbe3272512cf6cfae977f3a8b260550e47 --- /dev/null +++ b/.idea/inspectionProfiles/Project_Default.xml @@ -0,0 +1,7 @@ +<component name="InspectionProjectProfileManager"> + <profile version="1.0"> + <option name="myName" value="Project Default" /> + <inspection_tool class="Eslint" enabled="true" level="WARNING" enabled_by_default="true" /> + <inspection_tool class="Stylelint" enabled="true" level="ERROR" enabled_by_default="true" /> + </profile> +</component> \ No newline at end of file diff --git a/.idea/material_theme_project_new.xml b/.idea/material_theme_project_new.xml new file mode 100644 index 0000000000000000000000000000000000000000..9bdfa3108397a36a6eab8df0940c232f9cfc4458 --- /dev/null +++ b/.idea/material_theme_project_new.xml @@ -0,0 +1,17 @@ +<?xml version="1.0" encoding="UTF-8"?> +<project version="4"> + <component name="MaterialThemeProjectNewConfig"> + <option name="metadata"> + <MTProjectMetadataState> + <option name="migrated" value="true" /> + <option name="pristineConfig" value="false" /> + <option name="userId" value="104e8585:19002424fea:-7ffe" /> + </MTProjectMetadataState> + </option> + <option name="titleBarState"> + <MTProjectTitleBarConfigState> + <option name="overrideColor" value="false" /> + </MTProjectTitleBarConfigState> + </option> + </component> +</project> \ No newline at end of file diff --git a/.idea/modules.xml b/.idea/modules.xml new file mode 100644 index 0000000000000000000000000000000000000000..5995a29d92afa71b19bd0002b1624926ff6616cc --- /dev/null +++ b/.idea/modules.xml @@ -0,0 +1,8 @@ +<?xml version="1.0" encoding="UTF-8"?> +<project version="4"> + <component name="ProjectModuleManager"> + <modules> + <module fileurl="file://$PROJECT_DIR$/.idea/DojoDoc.iml" filepath="$PROJECT_DIR$/.idea/DojoDoc.iml" /> + </modules> + </component> +</project> \ No newline at end of file diff --git a/.idea/vcs.xml b/.idea/vcs.xml new file mode 100644 index 0000000000000000000000000000000000000000..e5a35fdf1d3b3bbc1cbdbd6cdeae8d43181254a2 --- /dev/null +++ b/.idea/vcs.xml @@ -0,0 +1,7 @@ +<?xml version="1.0" encoding="UTF-8"?> +<project version="4"> + <component name="VcsDirectoryMappings"> + <mapping directory="" vcs="Git" /> + <mapping directory="$PROJECT_DIR$/ZolaApp/install" vcs="Git" /> + </component> +</project> \ No newline at end of file diff --git a/ZolaApp/content/dev-doc/deploy/1001_introduction.md b/ZolaApp/content/dev-doc/deploy/1001_introduction.md new file mode 100644 index 0000000000000000000000000000000000000000..ac480e3d8618b9a528466c5055bdc0fd2f26dc27 --- /dev/null +++ b/ZolaApp/content/dev-doc/deploy/1001_introduction.md @@ -0,0 +1,24 @@ ++++ +title = "Introduction" +description = "Install / Create your own instance." +slug = "install" +weight = 1001 +template = "docs/page.html" + +[extra] +toc = false +top = false ++++ + +In the following sections, you will find the instructions to install and update your own instance of the Dojo. + +As you can read in the [introduction](/dev-doc/introduction) section, The Dojo is composed of several components that +need or don't need to be adapted or installed on your side: + +- **The Dojo CLI:** a command-line interface to interact with the Dojo platform. *This part doesn't require any + adaptation because the client chooses the instance to interact with.* +- **The Dojo Backend:** a RESTful API. *This part have to be installed on your side.* +- **The Dojo Pipelines:** a set of Docker images used in CI/CD environments. *These repos have to be created on your + side.* + - **AssignmentChecker:** a Docker image to check the assignments. + - **ExerciseChecker:** a Docker image to check the exercises. diff --git a/ZolaApp/content/dev-doc/deploy/1002_compatibility.md b/ZolaApp/content/dev-doc/deploy/1002_compatibility.md new file mode 100644 index 0000000000000000000000000000000000000000..eb6ef4ba30c8ce9f674a0f7251248a96a9a3e066 --- /dev/null +++ b/ZolaApp/content/dev-doc/deploy/1002_compatibility.md @@ -0,0 +1,16 @@ ++++ +title = "Compatibility" +description = "Compatibility of the different parts of The Dojo projects." +slug = "compatibility" +weight = 1002 +template = "docs/page.html" + +[extra] +toc = false +top = false ++++ + +This section will be updated at each release (except debug) of the Dojo to ensure the compatibility of the different +parts of the project. + +Actually, only the latest version (v5.0) of The Dojo is supported for a deployment outside of HEPIA infrastructure. \ No newline at end of file diff --git a/ZolaApp/content/dev-doc/deploy/1003_requirements.md b/ZolaApp/content/dev-doc/deploy/1003_requirements.md new file mode 100644 index 0000000000000000000000000000000000000000..b60e8074f6611ed96b21d73a626f75b2672e9366 --- /dev/null +++ b/ZolaApp/content/dev-doc/deploy/1003_requirements.md @@ -0,0 +1,75 @@ ++++ +title = "Requirements" +description = "Requirements to install / create your own instance." +slug = "requirements" +weight = 1003 +template = "docs/page.html" + +[extra] +toc = true +top = false ++++ + +You can find on this page the requirements to install / create your own instance of The Dojo. + + +## Requirements changes + +There is actually no change from the original requirements to install The Dojo. + + +## Gitlab + +The Dojo uses Gitlab to manage the projects. Gitlab must have the following characteristics: + +- Version 17.4 or higher with API version 4. +- A Gitlab account + - No project limit - All Dojo projects (assignments and exercises) are created under this account. +- Runners: At least one runner (on x64 architecture) is required to run the pipelines. It must have the following + characteristics: + - *Executor*: `Docker` + - *Image*: `ubuntu:latest` + - *Privileged*: `Yes` + - *Tags*: + - `dojo_assignment` + - `dojo_exercise` +- The following group tree must be created from The Dojo gitlab account: + - `Dojo`: Runners must be registered in this group (or be global runners) + - `Assignment` + - `Deleted` + - `Exercise` + - `Deleted` + - `Template` + - `Deleted` + +## The Dojo Backend + +The Dojo backend is Docker-based. Here are the **minimum** requirements of the server (may vary depending on the number +of users and the load): + +- *CPU*: 2 cores +- *Architecture*: x64 +- *RAM*: 4 GB +- *Disk*: 32 GB +- *OS*: Ubuntu 22.04 LTS (tested on this platform but other Linux distributions should work) + - *Docker*: 26.1 or higher + - *Docker Compose*: 2.27 or higher + - *Git*: 2.34 or higher + +## The Dojo Pipelines + +A **Docker Hub** account is required to generate and store The Dojo pipelines images. It can be a free account as we +don't use private repositories. + +Two public repositories must be created: + +- `dojo_assignment_checker` +- `dojo_exercise_checker` + +The computer that generates the images can be x64 or amd64 (the resulting images are built for x64) and must have the +following tools installed: + +- *Docker*: 26.1 or higher +- *Git*: 2.34 or higher +- *jq* +- *sed* \ No newline at end of file diff --git a/ZolaApp/content/dev-doc/deploy/1004_install-update.md b/ZolaApp/content/dev-doc/deploy/1004_install-update.md new file mode 100644 index 0000000000000000000000000000000000000000..15d7b4d5ba50bcd94ea71f918c01efb0b5cf6559 --- /dev/null +++ b/ZolaApp/content/dev-doc/deploy/1004_install-update.md @@ -0,0 +1,141 @@ ++++ +title = "Install / Update" +description = "Install / Update your instance." +slug = "install-update" +weight = 1004 +template = "docs/page.html" + +[extra] +toc = true +top = false ++++ + +This page will guide you through the installation and update of your own instance of the Dojo. + + +## Recommendations + +- Remember to check the [compatibility](/dev-doc/deploy/compatibility) and [requirements](/dev-doc/deploy/requirements) + updates if you do an update. +- The Dojo backend needs a config file (.env). Remember to back it up before updating. +- For better security, we recommend to use a reverse proxy with SSL/TLS that will redirect the requests to the backend + container. + +## Backend + +### Gitlab configuration (only need at the first installation) + +#### Gitlab Application + +The Dojo use the Gitlab API to authenticate users and get their information. To do so, you need to create a Gitlab +application in the `Dojo` base group. Here is the configuration information: + +- *Name*: `The Dojo CLI` +- *Redirect URI*: `http://localhost:30992/login` +- *Confidential*: `No` +- *Scopes*: + - `api` + - `create_runner` + - `read_repository` + - `write_repository` + +Once the application is created, you will get a `Client ID` and a `Client Secret`. Save them for later usage. + +#### Gitlab Token + +You need a token to interact with the Gitlab API. To do so, you need to create a token in the gitlab account with the +`api` scope. Save it for later usage. + +**WARNING:** This token has an expiration date. You need to renew it before it expires and update the backend with the +new one. + + +### Install + +To install the backend, you need to clone the repository and run the Docker Compose file. Here are the steps to follow: + +1. Clone the repository: + ```bash + git clone --recurse-submodule https://gitedu.hesge.ch/dojo_project/projects/backend/dojobackend + cd dojobackend + ``` +1. Copy the `.env.example` file to `.env` and fill it with the necessary informations: + ```bash + cp .env.example .env + nano .env + ``` +1. Run the Docker Compose file: + ```bash + ./infra --run + ``` + +### Update + +Pull (with recurse submodules) the new version of the backend and restart containers with the same command from the +installation. + + +### The Dojo access management + +To modify access right of a Dojo user, you have to do it manually in the database (you can access to a adminer interface +at the URL: `<BACKEND_URL>/dojo/adminer/` or do it via mysql command on the server): + +1. The user must log in at least once to the Dojo platform to be created in the database. +1. You have to find the user ID. For it, you can ask for his Gitlab ID or search it in the `User` table. +1. Here is the SQL command to change the access right of a user: + ```sql + UPDATE `User` SET + `role` = <ROLE_ID> + WHERE `id` = '<USER_ID>'; + ``` + Here are the roles id list: + - 1: Student + - 2: Teacher + - 3: Admin + +## Pipelines images generation (Docker Hub) + +### AssignmentChecker / ExerciseChecker + +The two checkers have similar steps to generate the images. Here are the steps to follow: + +1. Clone the repository: + - AssignmentChecker: + ```bash + git clone --recurse-submodule https://gitedu.hesge.ch/dojo_project/projects/pipelines/dojoassignmentchecker + cd dojoassignmentchecker + ``` + - ExerciseChecker: + ```bash + git clone --recurse-submodule https://gitedu.hesge.ch/dojo_project/projects/pipelines/dojoexercisechecker + cd dojoexercisechecker + ``` +1. Run the build and publish script. There is two options: + +- **Interactive:** Run the script with no values and follow the instructions: + ```bash + ./deploy_on_dockerhub.sh + ``` +- **Inline command:** Run the script with the values (all forgotten value will be asked during the process): + ```bash + ./deploy_on_dockerhub.sh --dockerhub-user <DOCKERHUB_USER> --dockerhub-password <DOCKERHUB_PASSWORD> + --dockerhub-repo <DOCKERHUB_REPO> --backend-url <BACKEND_URL> + ``` + +### Update + +Pull (with recurse submodules) the new version of the checkers and redo the build step. + + +## DojoClI + +As said in the [introduction](/dev-doc/deploy/introduction), the Dojo CLI doesn't need any adaptation because the user +has to choose the instance to interact with or to specify the backend URL on the first launch of the CLI. + +This can be changed with the command `dojo settings api` or by editing the `state_v1.json5` file in the +`.DojoCLI` directory in the user's home directory (for Linux users). + +### Add your instance in the preconfigured list of the CLI + +If you want to add your instance in the preconfigured list of the CLI, you can do it by contacting The Dojo team +(see on the [help page](/user-doc/help/faq/#contact-the-project)). \ No newline at end of file diff --git a/ZolaApp/content/dev-doc/deploy/_index.md b/ZolaApp/content/dev-doc/deploy/_index.md new file mode 100644 index 0000000000000000000000000000000000000000..183a592e36a8694c5e307203c79c0ebef7f389f0 --- /dev/null +++ b/ZolaApp/content/dev-doc/deploy/_index.md @@ -0,0 +1,9 @@ ++++ +title = "Deploy / Update" +description = "Deploy / Update your own instance." +template = "docs/section.html" +sort_by = "weight" +weight = 1000 +draft = false ++++ + \ No newline at end of file