Using VSCode to remotely debug Python code in local Docker container

Question

Background: We have Sphinx, a Python application for generating documentation, running inside a Docker Container. I'm running into an issue with converting drawio files. When executed in our GitLab pipelines it executes fine but when the project is executed locally on my M2 Mac it fails to convert the image and throws an exception. I've actually resolved the problem by rebuilding the container on my M2 machine, thus installing M2 versions of the packages required. I still wish to be able to learn how to properly set up the debugger.

Situation: I've been digging through the Sphinx source, adding debug prints. I got pretty much as far as the Traceback when I eventually couldn't see where we went anymore. Therefore I'm now looking into running sphinx with a live debugger attached.
I have:

• Opened the 5678 port on my container using docker run ... -p 5678:5678.
• Installed debugpy in the container
• Started debugpy in the container using python3 -m debugpy --wait-for-client --listen 0.0.0.0:5678 /opt/venv/bin/sphinx-build [lots of switches and options]
• Attached to the debugpy process waiting inside the container from VSCode outside the container using this launch.json. I created the launch.json by selecting the "Python: Remote launch" alternative after clicking "create a launch.json file".

{
    // 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": "Python: Remote Attach",
            "type": "python",
            "request": "attach",
            "connect": {
                "host": "localhost",
                "port": 5678
            },
            "pathMappings": [
                {
                    "localRoot": "${workspaceFolder}",
                    "remoteRoot": "."
                }
            ],
            "justMyCode": true
        }
    ]
}

The waiting process starts running and I can see it's output in the VSCode Debug Console. If i pause the execution i get presented with actual source code, but it is not the source I have locally in my repo. The specific source file somehow gets opened from within the container. When i hover over the opened source file's tab in VSCode i get e.g. "/opt/venv/python3.10/site-packages/sphinx/application.py" which is not a path that exists locally.
In this opened file I can also set breakpoints and read variable values, as you expect from a proper debugger. However and obviously, none of the breakpoints I set in my local files get hit.
This is a problem since I'd like to be able browse the source code and set breakpoints beforehand. Today I can only keep stepping and hope the correct file is opened.

Want: What I want is to either connect the files of the local repository or be able to browse the remote filesystem from within VSCode.

Answer 1

You can try remote-ssh.

According to the docs,

The Visual Studio Code Remote - SSH extension allows you to open a remote folder on any remote machine, virtual machine, or container with a running SSH server and take full advantage of VS Code's feature set. Once connected to a server, you can interact with files and folders anywhere on the remote filesystem.