Debugging Django apps running in Docker using ptvsd - Visual Studio (Code)

docker_debugging.md

Remote debugging in Docker (for Django apps)

In order to enable debugging for your Django app running in a Docker container, follow these steps using Visual Studio (Code):

1. Add ptvsd to your requirements.txt file

ptvsd == 4.3.2

2. To your launch.json, add this:

  {
      "name": "Remote Django App",
      "type": "python",
      "request": "attach",
      "pathMappings": [
          {
              "localRoot": "${workspaceFolder}",
              "remoteRoot": "/remote_root/of/your/app"
          }
      ],
      "port": 3000,
      "host": "localhost"
  }

(Edit the remoteRoot option to reflect your app).

3. To your manage.py, add this:

  if __name__ == "__main__":                                                    # This already exists
      os.environ.setdefault("DJANGO_SETTINGS_MODULE", "your_project.settings")  # This already exists

      from django.core.management import execute_from_command_line              # This already exists
      from django.conf import settings

      if settings.DEBUG:
          if os.environ.get('RUN_MAIN') or os.environ.get('WERKZEUG_RUN_MAIN'):
              import ptvsd
              ptvsd.enable_attach(address = ('0.0.0.0', 3000))
              print "Attached remote debugger"

      execute_from_command_line(sys.argv)                                         # This already exists

Note: The third if statement here ensures the debugger does not get attached again after a live reload.

4. Be sure to open port 3000 in your docker command or docker-compose.yml

5. Run your app:

  python manage.py runserver 0.0.0.0:8000

Line-by-line debugging

Note: In some (non-Django) cases line-by-line debugging does not work, unless you use double backslashes (\) in your remoteRoot parameter (Viscual Studio Code), even though the remote server runs on Linux. E.g. "remoteRoot": "\\remote_root\\of\\your\\app"

Gotchas

• When running a (non-Django) app using docker-compose run instead of docker-compose up, you need to add the additional --service-ports flag to open the ports defined in your docker-compose.yml:

docker-compose run --service-ports your_app

Otherwise, you will see a Connection refused error when trying to attach, as the required debug port (usually 3000) is not opened.

Shoutout

Shoutout to this exellent blog post describing how you can keep live reload turned on while remote debugging. (Previously we had to disable Django's live reload function because it would attach the debugger twice, thus throwing an error). We really can have our cake and eat it too.

Note: Be sure to use the latest version of ptvsd, as some old versions will throw an exceptions.SystemExit when you are attached from VS Code and the server gets reloaded. This happened to me using `ptvsd == 4.1.3.