Merge branch 'feat/tutorial' into 'develop'

Added tutorial for debugging with VSCode

See merge request teraflow-h2020/controller!150

tutorial/3-0-development.md

@@ -7,3 +7,4 @@ this guide assumes you are using the Oracle VirtualBox-based VM running MicroK8s
 ## Table of Content:
 - [3.1. Configure VSCode and Connect to the VM](./3-1-configure-vscode.md)
 - [3.2. Development Commands, Tricks, and Hints (WORK IN PROGRESS)](./3-2-develop-cth.md)
+- [3.3. Debugging individual components in VSCode](./3.3-debug-comp.md)

tutorial/3-1-configure-vscode.md

@@ -75,3 +75,18 @@ Host TFS-VM
 ```
   - Save the file
 - From now, VSCode will use the identity file to connect to the TFS-VM instead of the user's password.
+
+
+## 3.1.5. Install VSCode Python Extension (in VSCode server)
+This step installs Python extensions in VSCode server running in the VM.
+
+- In VSCode (connected to the VM), click left button "Extensions"
+- Search "Python" extension in the extension Marketplace.
+- Install official "Python" extension released by Microsoft.
+  - By default, since you're connected to the VM, it will be installed in the VSCode server running in the VM.
+
+- In VSCode (connected to the VM), click left button "Explorer"
+- Click "Ctrl+Alt+P" and type "Python: Select Interpreter". Select option "Python: 3.9.13 64-bit ('tfs')"
+
+in terminal: set python path to be used by VSCode:
+`echo "PYTHONPATH=./src" > ~/tfs-ctrl/.env`

tutorial/3-2-develop-cth.md

@@ -16,3 +16,22 @@ docker build -t "context:lgr-test" -f ./context/Dockerfile .
 
 Run by hand:
 docker run --rm --name lgr-test -it --env "DB_BACKEND=inmemory" --entrypoint /bin/bash context:lgr-test
+
+
+## Expose gRPC ports through Ingress Controller
+source `my_deploy.sh`
+run script `./expose_ingress_grpc.sh`
+
+to test:
+sudo apt-get install nmap
+nmap -p 1010 127.0.0.1  # test if context is reachable
+should retrieve something like:
+$ nmap -p 1010 127.0.0.1
+Starting Nmap 7.80 ( https://nmap.org ) at 2022-07-29 15:06 UTC
+Nmap scan report for localhost (127.0.0.1)
+Host is up (0.00035s latency).
+
+PORT     STATE SERVICE
+1010/tcp open  surf
+
+Nmap done: 1 IP address (1 host up) scanned in 0.07 seconds

tutorial/3.3-debug-comp.md

+# 3.3 Debugging individual components in VSCode
+
+## 3.3.1 Source TeraFlow environment variables into .bashrc
+
+With any text editor, open the file `~/.bashrc` and add the following line at the end:
+```bash
+source ~/tfs-ctrl/tfs_runtime_env_vars.sh
+```
+
+"tfs-ctrl" can be substituted by the appropriate path where the controller is deployed.
+
+## 3.3.2 Install VSCode Python extensions
+The following extensions are required to execute and debug TeraFlow components in VSCode:
+
+- *Python*. New versions of the extension are known to have some unsolved bugs, it is recommended to downgrade to version **v2022.10.0**. Go to the extension window, select Python, click the arrow next to the "Uninstall" button and select "Install Another Version..."
+- *Pylance*
+
+## 3.3.3 Configure VSCode workspace and launch settings
+Run VSCode and open the folder with the source code of TeraFlow, this will be the main workspace. Create (if it does not exist) the subfolder `.vscode`. Inside, create and edit the following files:
+
+- `settings.json` 
+    ```bash
+    {
+    "python.analysis.extraPaths": ["<HOME>/.pyenv/versions/3.9.7/envs/teraflow/lib/python3.9/site-packages"],
+    }
+    ```
+    `<HOME>` should be replaced by the path of your home folder. If in the future another version of Python is used, or the virtual environment changes, this file should be updated to reflect the new path of the installed pip packages.
+
+- `launch.json`
+    ```bash
+    {
+        // Use IntelliSense to learn about possible attributes.
+        // Hover to view descriptions of existing attributes.
+        // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+        "version": "0.2.0",
+        "configurations": [
+            {
+                "name": "TFS compute.service",
+                "module": "compute.service",
+                "python": "${command:python.interpreterPath}",
+                "type": "python",
+                "request": "launch",
+                "justMyCode": true,
+                "console": "internalConsole",
+                "env": {
+                    "PYTHONPATH": "${config:python.analysis.extraPaths}:${workspaceRoot}/src",
+                    "LOG_LEVEL": "DEBUG",
+                    }
+            }
+        ]
+    }
+    ```
+    This file contains the configuration necessary to execute the `"compute"` component from the TeraFlow controller, while providing debugging capabilities (e.g., breaking points, console log output etc.). After saving, the debugging can be started from the "Run and Debug" menu.
+
+    Additional profiles can be added to the JSON file under the `"configurations"` arrray. Copy & paste the existing one and change the `"name"` and  `"module"` fields.
\ No newline at end of file