Debug Server-Side Business Objects

Debugging of Server-Side Business Object is an experimental feature that can be used at own risk. This feature is not part of SLA.

Nevertheless we are happy to receive feedback on your experience on using the feature.

Use our experimental feature to open a debug session in Chrome DevTools to be able to debug Server-Side Business Objects.

Use all known features like breakpoints and watchpoints to fully enjoy debugging of your code.

Setup Preparation

Make sure your reverse Proxy is configured correctly to terminate TLS also for the exposed debug port and forward request and websocket conntections to the internal debug port.

On locally run instances you should be able to use debugging of Server-Side Business Objects directly.

Add Variables to your .env File

Add the required variables to your existing .env File

# Variables for the SSBO Debugging

# The Simplifier Host should be sufficient as a default
DEBUG_CHROME_DEV_TOOLS_EXPOSED_HOST=${SIMPLIFIER_HOSTNAME}
DEBUG_CHROME_DEV_TOOLS_PORT=2992

# The exposed port is usually the same as the internal port
DEBUG_CHROME_DEV_TOOLS_EXPOSED_PORT=${DEBUG_CHROME_DEV_TOOLS_PORT}

# Determines whether the dev-tools link protocol (true will deliver wss, false or anything else will deliver ws)
DEBUG_CHROME_DEV_TOOLS_USE_EXTERNAL_TLS=true

#Feature Flags
FEATURE_SSBO_JS_DEBUGGING=true

The Variables are explained in the following table:

Variable	Description	Default value
FEATURE_SSBO_JS_DEBUGGING	(de-)activates debugging of Server-Side Business Objects [true \| false]	false
DEBUG_CHROME_DEV_TOOLS_EXPOSED_HOST	Host to be used to connect from Chrome DevTools	127.0.0.1
DEBUG_CHROME_DEV_TOOLS_PORT	Port used to connect from Chrome DevTools	2992
DEBUG_CHROME_DEV_TOOLS_EXPOSED_PORT	Port used in provided link to open Debugger Session in Chrome DevTools Attention: Use only if internal port is not opened for access from Chrome DevTools	9229
DEBUG_CHROME_DEV_TOOLS_USE_EXTERNAL_TLS	Determine if the Chrome Debugger connects over WS (Websocket) or WSS (Websocket Secure)	true

Prepare your Docker Compose File

Add the following labels to the simplifier container in the docker-compose.yml file

      - DEBUG_CHROME_DEV_TOOLS_EXPOSED_HOST=${DEBUG_CHROME_DEV_TOOLS_EXPOSED_HOST}
      - DEBUG_CHROME_DEV_TOOLS_EXPOSED_PORT=${DEBUG_CHROME_DEV_TOOLS_EXPOSED_PORT}
      - DEBUG_CHROME_DEV_TOOLS_PORT=${DEBUG_CHROME_DEV_TOOLS_PORT}
      - DEBUG_CHROME_DEV_TOOLS_USE_EXTERNAL_TLS=${DEBUG_CHROME_DEV_TOOLS_USE_EXTERNAL_TLS}

      - FEATURE_SSBO_JS_DEBUGGING=true

Add the following labels to the traefik proxy container in the docker-compose.yml file

      # Second Router
      - "traefik.tcp.routers.ws-debugging.rule=HostSNI(`*`)"
      - "traefik.tcp.routers.ws-debugging.entrypoints=debugging"
      - "traefik.tcp.routers.ws-debugging.tls=true"
      - "traefik.tcp.routers.ws-debugging.service=ws-debugging"

      # Services
      # This is required in order to let Chrome Dev-Tools connect to Simplifier
      - "traefik.tcp.services.ws-debugging.loadbalancer.server.port=${DEBUG_CHROME_DEV_TOOLS_EXPOSED_PORT}"

Add the following commands to the traefik proxy container in the docker-compose.yml file

      - --entrypoints.debugging.address=:${DEBUG_CHROME_DEV_TOOLS_EXPOSED_PORT}
      - --entryPoints.debugging.transport.respondingTimeouts.readTimeout=60
      - --entryPoints.debugging.transport.respondingTimeouts.idleTimeout=180

Add the following port to the traefik proxy container in the docker-compose.yml file

      - ${DEBUG_CHROME_DEV_TOOLS_EXPOSED_PORT}:${DEBUG_CHROME_DEV_TOOLS_PORT}

You can find a complete example here on github

After saving the changes you must re-create the docker-compose setup to apply all changes.

Open debug session

As soon as the feature is activated a Debug button is displayed in test mode of your functions of Server-Side Business Objects.

Press the button to start your debug session. Follow the provided link to open your debug session in Chrome DevTools.

We recommend noting UUID of debug session

Status of session context

The current status of the debugging context is displayed in the results window. This is used for visualization.

Note: If you open multiple debug session, status of last opened session is shown.

Status	Displayed text	Remarks
Initialization	Debugging session initializing,	–
Open session	Debugging session for id: [UUID of session] ongoing.	It can only be displayed that session is open, not whether Chrome DevTools has connected to it
Closing session	Debugging session for id: [UUID of session] closing.	–

Close debug session

You can close the debug session by clicking on x-Button of info panel of debug session.

If the Chrome Dev Tools are not opened via the link within a few minutes, the debug context is automatically closed.

Hints on using Chrome DevTools

After clicking the link, Chrome DevTool opens where debugging is possible.

The first function is an anonymous function that can be skipped by skipping the step 4 times (F10). The fact that the anonymous function is called first is due to the GraalVM implementation. There is currently no known way of circumventing this fact.