Debugging ‐ using a debugger

In order to investigate a particularly nasty bug or if you want to follow the execution of a piece of code step by step to understand it better, you may want to use a debugger. Since our development setup runs the Django server inside a Docker container, it is not as easy as clicking "debug" in your IDE of choice, but we still have options.

Option 1: Modify your development setup to run the Django server outside Docker

This is probably the best solution performance-wise since we skip Docker, but it needs more setup.

Here are the steps I followed to go from a fresh Ubuntu 24.04 install (inside VirtualBox) to having Tapir run without Docker. Other Linux distribution probably need slightly different but similar steps. Newer versions of OSes may make the instructions obsolete.

1. Install docker
2. Clone Tapir
3. Check that the installed python version is at least 3.11 (otherwise you can use this PPA to get a newer version)
4. Install Poetry
5. Start the docker containers: sudo docker compose up but stop the web one: sudo docker compose stop web
6. Install the packages that are installed in the docker image,
7. Install the following packages on top: sudo apt install libpq-dev python3-dev
8. Run poetry install
9. Update the settings.py file: the URLs should point to localhost instead of the docker container names. It should look like this

DATABASES = {
    "default": env.db(default="postgresql://tapir:tapir@localhost:5432/tapir"),
    "ldap": env.db_url(
        "LDAP_URL", default="ldap://cn=admin,dc=supercoop,dc=de:admin@localhost"
    ),
}

10. Run the server! You probably want to set the DEBUG environment variable.

DEBUG=1 poetry run python manage.py runserver_plus

Option 2: Use remote debugging

You'll need an IDE that supports remote debugging.

VSCode

I (Théo) don't use VSCode so I haven't tried it, but this page should be a good start.

If someone tries it out, please update this page!

PyCharm

You'll need PyCharm professional since the remote docker interpreter feature is not available in the free community edition.

The main documentation page is here, below is a condensed version.

Configure the remote interpreter

In short, you should just need to add a remote interpreter in your PyCharm settings:

Select the the web service, then in the third step select Virtualenv environment. Next to the interpreter dropdown click the three dots and put in the full path to the python interpreter inside your docker container.

You need to use the path to the python interpreter that is inside the environment that was created by Poetry. You can ask Poetry for that path by running docker compose exec web poetry show -v, the path will be above the list of packages and will look like /root/.cache/pypoetry/virtualenvs/tapir-9TtSrW0h-py3.11. The path that PyCharm needs is the path to the python interpreter itself, so /root/.cache/pypoetry/virtualenvs/tapir-9TtSrW0h-py3.11/bin/python.

Update the debug configuration

There's one change that we need to apply to PyCharm's default debug configuration. Open the configuration window from the top right of your PyCharm window:

and in the Host field put 0.0.0.0.

That should be it. Start the debugging, add a breakpoint for example to tapir.accounts.views.TapirUserDetailView.get_permission_required as a test, then visit any member's page. PyCharm's debugger should get triggered.