add configuration & related readme notes for debugging gen-ai bff (tested in vscode) (opendatahub-io#5566)

Author: jharan1

packages/gen-ai/Makefile

@@ -35,6 +35,9 @@ dev-bff-mock: ## Run only the bff in development mode
 dev-bff:
 	cd bff && MAAS_URL=${MAAS_URL} DISTRIBUTION_NAME=${DISTRIBUTION_NAME} LLAMA_STACK_URL=${LLAMA_STACK_URL} AUTH_TOKEN=user_token AUTH_TOKEN_HEADER=Authorization AUTH_TOKEN_PREFIX="Bearer " make run STATIC_ASSETS_DIR=../frontend/dist
 
+.PHONY: dev-bff-debug
+dev-bff-debug: ## Run BFF with Delve debugger (VSCode can attach - requires Delve installation, see readme)
+	cd bff && MAAS_URL=${MAAS_URL} DISTRIBUTION_NAME=${DISTRIBUTION_NAME} LLAMA_STACK_URL=${LLAMA_STACK_URL} AUTH_TOKEN=user_token AUTH_TOKEN_HEADER=Authorization AUTH_TOKEN_PREFIX="Bearer " make debug STATIC_ASSETS_DIR=../frontend/dist
 
 .PHONY: dev-frontend
 dev-frontend: ## Run only the frontend in development mode
@@ -58,6 +61,16 @@ dev-start: dev-portforward ## Start frontend, bff, and port-forwarding
 	@sleep 2
 	make -j 2 dev-bff dev-frontend
 
+.PHONY: dev-start-debug
+dev-start-debug: dev-portforward ## Start frontend, bff with debugger, and port-forwarding (VSCode can attach on port 2345)
+	@sleep 2
+	@echo ""
+	@echo "🐛 Starting in DEBUG mode..."
+	@echo "📍 Delve debugger will listen on port 2345"
+	@echo "📍 In VSCode: Press F5 and select 'Attach to Delve (make dev-start-debug)'"
+	@echo ""
+	make -j 2 dev-bff-debug dev-frontend
+
 .PHONY: dev-start-no-portforward
 dev-start-no-portforward: ## Start frontend and bff without port-forwarding
 	make -j 2 dev-bff dev-frontend

packages/gen-ai/README.md

@@ -124,6 +124,46 @@ make dev-start-no-portforward
 
 These commands will run both services in parallel, making it easier to start your development environment with a single command.
 
+## Debugging the bff
+
+If you want to be able to set breakpoints in vscode, you must first ensure the following debug config is added to your .vscode/launch.json file.
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Attach to Delve (make dev-start-debug)",
+      "type": "go",
+      "request": "attach",
+      "mode": "remote",
+      "remotePath": "${workspaceFolder}/packages/gen-ai/bff",
+      "port": 2345,
+      "host": "localhost",
+      "showLog": true,
+      "trace": "verbose"
+    },
+  ]
+}
+```
+
+The debug approach will use the 'debug' command defined in packages/gen-ai/bff/Makefile, which uses 'dlv' (short for Delve, a debugger for the Go programming language, more at [github repo](https://github.com/go-delve/delve/tree/master)), which will need to be installed locally first.
+
+You can install the latest version with:
+
+```bash
+  go install github.com/go-delve/delve/cmd/dlv@latest
+```
+
+Then run the below, which will start the gen-ai frontend, bff with debugger, and port-forwarding (VSCode can attach on port 2345).
+
+```bash
+cd packages/gen-ai
+make dev-start-debug
+```
+
+Once everything is running and ready, you can click on the 'Run and Debug' tab in left navbar, and in the top dropdown, select and run 'Attach to Delve (make dev-start-debug)'. Now you should be able to set breakpoints in order to debug code inside packages/gen-ai/bff.
+
 ## Building and Running with Docker
 
 The project includes a multi-stage Dockerfile that builds both the frontend and backend components and creates a minimal production image.

packages/gen-ai/bff/.gitignore

@@ -1,2 +1,5 @@
 vendor/
 pkg/
+
+# Debug files generated by running debugger can be ignored
+__debug*

packages/gen-ai/bff/Makefile

@@ -56,6 +56,14 @@ run: fmt vet envtest ## Runs the project.
 	ENVTEST_ASSETS="$(shell $(ENVTEST) use $(ENVTEST_K8S_VERSION) --bin-dir $(LOCALBIN) -p path)" \
 	go run ./cmd --port=$(PORT) --static-assets-dir=$(STATIC_ASSETS_DIR) --log-level=$(LOG_LEVEL) --allowed-origins=$(ALLOWED_ORIGINS) --llama-stack-url=$(LLAMA_STACK_URL) --maas-url=$(MAAS_URL) --mock-ls-client=$(MOCK_LS_CLIENT) --mock-k8s-client=$(MOCK_K8S_CLIENT) --mock-mcp-client=$(MOCK_MCP_CLIENT) --mock-maas-client=$(MOCK_MAAS_CLIENT) --auth-method=$(AUTH_METHOD) --path-prefix=$(PATH_PREFIX) --filtered-model-keywords=$(FILTERED_MODEL_KEYWORDS) --distribution-name=$(DISTRIBUTION_NAME)
 
+.PHONY: debug
+debug: fmt vet envtest ## Runs the project with Delve debugger (VSCode can attach on port 2345).
+	@echo "Starting BFF with Delve debugger on port 2345..."
+	@echo "In VSCode: Press F5 and select 'Attach to Delve (make dev-start-debug)'"
+	ENVTEST_ASSETS="$(shell $(ENVTEST) use $(ENVTEST_K8S_VERSION) --bin-dir $(LOCALBIN) -p path)" \
+	dlv debug ./cmd --headless --listen=:2345 --api-version=2 --accept-multiclient --continue -- \
+		--port=$(PORT) --static-assets-dir=$(STATIC_ASSETS_DIR) --log-level=$(LOG_LEVEL) --allowed-origins=$(ALLOWED_ORIGINS) --llama-stack-url=$(LLAMA_STACK_URL) --maas-url=$(MAAS_URL) --mock-ls-client=$(MOCK_LS_CLIENT) --mock-k8s-client=$(MOCK_K8S_CLIENT) --mock-mcp-client=$(MOCK_MCP_CLIENT) --mock-maas-client=$(MOCK_MAAS_CLIENT) --auth-method=$(AUTH_METHOD) --path-prefix=$(PATH_PREFIX) --filtered-model-keywords=$(FILTERED_MODEL_KEYWORDS) --distribution-name=$(DISTRIBUTION_NAME)
+
 ##@ Dependencies
 
 ## Location to install dependencies to