From bcc12e0619dc44f72e14960deaae7645cfc896e5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?V=C3=ADt=20Baisa?= <xbaisa@fi.muni.cz>
Date: Mon, 3 Jun 2024 14:40:41 +0200
Subject: [PATCH] Formatting, small fixes
---
docs/.DS_Store | Bin 8196 -> 0 bytes
docs/acknowledgements.md | 7 +-
docs/authors.md | 36 +++---
docs/faq.md | 4 +-
docs/how-to-cite.md | 9 +-
docs/images/.DS_Store | Bin 6148 -> 0 bytes
docs/{img => images}/Logo_BW_inverz.png | Bin
.../inject-favicon-light-192.png | Bin
.../inject-logo--horizontal-black-1.svg | 0
docs/index.md | 39 +++---
docs/license.md | 4 +-
docs/report-bugs.md | 9 +-
docs/stylesheets/extra.css | 2 +-
docs/tech/api/overview.md | 11 +-
docs/tech/architecture/overview.md | 113 +++++++++++-------
docs/tech/installation.md | 19 ++-
docs/tech/security.md | 90 ++++++++------
docs/tech/tech_overview.md | 54 ++++-----
mkdocs.yml | 13 +-
overrides/partials/copyright.html | 4 +-
20 files changed, 242 insertions(+), 172 deletions(-)
delete mode 100644 docs/.DS_Store
delete mode 100644 docs/images/.DS_Store
rename docs/{img => images}/Logo_BW_inverz.png (100%)
rename docs/{img => images}/inject-favicon-light-192.png (100%)
rename docs/{img => images}/inject-logo--horizontal-black-1.svg (100%)
diff --git a/docs/.DS_Store b/docs/.DS_Store
deleted file mode 100644
index 4816cd657f486394e46aa424fe3e180780ec28c2..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001
literal 8196
zcmeHMPj4GV6n|rzuuf>ZY2so82n%13T1udQRD@7nrxh3^64g;jnihB09y{A?X58I%
z+z>_b83Z4I55N_1>lulU00%C70S;WDhw_`5bsPUF5{I@(ow0U)Z)e_nGxJ-|TfZ?8
zv1+gNE>V$)99#<BIaE`M>Q~o9$)qhVkinivQlCQN)S}LWwr#KsSOzQumI2FvW#Iq7
z0N&ZEIFEVnn_gR61}p>5B?BrxlyE7mq&P6BLkB9I0swPp)&;Uk2b4`I#Y&0;gXlqF
z#uR8wS(;)nV~+Mxs#i&IV9=NoOOp?lj?B^wh3V1ZzogZPRSeqNGGG~)WI%0~1@fp#
z+ayNvcTPLV<OL-Z(`m@9S}2=-D1BJKiv0yV{XiG(b{1ZG(B6WVXu3^CoeCVbnV~kU
z?o9Ka`DILZ0cQ#!e8;eeXpi28+(w;XmJ#MRb(Y!XF)uR|K-YsWPVwl9=!bvP_4{!*
zUHv`38wPQ*wDc>>WOFafyy!U2oO83jCHwWnOL}qDi#FBWnv|hGls*4i!21n%aaoGQ
z3j~j}LD1q*x$$`*TC!i2J<*D_ZQXP@`Fy_N7Wenhom)CpI(y;F!Ku>z`|m0F%=v?Z
zyi+K@^TE}|cDN(tSC~HvOG6|bG4~JauOW@BKWOfzYhphQ*YvyV4p)_*oqOrX(PQrX
z@rC)t`9h&^;^ji|mEx-ncft3X+nq?wc3Flps)jwj9yFz>2Ve5_gx^h+&~T5B>0RZm
zFCI0m?RBBE_^3hq`Y7UDY<8lcwbE|KJXt>^Z#3LvaWj%(xGLiy38dJ#5rgPj!gp$-
zEivLQNM7lxuJ{^{V&H_$`pwYudAK5~GD+mlh8IPi=<w>E(p28CkkyDQPkQWn*J}o%
zQ@;48p|V_A9SUz5!KJbh@N0T;D5c2qYeEX1FIPTITO2w`m*^9!W3Tk-Tl$W^r+f4>
z{YHP#-z>*Yus7LBc9wm}F0zkVja_G(>=yHkb!PZ<UmG2V-NyaM)7`B{B9ubyIc1a8
z-~7(#cRu?gdJgYM2U-H>cbx7{+m-C~G5w=dqtCFGE3`~&)Sxc*qC_;o?wZ(Nm;Q_G
z*z9Mq_XF)$z%!pVx7-^O{v&91bv#NCDSX7I&h$8u`)15`4tfcqj5^JX@tin5h=il;
zF}0%(vzOD+s7YI+db#^!dbqX4GVqKU$eQtsD*wOo`1Ai~JWD&gWxz7<BpG12%k|4u
zj4=FZF+P~ewM)2e;ZjBE4Gd}%R5~38>U13V@DD@CC8#Q!N{R!6XhC`E2LV&_1pEHi
L55rc^4FmrGVx*o`
diff --git a/docs/acknowledgements.md b/docs/acknowledgements.md
index 1723086..059b64e 100644
--- a/docs/acknowledgements.md
+++ b/docs/acknowledgements.md
@@ -1,8 +1,9 @@
<div class="container" markdown>
<div class="content" markdown>
-<img class="ack_logo" src="../img/Logo_BW_inverz.png">
+<img class="ack_logo" src="../images/Logo_BW_inverz.png">
<div markdown>
-This research is supported by the Open Calls for Security Research 2023–2029 (OPSEC) program granted by the Ministry of the Interior of the Czech Republic under No. [VK01030007 – Intelligent Tools for Planning, Conducting, and Evaluating Tabletop Exercises.](https://www.muni.cz/en/research/projects/69231)
+This research is supported by the Open Calls for Security Research 2023–2029 (OPSEC) program granted by the Ministry of the Interior of the Czech Republic
+under No. [VK01030007 – Intelligent Tools for Planning, Conducting, and Evaluating Tabletop Exercises](https://www.muni.cz/en/research/projects/69231).
+</div>
</div>
</div>
-</div>
\ No newline at end of file
diff --git a/docs/authors.md b/docs/authors.md
index cb8a6c0..f6e94c7 100644
--- a/docs/authors.md
+++ b/docs/authors.md
@@ -1,20 +1,20 @@
# Project contributors
-| Name | Role |
-| ------ | ------ |
-| VĂt Baisa | technical lead |
-| Jindřich Burget | frontend developer |
-| Pavel ÄŚeleda | project manager |
-| Roman Dvořák | backend developer |
-| Richard Glosner | backend developer |
-| Tomáš Hájek | exercise designer |
-| Martin Hofbauer | devops, research assistant |
-| Martin Horák | product manager |
-| Martin Juhás | backend lead developer |
-| Michal KrejÄŤĂĹ™ | exercise designer |
-| Adam Parák | full-stack developer |
-| KatarĂna Platková | frontend developer |
-| Valdemar Švábenský | researcher |
-| Michal Urban | lead developer of the first prototype |
-| Marek VeselĂ˝ | full-stack developer |
-| Jan Vykopal | pricipal investigator |
+| Name | Role |
+|--------------------|---------------------------------------|
+| VĂt Baisa | technical lead |
+| Jindřich Burget | frontend developer |
+| Pavel ÄŚeleda | project manager |
+| Roman Dvořák | backend developer |
+| Richard Glosner | backend developer |
+| Tomáš Hájek | exercise designer |
+| Martin Hofbauer | devops, research assistant |
+| Martin Horák | product manager |
+| Martin Juhás | backend lead developer |
+| Michal KrejÄŤĂĹ™ | exercise designer |
+| Adam Parák | full-stack developer |
+| KatarĂna Platková | frontend developer |
+| Valdemar Švábenský | researcher |
+| Michal Urban | lead developer of the first prototype |
+| Marek VeselĂ˝ | full-stack developer |
+| Jan Vykopal | pricipal investigator |
diff --git a/docs/faq.md b/docs/faq.md
index 0e8521f..92198aa 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -1 +1,3 @@
-TBA
\ No newline at end of file
+# Frequently Asked Questions
+
+TBA
diff --git a/docs/how-to-cite.md b/docs/how-to-cite.md
index db66804..e693f50 100644
--- a/docs/how-to-cite.md
+++ b/docs/how-to-cite.md
@@ -1,7 +1,8 @@
When referencing the INJECT Exercise Platform, please cite our paper titled:
+[From Paper to Platform: Evolution of a Novel Learning Environment for Tabletop Exercises](https://www.muni.cz/en/research/publications/2390899).
-[**From Paper to Platform: Evolution of a Novel Learning Environment for Tabletop Exercises**](https://www.muni.cz/en/research/publications/2390899)
+This paper provides insights and practical experiences derived from a cybersecurity course where
+tabletop exercises were introduced utilizing the innovative technology of the INJECT Exercise Platform (IXP).
-This paper provides insights and practical experiences derived from a cybersecurity course where tabletop exercises were introduced utilizing the innovative technology of the INJECT Exercise Platform (IXP).
-
-For a comprehensive overview of tabletop exercises, we recommend our Systematic Literature Review: ["Research and Practice of Delivering Tabletop Exercises."](https://www.muni.cz/en/research/publications/2390898)
+For a comprehensive overview of tabletop exercises, we recommend our systematic literature review:
+[Research and Practice of Delivering Tabletop Exercises](https://www.muni.cz/en/research/publications/2390898).
diff --git a/docs/images/.DS_Store b/docs/images/.DS_Store
deleted file mode 100644
index 0ace6253329615dc24cebd0020a4ddd5577fa73b..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001
literal 6148
zcmeHKJ5Iwu5S<AT1kt3V!xwNw_;eH|G6gjSEpb3mz`_UtwNF4r$uYPBx8V-v&CV#o
zHcp8mG-J)a-Pt$m>~rMt5)n_Hug63~A{xL2d)sJ!F_{-{S<fO{Kn`o%)BHRyW?5cj
zEw%^NQ2}{&o3xK>L=RMde)6aIgpaCV;pYo?+`;_-<3zbtg}!hPI=HWxe`|0LS8%@?
z+@o$Trw#7$3hw(4?j9|mz%AX-jGic_oC=!5V_YwYJ|eon+!Ql0WoV}u-F2*fiXC3+
z>gc(-0<M57uuck~W{VAW6uor?Tme^Lsers6BDi2;SSp5B2bypM0QM0MhQ53@N={^$
z7?z5dfw86nHI?m%!J3YEWW2<%RMd20JAAO+neBwa;qF*J3UuN`(OXx*6{st)p~Ion
z|FiD%e?7@Zu7E4>uN2^ZdXY}BC9AEi%}K3|;8$=l;gyQZ6m&u<23Jb)E<70Gk#vBG
TVX24+%s&Kz4Bof`f2zPYL1cEP
diff --git a/docs/img/Logo_BW_inverz.png b/docs/images/Logo_BW_inverz.png
similarity index 100%
rename from docs/img/Logo_BW_inverz.png
rename to docs/images/Logo_BW_inverz.png
diff --git a/docs/img/inject-favicon-light-192.png b/docs/images/inject-favicon-light-192.png
similarity index 100%
rename from docs/img/inject-favicon-light-192.png
rename to docs/images/inject-favicon-light-192.png
diff --git a/docs/img/inject-logo--horizontal-black-1.svg b/docs/images/inject-logo--horizontal-black-1.svg
similarity index 100%
rename from docs/img/inject-logo--horizontal-black-1.svg
rename to docs/images/inject-logo--horizontal-black-1.svg
diff --git a/docs/index.md b/docs/index.md
index 6814266..1e9d163 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,31 +1,42 @@
# INJECT Exercise Platform Documentation
-Welcome to the INJECT Exercise Platform Documentation portal! Here, you'll find comprehensive resources to guide you through every aspect of the INJECT Exercise Platform, from installation to advanced usage.
+Welcome to the INJECT Exercise Platform (IXP) Documentation!
+Here, you'll find comprehensive resources to guide you through every aspect of the IXP, from installation to advanced usage.
## Overview
-The INJECT Exercise Platform revolutionizes tabletop exercise management by providing a versatile and intuitive solution for organizations of all sizes. Whether you're a small team looking to improve emergency response protocols or a large corporation conducting complex training scenarios, INJECT Exercise Platform offers the flexibility and power to meet your needs.
+The INJECT Exercise Platform revolutionizes tabletop exercise management by
+providing a versatile and intuitive solution for organizations of all sizes.
+Whether you're a small team looking to improve emergency response protocols or
+a large corporation conducting complex training scenarios,
+IXP offers the flexibility and power to meet your needs.
## Technical Documentation
-Explore the technical documentation to gain a deeper understanding of the platform's architecture, APIs, security measures, and installation procedures.
+Explore the technical documentation to gain a deeper understanding of
+the platform's architecture, APIs, security measures, and installation procedures.
-- **[Installation Guide](tech/installation.md)**: Step-by-step instructions for deploying INJECT Exercise Platform using Docker Compose and Nginx.
-- **[Security](tech/security.md)**: Details on the security measures and practices implemented in the INJECT Exercise Platform.
-- **[API Documentation](tech/api/overview.md)**: Comprehensive documentation of the APIs provided by INJECT Exercise Platform, including RESTful APIs.
-- **[Architecture Overview](tech/architecture/overview.md)**: Detailed documentation on the architecture of the INJECT Exercise Platform, including component definitions and change logs.
+- [Installation Guide](tech/installation.md):
+ Step-by-step instructions for deploying IXP using Docker Compose and Nginx.
+- [Security](tech/security.md):
+ Details on the security measures and practices implemented in the IXP.
+- [API Documentation](tech/api/overview.md):
+ Comprehensive documentation of the APIs provided by IXP, including RESTful APIs.
+- [Architecture Overview](tech/architecture/overview.md):
+ Detailed documentation on the architecture of the IXP, including component definitions and changelogs.
## INJECT Process
-Learn about the process of conducting tabletop exercises using the INJECT Exercise Platform.
+Learn about the process of conducting tabletop exercises using the IXP.
-- **[Inject Process](INJECT_process/intro/overview.md)**: A detailed guide on how to plan, execute, and evaluate tabletop exercises using INJECT Exercise Platform.
+- [Inject Process](INJECT_process/intro/overview.md):
+ A detailed guide on how to plan, execute, and evaluate tabletop exercises using IXP.
## Additional Resources
-Access supplementary materials and information related to INJECT Exercise Platform.
+Access supplementary materials and information related to IXP.
-- **[Glossary of Terms](glossary-of-terms.md)**: Definitions of key terms and concepts used in the INJECT Exercise Platform.
-- **[Report Bugs](report-bugs.md)**: Instructions for reporting bugs, issues, or providing feedback on the INJECT Exercise Platform.
-- **[Acknowledgements](acknowledgements.md)**: Recognition of individuals or organizations that have contributed to the development or support of the INJECT Exercise Platform.
-- **[Authors](authors.md)**: Meet the team behind the development of INJECT Exercise Platform.
+- **[Glossary of Terms](glossary-of-terms.md)**: Definitions of key terms and concepts used in the IXP.
+- **[Report Bugs](report-bugs.md)**: Instructions for reporting bugs, issues, or providing feedback on the IXP.
+- **[Acknowledgements](acknowledgements.md)**: Recognition of individuals or organizations that have contributed to the development or support of the IXP.
+- **[Authors](authors.md)**: Meet the team behind the development of IXP.
diff --git a/docs/license.md b/docs/license.md
index 0e8521f..f353d64 100644
--- a/docs/license.md
+++ b/docs/license.md
@@ -1 +1,3 @@
-TBA
\ No newline at end of file
+# License
+
+TBA
diff --git a/docs/report-bugs.md b/docs/report-bugs.md
index 682184a..a2a2705 100644
--- a/docs/report-bugs.md
+++ b/docs/report-bugs.md
@@ -3,7 +3,8 @@ This guide will walk you through the steps of using Service Desk to submit your
* Open your email client and create a new email.
* Set the recipient email address to [our adress](mailto:git+inject-inject-issues-30987-issue-@gitlab.fi.muni.cz).
* In the subject line, briefly describe the nature of your inquiry (e.g., Bug Report: Application Crashes).
-* In the body of the email, provide detailed information about the issue you are experiencing. Include steps to reproduce the problem, screenshots (if applicable), and any other relevant details.
+* In the body of the email, provide detailed information about the issue you are experiencing.
+ Include steps to reproduce the problem, screenshots (if applicable), and any other relevant details.
* Once you have filled out all the necessary information, click the send button to dispatch your email to us.
Project maintainers may reach out to you to gather more information or provide updates on the status of your inquiry.
@@ -11,8 +12,10 @@ Respond to any communications from project maintainers directly through email.
**Additional Tips**
-* Be as descriptive as possible when outlining the issue in your email. Clear and detailed descriptions help project maintainers understand and address the problem more effectively.
+* Be as descriptive as possible when outlining the issue in your email.
+ Clear and detailed descriptions help project maintainers understand and address the problem more effectively.
* Include any relevant attachments, such as log files or error messages, to assist project maintainers in diagnosing the issue.
* Check your email regularly for any follow-up communications from project maintainers regarding your inquiry.
-By following these steps, you can easily report bugs or provide feedback to project maintainers. Your contributions help improve the overall quality and functionality of the project for all users.
\ No newline at end of file
+By following these steps, you can easily report bugs or provide feedback to project maintainers.
+Your contributions help improve the overall quality and functionality of the project for all users.
diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
index d7e47a1..47d804b 100644
--- a/docs/stylesheets/extra.css
+++ b/docs/stylesheets/extra.css
@@ -222,4 +222,4 @@ tr td {
max-width: 13rem !important;
height: auto !important;
margin-right: 10px;
-}
\ No newline at end of file
+}
diff --git a/docs/tech/api/overview.md b/docs/tech/api/overview.md
index d29d98f..e08e420 100644
--- a/docs/tech/api/overview.md
+++ b/docs/tech/api/overview.md
@@ -1,8 +1,13 @@
+The INJECT API is designed to facilitate communication between the frontend and backend components of the INJECT Exercise Platform (IXP).
+It enables clients to perform various operations, including data retrieval, manipulation, and real-time updates.
-The INJECT API is designed to facilitate communication between the frontend and backend components of the INJECT Exercise Platform. It enables clients to perform various operations, including data retrieval, manipulation, and real-time updates.
### GraphQL API
-The GraphQL API provides a flexible and efficient way to interact with the INJECT Exercise Platform. It allows clients to query specific data fields, reducing over-fetching. The GraphQL documentation will provide detailed information about the available queries, mutations, and subscriptions, along with examples and usage guidelines.
+The GraphQL API provides a flexible and efficient way to interact with the IXP.
+It allows clients to query specific data fields, reducing over-fetching.
+The GraphQL documentation will provide detailed information about the available queries, mutations, and subscriptions, along with examples and usage guidelines.
+
### REST API
-The REST API complements the GraphQL API by providing additional functionality and support for file transfers and other operations not supported by GraphQL. The [REST documentation](swagger-docs.md) covers endpoints, request methods, parameters, and response formats, offering comprehensive guidance for integrating with the INJECT Exercise Platform.
\ No newline at end of file
+The REST API complements the GraphQL API by providing additional functionality and support for file transfers and other operations not supported by GraphQL.
+The [REST documentation](swagger-docs.md) covers endpoints, request methods, parameters, and response formats, offering comprehensive guidance for integrating with the IXP.
diff --git a/docs/tech/architecture/overview.md b/docs/tech/architecture/overview.md
index c46eed5..bd6a19c 100644
--- a/docs/tech/architecture/overview.md
+++ b/docs/tech/architecture/overview.md
@@ -1,8 +1,9 @@
## System Overview
-The INJECT Exercise Platform is architecturally structured into two distinct components: the frontend and the backend. This separation allows for clear delineation of roles and responsibilities, enhancing modularity and scalability within the system.
+The INJECT Exercise Platform (IXP) is architecturally structured into two distinct components: the frontend and the backend.
+This separation allows for clear delineation of roles and responsibilities, enhancing modularity and scalability within the system.
-The architecture of the INJECT Exercise Platform can be visualized as follows:
+The architecture of the IXP can be visualized as follows:
``` mermaid
flowchart LR
@@ -10,7 +11,7 @@ flowchart LR
A --> C(FRONTEND)
C --> D(TRAINEE PANEL)
C --> E(INSTRUCTOR PANEL)
- C --> F(ANALITICS PANEL)
+ C --> F(ANALYTICS PANEL)
C --> J(EXERCISE PANEL)
B --> G(EXERCISES)
B --> H(EXERCISE DEFINITIONS)
@@ -18,58 +19,78 @@ flowchart LR
B --> K(AUTHENTICATION)
```
-This diagram illustrates the high-level architecture of the INJECT Exercise Platform. It is composed out of these parts:
-
-* Frontend: The frontend component serves as the user interface of the INJECT Exercise Platform, allowing users to interact with the system.
-It includes four main parts:
- * Trainee View: This view is designed for trainees participating in tabletop exercises. It provides functionalities tailored to their role, such as accessing exercise scenarios, submitting responses, and general interaction with the exercise.
- * Instructor View: This view is tailored for instructors or facilitators overseeing tabletop exercises. It offers capabilities for monitoring trainee progress, and providing guidance during the exercise.
- * Analytics: The analytics view provides insights and analytics related to the tabletop exercises conducted on the platform. It includes metrics such as participation rates, completion times, and performance trends.
+This diagram illustrates the high-level architecture of the IXP.
+It is composed out of these parts:
+
+* Frontend: The frontend component serves as the user interface of the IXP, allowing users to interact with the system.
+ It includes four main parts:
+ * Trainee View: This view is designed for trainees participating in tabletop exercises.
+ It provides functionalities tailored to their role, such as accessing exercise scenarios, submitting responses, and general interaction with the exercise.
+ * Instructor View: This view is tailored for instructors or facilitators overseeing tabletop exercises.
+ It offers capabilities for monitoring trainee progress, and providing guidance during the exercise.
+ * Analytics: The analytics view provides insights and analytics related to the tabletop exercises conducted on the platform.
+ It includes metrics such as participation rates, completion times, and performance trends.
* Exercise Panel: The exercise panel enables users to view and manage exercises available on the platform, including creating new exercises, editing existing ones, and organizing exercise-related resources.
-* Backend: The backend component serves as the backbone of the INJECT platform, handling data management, authentication, and communication with the frontend. It includes several parts:
+* Backend: The backend component serves as the backbone of the INJECT platform, handling data management, authentication, and communication with the frontend.
+ It includes several parts:
* Exercises: This module manages the creation, modification, and storage of tabletop exercises on the platform.
- * Exercise Definitions: The exercise definitions module stores templates and definitions for different types of exercises. These definitions include details such as injects, emails and tools. It also checks and ensures that definitions are correctly configured and set up. For a more in-depth explanation of definitions, please refer to [definitions architecture.](definitions.md)
+ * Exercise Definitions: The exercise definitions module stores templates and definitions for different types of exercises.
+ These definitions include details such as injects, emails and tools.
+ It also checks and ensures that definitions are correctly configured and set up.
+ For a more in-depth explanation of definitions, please refer to [definitions architecture.](definitions.md)
* Running Exercise: This module manages the execution and runtime aspects of tabletop exercises, including tracking the progress of ongoing exercises and managing the flow of injects.
* Authentication: Handles user authentication and authorization, ensuring secure access to the platform's functionalities.
## Used Technology
+
### Backend Technology
-The backend component of the INJECT Exercise Platform is built using Python and Django, a high-level web development framework. Key components of the backend architecture include:
-* Python Backend: The backend of the INJECT Exercise Platform is implemented using Python.
-* Django Framework: Django, the most popular web development framework for Python, is used to build the backend application. Django provides robust features for database management, user authentication, and more.
-* GraphQL API: The backend exposes a GraphQL API for communication with the frontend. GraphQL allows efficient data fetching and enables the client to request only the data it needs.
+The backend component of the IXP is built using Python and Django, a high-level web development framework.
+Key components of the backend architecture include:
+
+* Python Backend: The backend of the IXP is implemented using Python.
+* Django Framework: Django, the most popular web development framework for Python, is used to build the backend application.
+ Django provides robust features for database management, user authentication, and more.
+* GraphQL API: The backend exposes a GraphQL API for communication with the frontend.
+ GraphQL allows efficient data fetching and enables the client to request only the data it needs.
* Django REST Framework: For file transfers and other functionalities not supported by GraphQL, a REST API is implemented using Django REST Framework.
### Frontend Technology
-The frontend component of the INJECT Exercise Platform utilizes modern web technologies including:
-* React Frontend: The frontend application of the INJECT Exercise Platform is developed using React, library for building user interfaces.
+The frontend component of the IXP utilizes modern web technologies including:
+
+* React Frontend: The frontend application of the IXP is developed using React, library for building user interfaces.
* TypeScript: TypeScript is used instead of JavaScript to ensure type safety and improve code quality.
* React Hooks: React hooks play a crucial role in modern React programming, providing essential features such as state management and performing side effects.
* Libraries and Tools: Various libraries and tools, including Yarn, Vite, Apollo Client, and Generouted, are utilized for package management, building, data management, and routing within the frontend application.
## Security overview
+
### Authentication
-Authentication on the INJECT platform is fundamental to ensuring secure access to its features and resources. Leveraging Django's built-in session system, the platform utilizes cookies as a means to authenticate client requests.
+
+Authentication on the INJECT platform is fundamental to ensuring secure access to its features and resources.
+Leveraging Django's built-in session system, the platform utilizes cookies as a means to authenticate client requests.
### Authentication Process Overview
The authentication process involves the following steps:
-``` mermaid
+```mermaid
sequenceDiagram
Client->>Server: Get backend version
Server->>Client: Responds with backend version and SET_COOKIE
```
-```
-1. Client -> Server: Get the backend version from the REST API. (No cookies are set yet.)
-2. Client <- Server: Responds with backend version and SET_COOKIE
-with new _sessionid_ and _csrf_ cookie.
-```
-In this state, the server established a session with the client. The client did not authenticate yet, and thus the session attribute _user_ is set to _AnonymousUser_. All further requests from the client should now contain the _sessionid_ and _csrf_ cookie together with the _X-csrftoken_ header of requests (most importantly for safe login!).
-The client can now make any request to endpoints, which do not enforce authenticated requesters. On every request, the match of _csrf_ cookie and _X-csrftoken_ header is checked.
+1. Client → Server: Get the backend version from the REST API.
+ (No cookies are set yet.)
+2. Client ↠Server: Responds with backend version and `SET_COOKIE`
+ with new `sessionid` and CSRF cookie.
+
+In this state, the server established a session with the client.
+The client did not authenticate yet, and thus the session attribute _user_ is set to _AnonymousUser_.
+All further requests from the client should now contain the _sessionid_ and _csrf_ cookie together with the _X-csrftoken_ header of requests (most importantly for safe login!).
+The client can now make any request to endpoints, which do not enforce authenticated requests.
+On every request, the match of _csrf_ cookie and _X-csrftoken_ header is checked.
The next important step in our schema is **login**:
``` mermaid
@@ -77,19 +98,19 @@ sequenceDiagram
Client->>Server: Sends login request on GraphQL login endpoint
Server->>Client: Server generates new session
```
-```
-3. Client -> Server: Sends a login request on the GraphQL login endpoint
-containing the username and password (and most importantly,
-the _sesisonid_ and _csrf_ cookie with _X-csrftoken_ header set to the
-value of the _csrf_ cookie to prevent cross-site request forgery).
-4. Client <- Server: If the provided credentials were correct,
-the server generated a new session with attribute _user_ set
-to User model of user who successfully authenticated themselves and
-responded with SET_COOKIE containing the new _sessionid_ cookie
-and the new _csrf_ cookie.
-```
-The client is expected to drop the old _sessionid_ and _csrf_ cookie and replace them with the new ones. Also, every request from now on should contain _X-csrftoken_ value of the new _csrf_ cookie.
+3. Client → Server: Sends a login request on the GraphQL login endpoint
+ containing the username and password (and most importantly,
+ the _sesisonid_ and _csrf_ cookie with _X-csrftoken_ header set to the
+ value of the _csrf_ cookie to prevent cross-site request forgery).
+4. Client ↠Server: If the provided credentials were correct,
+ the server generated a new session with attribute _user_ set
+ to User model of user who successfully authenticated themselves and
+ responded with `SET_COOKIE` containing the new _sessionid_ cookie
+ and the new _csrf_ cookie.
+
+The client is expected to drop the old _sessionid_ and _csrf_ cookie and replace them with the new ones.
+Also, every request from now on should contain _X-csrftoken_ value of the new _csrf_ cookie.
For further information, refer to the official documentation on:
@@ -97,13 +118,20 @@ For further information, refer to the official documentation on:
* [CSRF Protection](https://docs.djangoproject.com/en/2.0/ref/csrf/)
### Basic authentication
-For the purposes of more convenient development, basic authentication is also supported according to the [RFC 2617](https://datatracker.ietf.org/doc/html/rfc2617#section-2) standard.
+For the purposes of more convenient development, basic authentication is also supported
+according to the [RFC 2617](https://datatracker.ietf.org/doc/html/rfc2617#section-2) standard.
+
+<!--
### Authorization
+
### Process of Authorization
-Every endpoint resolver (in REST API and GraphQL), which allows access to data that should not be visible to everyone, should be decorated by decorators. The INJECT authorization schema functions on the combinations of these decorators:
+
+Every endpoint resolver (in REST API and GraphQL), which allows access to data that should not be visible to everyone, should be decorated by decorators.
+The INJECT authorization schema functions on the combinations of these decorators:
#### protected
+
 - takes as an argument permission needed for accessing the endpoint
 - Role-based access control -> checks whether the requester is assigned to a group with the required permission
 - if request is unauthenticated, it automatically denies access
@@ -171,4 +199,5 @@ def resolver(team_id: str):
@extra_protected(Check.THREAD_ID)
def resolver(thread_id):
  pass
-```
\ No newline at end of file
+```
+-->
diff --git a/docs/tech/installation.md b/docs/tech/installation.md
index 369cc81..5738f7f 100644
--- a/docs/tech/installation.md
+++ b/docs/tech/installation.md
@@ -1,10 +1,14 @@
-# Overview
+# Installation
-The INJECT Exercise Platform comprises two main components: the frontend and the backend. This separation allows for modular development, easier maintenance, and scalability of the platform. Below, we'll walk you through the unified process of installation for frontend as well as for backend.
+The INJECT Exercise Platform (IXP) comprises two main components: the frontend and the backend.
+This separation allows for modular development, easier maintenance, and scalability of the platform.
+Below, we'll walk you through the unified process of installation for frontend as well as for backend.
-For a deeper understanding of the overall architecture of the INJECT Exercise Platform, you can refer to the [architecture overview](architecture/overview.md) in the documentation.
+For a deeper understanding of the overall architecture of the IXP,
+you can refer to the [architecture overview](architecture/overview.md) in the documentation.
## Prerequisites
+
### Hardware Requirements
Before you begin, ensure that you have the following:
@@ -14,6 +18,7 @@ Before you begin, ensure that you have the following:
* Root or sudo access to the server
These requirements ensure that the backend server can handle data processing efficiently while serving the frontend interface smoothly.
+
### Software Requirements
* Linux operating system: Debian 11 or 12 is recommended
@@ -22,8 +27,8 @@ These requirements ensure that the backend server can handle data processing eff
Make sure to install Docker and Docker Compose before proceeding with the installation.
-
-The installation files for deployment are zipped and available on GitLab. You can download them from [here](https://gitlab.fi.muni.cz/inject/inject-docs/-/raw/main/files-from-repos/deployment-files.zip?ref_type=heads&inline=false)
+The installation files for deployment are zipped and available on GitLab.
+You can download them from [here](https://gitlab.fi.muni.cz/inject/inject-docs/-/raw/main/files-from-repos/deployment-files.zip?ref_type=heads&inline=false)
These files include all necessary configuration files, scripts, and the `.env` file needed for deployment.
@@ -36,4 +41,6 @@ tags: used_in_docs
## Conclusion
-By following the installation guide, you'll be able to successfully set up and run the INJECT Exercise Platform. If you encounter any bugs or require further assistance, don't hesitate to report them to us. The [Report bugs](../report-bugs.md) includes instructions on how to report bugs.
+By following the installation guide, you'll be able to successfully set up and run the IXP.
+If you encounter any bugs or require further assistance, don't hesitate to report them to us.
+The [Report bugs](../report-bugs.md) includes instructions on how to report bugs.
diff --git a/docs/tech/security.md b/docs/tech/security.md
index 2e65e4b..9174189 100644
--- a/docs/tech/security.md
+++ b/docs/tech/security.md
@@ -1,56 +1,76 @@
# Authorization and User Management
-This section provides details on the authorization roles, user onboarding processes, and access control mechanisms implemented in the INJECT platform.
+This section provides details on the authorization roles, user onboarding processes, and access control mechanisms implemented in the INJECT Exercise Platform.
## Authorization
-For authorization processes, the RBAC (Role-based access control) is supplemented with a modified ACL (access control list)
-Three authorization roles (also called groups to not be mistaken for in-game roles) are present:
+For authorization processes, the RBAC (Role-based access control) is supplemented with a modified ACL (access control list).
-- **ADMIN**
+Three authorization roles (also called groups, not to be mistaken for in-game roles) are present:
- - has implicit access to all resources and the platform (exercises, definitions, users, etc...)
- - role should be assigned only to people that really need it (maintainers, deployers of the platform), and the number of people with this role should be kept to a minimum
- - can execute every action that a TRAINEE or INSTRUCTOR can
+**ADMIN**
-- **INSTRUCTOR**
+- has access to all resources and the platform (exercises, definitions, users, etc...)
+- role should be assigned only to people that really need it (maintainers, deployers of the platform), and the number of people with this role should be kept to a minimum
+- can execute every action that a TRAINEE or INSTRUCTOR can
- - can access only exercises and definitions where he/she was assigned (or which he/she has created and was not removed from them)
- - isntructors can add or remove other instructors from exercises or definitions if they have access to these resources
- - by creating an exercise or uploading an exercise definition, the instructor is automatically granted access to it - access can be removed by the other instructor assigned to the exercise or definition
- - instructor of the given exercise can see all teams in the exercise
- - can manipulate with the exercises (start, stop, create, or remove)
- - can add/remove trainees to/from teams of an exercise
- - inherits all trainee permissions
+**INSTRUCTOR**
-- **TRAINEE**
+- can access only exercises and definitions where he/she was assigned (or which he/she has created and was not removed from them)
+- instructors can add or remove other instructors from exercises or definitions if they have access to these resources
+- by creating an exercise or uploading an exercise definition, the instructor is automatically granted access to it –
+ access can be removed by the other instructor assigned to the exercise or definition
+- instructor of the given exercise can see all teams in the exercise
+- can manipulate with the exercises (start, stop, create, or remove)
+- can add/remove trainees to/from teams of an exercise
+- inherits all trainee permissions
- - can see only exercises where he/she was assigned
- - can access only the data of the team to which he or she was assigned (cannot see the data of other teams for the same exercise)
- - can use tools in exercise (sending emails, using tools,...)
+**TRAINEE**
+
+- can see only exercises to which he/she was assigned
+- can access only the data of the team to which he or she was assigned
+ (cannot see the data of other teams for the same exercise)
+- can use tools in exercise (sending emails, using tools,...)
### Additional notes
-- Users with the ADMIN role can be added to the access control lists to be shown in exercises (if the admin acts as an instructor for some reason), but it is not necessary because ADMIN has control over every resource on the platform, whether he is assigned to it or not
+
+Users with the ADMIN role can be added to the access control lists to be shown in exercises
+(if the admin acts as an instructor for some reason),
+but it is not necessary because ADMIN has control over every resource on the platform, whether he is assigned to it or not.
## User onboarding
-Users can be added to the platform via a .csv file in the following format:
+
+Users can be added to the platform via a `.csv` file in the following format:
+
```
username,group,tags,first_name,last_name
```
-- **username** (mandatory)
- - has to be a valid email address of the user (user will receive credentials via this email)
-- **group** (optional, implicitly "trainee")
- - authorization role of the created user
- - values: trainee, instructor, or admin (shorts "t", "i" or "a" can be used as well) case is ignored
-Instructors cannot create users with higher privileges. admin (admin can be created only by admin users)
-- **tags** (optional)
- - you can mark the newly created user by tags to make your work with assigning users to teams or exercises more convenient
- - format of the field: `tag1|tag2|tag3` (values separated by "|")
-- **first_name** (optional)
- - first name of the created user if you want to identify them later
-- **last_name** (optional)
- - last name of the created user if you want to identify them later
+**username** (mandatory)
+
+- has to be a valid email address of the user (user will receive credentials via this email)
+
+**group** (optional, implicitly "trainee")
+
+- authorization role of the created user
+- values: trainee, instructor, or admin (shorts "t", "i" or "a" can be used as well) case is ignored
+
+Instructors cannot create users with higher privileges.
+Admin can be created only by admin users.
+
+**tags** (optional)
+
+- you can mark the newly created user by tags to make your work with assigning users to teams or exercises more convenient
+- format of the field: `tag1|tag2|tag3` (values separated by "|")
+
+**first_name** (optional)
+
+- first name of the created user if you want to identify them later
+
+**last_name** (optional)
+
+- last name of the created user if you want to identify them later
As a separator for the column, you can use either `,` or `;`.
-An example of such a file can be downloaded [here](https://gitlab.fi.muni.cz/inject/inject-docs/-/raw/main/docs/tech/example_csv.csv?ref_type=heads&inline=false)
\ No newline at end of file
+
+An example of such a file can be [downloaded](https://gitlab.fi.muni.cz/inject/inject-docs/-/raw/main/docs/tech/example_csv.csv?ref_type=heads&inline=false).
diff --git a/docs/tech/tech_overview.md b/docs/tech/tech_overview.md
index 157780c..0a0ba07 100644
--- a/docs/tech/tech_overview.md
+++ b/docs/tech/tech_overview.md
@@ -1,51 +1,47 @@
-# Technical Overview
+# Technical documentation – Overview
-Welcome to the technical documentation for the INJECT Exercise Platform. This section provides comprehensive information and resources for understanding, installing, and maintaining the INJECT Exercise Platform. Each part of the documentation is designed to help developers, system administrators, and other stakeholders effectively utilize the platform.
+This section provides comprehensive information and resources for understanding, installing, and maintaining the INJECT Exercise Platform (IXP).
+Each part of this section is designed to help developers, system administrators, and other stakeholders effectively utilize the platform.
## Contents
### 1. Installation Guide
+
- **[Installation Guide](installation.md)**:
- This guide provides detailed, step-by-step instructions for deploying the INJECT Exercise Platform using Docker Compose and Nginx. It covers prerequisites, environment variables configuration, HTTPS deployment, creating a superuser, and troubleshooting tips. Following this guide ensures a smooth and error-free installation process, helping you to get the platform up and running quickly.
+ This guide provides detailed, step-by-step instructions for deploying the IXP using Docker Compose and Nginx.
+ It covers prerequisites, environment variables configuration, HTTPS deployment, creating a superuser, and troubleshooting tips.
### 2. Authentication and Authorization
+
- **[Authentication and Authorization](security.md)**:
- This section outlines the authentication and authorization mechanisms implemented in the INJECT Exercise Platform. It includes detailed descriptions of the authentication processes, such as how users are authenticated using Django's session system with cookies, and authorization mechanisms, detailing the role-based access control (RBAC) and access control lists (ACL) used to manage user permissions. By understanding and following the guidelines, you can protect your data and ensure that only authorized users have access to sensitive information.
+ This section outlines the authentication and authorization mechanisms implemented in the IXP.
+ It includes detailed descriptions of the authentication processes, such as
+ how users are authenticated using Django's session system with cookies, and
+ authorization mechanisms, detailing the role-based access control (RBAC) and access control lists (ACL) used to manage user permissions.
+ By understanding and following the guidelines, you can protect your data and ensure that only authorized users have access to sensitive information.
### 3. API Documentation
+
- **[API Overview](api/overview.md)**:
- This document provides an overview of the APIs available in the INJECT Exercise Platform, explaining the purpose and usage of each API. It sets the stage for more detailed documentation found in the subsequent files.
+ This document provides an overview of the APIs available in the IXP, explaining the purpose and usage of each API.
+ It sets the stage for more detailed documentation found in the subsequent files.
- **[Swagger Documentation](api/swagger-docs.md)**:
Detailed documentation generated from the OpenAPI specification, providing a user-friendly interface to explore and test the API endpoints.
### 4. Architecture
+
- **[Architecture Overview](architecture/overview.md)**:
- This document gives a high-level view of the architecture of the INJECT Exercise Platform, describing the main components, their interactions, and the overall system design. It includes diagrams and explanations to help you understand how the platform is structured and how the different parts work together.
+ This document gives a high-level overview of the architecture of the IXP,
+ describing the main components, their interactions, and the overall system design.
+ It includes diagrams and explanations to help you understand how the platform is structured and how the different parts work together.
- **[Definitions](architecture/definitions.md)**:
- A detailed description of the key components and concepts within the INJECT Exercise Platform. This section serves as a glossary, helping you understand specific terms and their meanings in the context of the platform.
+ A detailed description of the key components and concepts within the IXP.
+ This section serves as a glossary, helping you understand specific terms and their meanings in the context of the platform.
- **[Changelog](architecture/CHANGELOG.md)**:
- A log of all the changes, updates, and improvements made to the platform over time. This document is crucial for keeping track of the platform's evolution and understanding the history of updates and bug fixes.
+ A log of all the changes, updates, and improvements made to the platform over time.
+ This document is crucial for keeping track of the platform's evolution and understanding the history of updates and bug fixes.
## Getting Started
-To begin your journey with the INJECT Exercise Platform, we recommend starting with the [Installation Guide](installation.md). This guide will help you set up the platform using Docker Compose and Nginx, ensuring that all components are correctly configured and running smoothly.
-
-### Installation Guide
-
-The installation guide covers everything from setting up prerequisites, such as ensuring your system meets the hardware requirements, to configuring environment variables and deploying the platform using Docker Compose. It also provides troubleshooting tips to resolve common issues you might encounter during the setup process.
-
-### Authentication and Authorization
-
-In the [Authentication and Authorization](security.md) section, you will find detailed information about the security architecture of the INJECT Exercise Platform. This includes authentication processes, such as how users are authenticated using Django's session system with cookies, and authorization mechanisms, detailing the role-based access control (RBAC) and access control lists (ACL) used to manage user permissions.
-
-### API Documentation
-
-For developers looking to integrate their applications with INJECT Exercise Platform, the [API Overview](api/overview.md) is an excellent starting point. This section provides an introduction to the available APIs, followed by in-depth documentation for both GraphQL and RESTful APIs. The GraphQL documentation includes detailed descriptions of queries and mutations, while the OpenAPI and Swagger documentation provide a comprehensive look at the RESTful endpoints, complete with examples and testing capabilities.
-
-### Architecture
-
-Understanding the architecture of the INJECT Exercise Platform is crucial for both developers and system administrators. The [Architecture Overview](architecture/overview.md) provides a high-level look at the system, supported by detailed definitions of key components and a changelog that tracks the evolution of the platform. This section is essential for anyone looking to gain a deep understanding of how INJECT Exercise Platform is designed and how its components interact.
-
-## Conclusion
-
-This technical overview serves as a navigation hub for the INJECT Exercise Platform's technical documentation. Each section is designed to provide you with the information you need to effectively use, secure, and integrate the platform. For further details and specific instructions, please refer to the respective documentation linked above.
\ No newline at end of file
+To begin your journey with the IXP, we recommend starting with the [Installation Guide](installation.md).
+This guide will help you set up the platform using Docker Compose and Nginx, ensuring that all components are correctly configured and running smoothly.
diff --git a/mkdocs.yml b/mkdocs.yml
index ad29d61..83c4411 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,21 +1,18 @@
site_name: INJECT Exercise Platform
theme:
name: material
- favicon: 'img/inject-favicon-light-192.png'
- logo: 'img/inject-logo--horizontal-black-1.svg'
+ favicon: 'images/inject-favicon-light-192.png'
+ logo: 'images/inject-logo--horizontal-black-1.svg'
custom_dir: overrides/
-
extra:
social:
- icon: inject/inject-logo--horizontal-black
link: https://inject.muni.cz
-
copyright: Copyright © 2024 Masaryk University
-
nav:
- Home: index.md
- Technical documentation:
- - Technical Overview: tech/tech_overview.md
+ - Overview: tech/tech_overview.md
- Installation: tech/installation.md
- System architecture:
- Overview: tech/architecture/overview.md
@@ -46,7 +43,6 @@ nav:
- Acknowledgements: acknowledgements.md
- How to cite: how-to-cite.md
# - License: license.md
-
markdown_extensions:
- attr_list
- md_in_html
@@ -64,11 +60,8 @@ markdown_extensions:
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format
-
-
extra_css:
- stylesheets/extra.css
-
plugins:
- render_swagger
- include-markdown
diff --git a/overrides/partials/copyright.html b/overrides/partials/copyright.html
index b124641..b45c408 100644
--- a/overrides/partials/copyright.html
+++ b/overrides/partials/copyright.html
@@ -11,5 +11,5 @@
</a>
{% endif %}
<br>
- <a href="/inject-docs/report-bugs/">Report bugs</a>
- </div>
\ No newline at end of file
+ <a href="/inject-docs/report-bugs/">Report bugs</a>
+</div>
--
GitLab