Using VSCode to Debug Django

Setting up the dev environment

VSCode can be used to edit and debug files on remote environments using the Remote-SSH extension by Microsoft. This enables easy line-by-line debugging of the Django project hosted in a virtual machine.

The extension will need to login to the virtual box as root in order to edit files and setup a workspace in /var/django on the box. If the root account does not already have a password, create one by with sudo passwd root in the virtual box.

In VSCode, search for and install the Microsoft Remote-SSH extension from the extensions view (icon on left side-bar).

Click the new Remote "Quick Access" status bar item in the lower left corner of VSCode

Select Remote-SSH: Connect Current Window to Host and enter ssh root@hostname where hostname is the virtual box's internal IPv4 address (192.168...).

Enter the new root password when prompted (there may be multiple prompts)

Go to File>Open Folder and browse to /var/django

Search for and install the Microsoft Python extension to enable Python debugging. Install this extension on the remote host as well using the prompts in the extensions view.

Open the command pallete (View>Commmand Pallete) and search for and run the Python: Select Interpreter command. Enter or select the virtual environment interpreter created by provisions.sh at /usr/bin/venv/bin/python

Create or open the .vscode folder in the open director (/var/django/.vscode). Inside .vscode, create or open launch.json and insert the following launch configurations:

{
    "version": "0.2.0",
    "configurations": [
        {
            // settings.DEBUG must be true for this to work
            "name": "Python: Attach to Django",
            "type": "python",
            "request": "attach",
            "pathMappings": [
                {
                    "localRoot": "${workspaceFolder}/ops",
                    "remoteRoot": "/var/django/ops"
                }
            ],
            "port": 65078,
            "host": "10.0.2.15",
            "django": true,
            "justMyCode": true,  // set false if you want to be able to step into Django code
        },
        {
            "name": "Python: Launch Django",
            "type": "python",
            "request": "launch",
            "program": "${workspaceFolder}/ops/ops/wsgi.py",
            "args": [
                "runserver"
            ],
            "django": true,
            "justMyCode": false
        },
        { 
             "name": "Python: Run Test Suite", 
             "type": "python", 
             "request": "launch", 
             "program": "${workspaceFolder}/ops/manage.py", 
              "args": [ 
                   "test", "ops/opsTests/" 
              ], 
              "django": true,
              "justMyCode": false
        }
    ]
}

Finally, create or edit a .env file in the open directory and set the PYTHONPATH env var to the root of the Django project: PYTHONPATH=ops/

Now you can edit ops/ops/debugView.py to target whatever view is desired, add breakpoints to the files that will be run (by clicking in the gutter in VSCode), and launch the debugger (with the Python: Launch Django config) by clicking the Run icon in the run (debug) view (or from Run>Start Debugging).

Attaching to Django instance

Having completed the above steps, it is possible to attach to a running Django instance (if settings.DEBUG is True) with the Python: Attach to Django configuration. Select this configuration from the run (debug) view.

In views.py, you must insert debugpy.debug_this_thread() at the top of any view you wish to debug. This is because mod_wsgi spawns multiple Python threads to launch requested views. debugpy only debugs threads spawned by the main thread by default, so this call ensures that the view will be debugged regardless of its parent thread.

Now you can add breakpoints to the view by clicking in the gutter in VSCode. Restart the httpd service in the Virtual Box to ensure views.py is reloaded with the debugpy calls. Run the debugger (after selecting the Python: Attach to Django config) in VSCode by clicking the Run icon. The debugger should show that it is running but not much will happen until you exercise a view containing breakpoints by using Matlab, or by loading the web app, etc.

Troubleshooting

If you get an error while trying to attach: "already being debugged", restart httpd with service httpd restart