[Question]: How to debug ragflow_server.py?

[ahmedavid]

Self Checks

• [x] I have searched for existing issues search for existing issues, including closed ones.
• [x] I confirm that I am using English to submit this report (Language Policy).
• [x] Non-english title submitions will be closed directly ( 非英文标题的提交将会被直接关闭 ) (Language Policy).
• [x] Please do not modify this template :) and fill in all the required fields.

Describe your problem

I would like to make some small changes in http API for my own purposes. I would like to run the server in debug mode in vscode or in the container. Please point to me to some documentation or give brief explanation.

Thank you.

[dosubot[bot]]

Hi @ahmedavid! I'm Dosu and I’m helping the ragflow team.

To debug ragflow_server.py, you have two main options: use the built-in debug mode or attach a debugger like VSCode/debugpy.

1. Run in Debug Mode (Werkzeug Debugger): Start the server with the --debug flag:

python api/ragflow_server.py --debug

This enables Werkzeug's debugger and auto-reloader, making it easier to iterate on code changes and catch exceptions interactively. You can use this both locally and inside a container if you have shell access and the right ports exposed.
Reference

2. Remote Debugging with VSCode (debugpy): Set the environment variable RAGFLOW_DEBUGPY_LISTEN to a port (e.g., 5678) before starting the server:

export RAGFLOW_DEBUGPY_LISTEN=5678
python api/ragflow_server.py --debug

This will start a debugpy server listening on all interfaces. In VSCode, use the "Python: Attach" debug configuration to connect to localhost:5678 (or the container's IP if running inside Docker).
Reference

3. Debugging in Docker:

• Expose the debug port in your Docker run or compose config (e.g., -p 5678:5678).
• Set RAGFLOW_DEBUGPY_LISTEN=5678 in the container environment.
• Start the server as above.
• Attach from VSCode using the remote debug configuration.

4. Tips:

• You can set breakpoints in VSCode and step through code as usual.
• Make sure your container entrypoint or launch script does not restart the server in a loop, or you may lose your debug session. You might want to modify the entrypoint for development.
• The launch_ragflow_from_source.md doc has more details on running from source and setting up your environment.

This setup should let you make and test changes to the HTTP API with full debugging support.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}   

[wwwqqyy]

Could you please explain how to perform debugging? Specifically, do you run the program on the front end first, and then set breakpoints in the backend code? Are there any other better ways? For instance, some local scripts are used to load files, and then perform subsequent operations such as slicing and constructing graphs.

[wwwqqyy]

I started the service using the source code. However, without a good debugging method, it is very difficult to find the corresponding backend code for the frontend. Could you suggest any better debugging methods? I would like to gain a deeper understanding of the subsequent processes such as parsing after file upload, storing in ES, and so on.