Debugging Guide

This guide covers setting up a local debugging environment for Thunder's backend, Gate app, Develop app, and React SDK sample application.

Introduction

Thunder consists of the following components:

Component	Description	Port
Backend	Go-based API server	8090
Gate App	React-based authentication gateway	5190
Develop App	React-based developer console	5191
React SDK Sample	Sample app demonstrating OAuth integration	3000

This guide focuses on local development and debugging with SQLite for database storage.

Prerequisites

Required

• Go (v1.26+)
• Node.js (20+)
• pnpm (v10)
• Delve (Go debugger)

  go install github.com/go-delve/delve/cmd/dlv@latest

• VS Code with the Go extension
• DBeaver (database viewer)
• Google Chrome browser

Optional

• yq — YAML parser for better config parsing

  brew install yq

Start Thunder for Debugging

Step 1: Configure the Server

Edit backend/cmd/server/repository/conf/deployment.yaml and add:

CORS allowed origins (so the frontend development servers and sample app can talk to the backend):

cors:
  allowed_origins:
    - "https://localhost:3000"
    - "https://localhost:5190"
    - "https://localhost:5191"

Gate client port (so the backend knows where to redirect for auth):

gate_client:
  port: 5190

Step 2: Seed Data

Open a terminal and switch to the Thunder root directory:

cd <repo-root>

Run the backend with API security disabled:

THUNDER_SKIP_SECURITY=true make run_backend

In a new terminal, seed data (one-time only):

THUNDER_API_BASE="https://localhost:8090" \
  backend/cmd/server/bootstrap/01-default-resources.sh \
  --develop-redirect-uris "https://localhost:5191/develop"

THUNDER_API_BASE="https://localhost:8090" \
  backend/cmd/server/bootstrap/02-sample-resources.sh

Stop the backend by pressing Ctrl + C.

Step 3: Start the Backend in Debug Mode

make debug_backend

Step 4: Start the Frontend

In a new terminal:

make run_frontend

Step 5: Start the Sample App (Optional)

In a new terminal, navigate to the sample app:

cd <repo-root>/samples/apps/react-sdk-sample

Generate TLS certificates:

openssl req -x509 -newkey rsa:2048 -nodes -sha256 -days 365 \
  -keyout server.key -out server.cert \
  -subj "/O=WSO2/OU=Thunder/CN=localhost"

Run the sample app:

npm run dev

Connect Debuggers

Connect to Develop App (Browser DevTools)

1. Open https://localhost:5191/develop in Chrome
2. Open DevTools (Cmd+Option+I on macOS, F12 on Windows/Linux)
3. Navigate to Sources → top → localhost:5191 → develop → src
4. Click on a line number to set a breakpoint
5. When that line executes, Chrome pauses execution and lets you inspect variables

Connect to Backend (VS Code)

1. Open the Thunder repository in VS Code
2. Go to Run and Debug view (Cmd+Shift+D)
3. Select "Connect to server" from the dropdown
4. Click the green Play button or press F5
5. Switch to the Debug Console (Cmd+Shift+Y) to view output

Setting breakpoints:

• Open any Go file
• Click in the gutter to the left of a line number to add a breakpoint (red dot)
• When that line executes, VS Code pauses execution

Connect DBeaver to View Database Tables

1. Open DBeaver
2. Open the New Database Connection wizard (Ctrl+Shift+N)
3. Select SQLite and click Next
4. Set the path to one of the database files:

Database	Path
User DB	<repo-root>/backend/cmd/server/repository/database/userdb.db
Runtime DB	<repo-root>/backend/cmd/server/repository/database/runtimedb.db
Config DB	<repo-root>/backend/cmd/server/repository/database/configdb.db

5. Click Test Connection to verify, then click Finish
6. Repeat for the other two databases

Sample Debug Scenario: User Creation

This walks through debugging the user creation flow from the UI to database storage.

1. Set Develop App Breakpoints

In Chrome DevTools, open:

• features/users/api/useCreateUser.ts — set a breakpoint at const serverUrl: string = getServerUrl();

2. Set Backend Breakpoints

In VS Code, open these files and set breakpoints:

• backend/internal/user/handler.go — at the beginning of HandleUserPostRequest
• backend/internal/user/service.go — at the beginning of CreateUser
• backend/internal/user/store.go — at the beginning of CreateUser

3. Trigger the Flow

1. Navigate to https://localhost:5191/develop
2. Log in with admin credentials (admin / admin)
3. Go to Users section
4. Click Add User
5. Select User Type: Person
6. Fill in:
   • Username: john.doe
   • Email: john.doe@example.com
   • Password: Test@1234
7. Click Create User

4. Debug the Flow

• Chrome pauses at the frontend breakpoint — inspect variables and step through the API call
• Once the API call is made, VS Code pauses at the backend breakpoints
• Use the Variables panel to inspect request data
• Step through the code (F10 step over, F11 step into, F5 continue)
• After continuing through the flow, the user is saved to the database

5. Verify in Database

Open DBeaver and view the User table in the User DB to confirm the new user was created.