From 01317138e288c30718938be7db3ab03499dee3aa Mon Sep 17 00:00:00 2001
From: tofarr <tofarr@gmail.com>
Date: Thu, 26 Sep 2024 08:57:37 -0600
Subject: [PATCH] Fix: uvicorn reloading when python files in workspace change,
 & started section for debugging instructions for developers (#4041)

Co-authored-by: Engel Nyst <enyst@users.noreply.github.com>
---
 Makefile                               |  2 +-
 docs/modules/usage/how-to/debugging.md | 71 ++++++++++++++++++++++++++
 docs/sidebars.ts                       |  4 ++
 3 files changed, 76 insertions(+), 1 deletion(-)
 create mode 100644 docs/modules/usage/how-to/debugging.md

diff --git a/Makefile b/Makefile
index 3798365f5d..d815adc332 100644
--- a/Makefile
+++ b/Makefile
@@ -190,7 +190,7 @@ build-frontend:
 # Start backend
 start-backend:
 	@echo "$(YELLOW)Starting backend...$(RESET)"
-	@poetry run uvicorn openhands.server.listen:app --host $(BACKEND_HOST) --port $(BACKEND_PORT) --reload --reload-exclude "workspace/*"
+	@poetry run uvicorn openhands.server.listen:app --host $(BACKEND_HOST) --port $(BACKEND_PORT) --reload --reload-exclude "$(shell pwd)/workspace"
 
 # Start frontend
 start-frontend:
diff --git a/docs/modules/usage/how-to/debugging.md b/docs/modules/usage/how-to/debugging.md
new file mode 100644
index 0000000000..d7933376b7
--- /dev/null
+++ b/docs/modules/usage/how-to/debugging.md
@@ -0,0 +1,71 @@
+# Debugging
+
+The following is intended as a primer on debugging OpenHands for Development purposes.
+
+## Server / VSCode
+
+The following `launch.json` will allow debugging the agent, controller and server elements, but not the sandbox (Which runs inside docker). It will ignore any changes inside the `workspace/` directory:
+
+```
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "OpenHands CLI",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "openhands.core.cli",
+            "justMyCode": false
+        },
+        {
+            "name": "OpenHands WebApp",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "uvicorn",
+            "args": [
+                "openhands.server.listen:app",
+                "--reload",
+                "--reload-exclude",
+                "${workspaceFolder}/workspace",
+                "--port",
+                "3000"
+            ],
+            "justMyCode": false
+        }
+    ]
+}
+```
+
+More specific debugging configurations which include more parameters may be specified:
+
+```
+    ...
+    {
+      "name": "Debug CodeAct",
+      "type": "debugpy",
+      "request": "launch",
+      "module": "openhands.core.main",
+      "args": [
+        "-t",
+        "Ask me what your task is.",
+        "-d",
+        "${workspaceFolder}/workspace",
+        "-c",
+        "CodeActAgent",
+        "-l",
+        "llm.o1",
+        "-n",
+        "prompts"
+      ],
+      "justMyCode": false
+    }
+    ...
+```
+
+Values in the snippet above can be updated such that:
+
+    * *t*: the task
+    * *d*: the openhands workspace directory
+    * *c*: the agent
+    * *l*: the LLM config (pre-defined in config.toml)
+    * *n*: session name (e.g. eventstream name)
diff --git a/docs/sidebars.ts b/docs/sidebars.ts
index 4b6562fb78..3b4810efe0 100644
--- a/docs/sidebars.ts
+++ b/docs/sidebars.ts
@@ -83,6 +83,10 @@ const sidebars: SidebarsConfig = {
         {
           type: 'doc',
           id: 'usage/how-to/openshift-example',
+        },
+        {
+          type: 'doc',
+          id: 'usage/how-to/debugging',
         }
       ]
     },