Add docs on development mode

Pipfile

@@ -18,6 +18,7 @@ uwsgi = "*"
 psycopg2-binary = "*"
 django-prometheus = "*"
 sentry-sdk = "*"
+debugpy = "*"
 
 [dev-packages]
 pylint = "*"

README.md

@@ -4,18 +4,56 @@ The VMChecker API is built on [Django](https://www.djangoproject.com/). The proj
 
 ## Requirements
 
-1. `python3 >= 3.8`
+1. `python3 >= 3.10`
 2. `pipenv` (`pip3 install pipenv --user`. See [docs](https://pipenv.pypa.io/en/latest/installation.html))
 3. `docker` (See official docker [docs](https://docs.docker.com/engine/install/))
-4. A Moodle installation with the vmchecker plugin installed. See the vmchecker-next [docs](https://github.com/open-education-hub/vmchecker-next/blob/master/CONTRIBUTING.md#requirements) on how to set up a development environment. If you do not plan on working on the Moodle plugin, follow the following workshop tutorial on setting up a Moodle instance with the vmchecker plugin installed ([Tutorial](https://open-education-hub.github.io/docs/events/vmchecker-workshop/vmchecker-moodle-install)).
-5. Create a test assignment on [Gitlab.com](https://gitlab.com/) by following the [TA handbook](https://github.com/open-education-hub/vmchecker-next/wiki/Teaching-Assistant-Handbook). You will only require the private git repository. You can directly fork the following [template assignment](https://gitlab.cs.pub.ro/vmchecker/vmchecker-next-assignment).
+4. Create a test assignment on [Gitlab.com](https://gitlab.com/) by following the [TA handbook](https://github.com/open-education-hub/vmchecker-next/wiki/Teaching-Assistant-Handbook). You will only require the private git repository. You can directly fork the following [template assignment](https://gitlab.cs.pub.ro/vmchecker/vmchecker-next-assignment).
 
 ### Setting up the development environment
 
 1. After cloning the repository install the python packages using `pipenv install`.
-2. `cp ./etc/.env.development .env`
-3. Customize the `.env` file with the correct information
-4. Start up the development stack `pipenv run docker-compose-dev up`. It will start a `Minio` and `Postgres` instance under the 'api' namespace
+2. Clone the Vmchecker Moodle plugin from: [VMChecker Next](https://github.com/open-education-hub/vmchecker-next) and change the compose-dev moodle service's path to point to it
+3. Start the environment using `./bin/dev.sh up --watch`
+
+#### First time configuration:
+
+**Note**: The first time you run `dev.sh` the moodle service might fail. Comment out the vmchecker volume bind and do `dev.sh down && dev.sh up --watch`.
+
+If this is the first time starting up the development environment you'll have to set up a Moodle assignment and configure the Moodle plugin.
+
+To configure the Moodle block plugin:
+
+1. Go to `Site Administration > Plugins > Blocks > VMChecker block`
+2. Change `vmck backend` to `http://backend:8000/api/v1/`
+
+To set up the Moodle assignment create a [course](https://docs.moodle.org/405/en/Create_a_course) and some [users](https://docs.moodle.org/405/en/Create_a_user) and [add them to the course](https://docs.moodle.org/405/en/Add_new_users). Then you can follow the [TA handbook](https://github.com/open-education-hub/vmchecker-next/wiki/Teaching-Assistant-Handbook) on how to prepare the assignment.
+
+**Useful notes**:
+- Moodle is avaialbe at `http://localhost/`
+    - User: `admin`, Password: `Parola-123`
+    - If you are also developing the Moodle plugin check out the [Moodle debugging notes](https://docs.moodle.org/405/en/Debugging)
+- VMChecker service port `8000`
+
+### Debugging
+
+The backend service exposes port `5678` for debugging. A VS Code configuration example:
+```json
+{
+            "name": "Python Debugger: Remote Attach",
+            "type": "debugpy",
+            "request": "attach",
+            "connect": {
+                "host": "localhost",
+                "port": 5678
+            },
+            "pathMappings": [
+                {
+                    "localRoot": "${workspaceFolder}",
+                    "remoteRoot": "/opt/api"
+                }
+            ]
+        }
+```
 
 ### Running tests
 

api/wsgi.py

@@ -1,6 +1,5 @@
 import os
 
-import uwsgidecorators
 from django.core.wsgi import get_wsgi_application
 
 import api.sentry as sentry
@@ -11,10 +10,11 @@
 
 sentry.initialize()
 
+if os.getenv("DEBUG") != "True":
+    import uwsgidecorators
+    @uwsgidecorators.postfork
+    def preload():
+        from api.core.task_runner import Runner
 
-@uwsgidecorators.postfork
-def preload():
-    from api.core.task_runner import Runner
-
-    if os.getenv("API_TASK_RUNNER_ENABLED") == "True":
-        Runner.instance()
+        if os.getenv("API_TASK_RUNNER_ENABLED") == "True":
+            Runner.instance()

bin/dev.sh

@@ -2,4 +2,4 @@
 
 cd "$(dirname "${BASH_SOURCE[0]}")"/.. || exit 1
 
-docker compose -f ./etc/compose-dev.yml -p backend "$@"
+docker compose -f ./etc/compose-dev.yml -p vmchecker-backend "$@"

bin/startapi.sh

@@ -4,8 +4,14 @@ cd "$(dirname "${BASH_SOURCE[0]}")"/.. || exit 1
 
 sleep 2 # make sure that the DB container is up
 ./manage.py migrate
-exec uwsgi --chdir="$(pwd)" \
-    --env DJANGO_SETTINGS_MODULE=api.settings \
-    --env API_TASK_RUNNER_ENABLED=True \
-    --processes "$UWSGI_PROCESS_COUNT" \
-    --ini etc/api.ini
+
+
+if [[ "$DEBUG" == "True" ]] ; then
+    exec uwsgi --chdir="$(pwd)" \
+        --env DJANGO_SETTINGS_MODULE=api.settings \
+        --env API_TASK_RUNNER_ENABLED=True \
+        --processes "$UWSGI_PROCESS_COUNT" \
+        --ini etc/api.ini
+else
+    python3 -m debugpy --listen 0.0.0.0:5678 ./manage.py runserver 0.0.0.0:8000
+fi

etc/compose-dev.yml

@@ -24,9 +24,9 @@ services:
       MOODLE_USERNAME: 'admin'
       MOODLE_PASSWORD: 'Parola-123'
     volumes:
-      - ../../vmchecker:/bitnami/moodle/blocks/vmchecker # NOTE: Change the path ('../../vmchecker') to the location you downloaded the vmchecker plugin to
       - moodle_data:/bitnami/moodle
       - moodledata_data:/bitnami/moodledata
+      - ../../vmchecker:/bitnami/moodle/blocks/vmchecker # NOTE: Change the path ('../../vmchecker') to the location you cloned the vmchecker plugin to
     depends_on:
       - mariadb
 
@@ -65,6 +65,7 @@ services:
           path: ../etc/api.ini
           target: /opt/api/etc/api.ini
     environment:
+      DEBUG: 'True'
       GITLAB_URL: 'https://gitlab.com'
       MINIO_ADDRESS: 'minio:9000'
       MINIO_ACCESS_KEY: 'access_key'
@@ -78,6 +79,7 @@ services:
       UWSGI_PROCESS_COUNT: '2'
     ports:
       - '8000:8000'
+      - '5678:5678' # python debug port
     depends_on:
       - postgres
       - minio