Kuzzle gives the possibility to debug a Kuzzle instance using the Debug Controller actions.
It's easier and safer to use the Debug Controller to debug Kuzzle remotely than exposing the debugger port using
node --inspect since the Debug Controller is limited by the authentication mechanism of Kuzzle making it impossible to use if you don't have the proper rights to use it.
Whereas when launching Kuzzle with
node --inspect you need to setup some Port Forwarding from your host machine to your local machine to be able to debug Kuzzle remotely, and you need to be sure that no one can access your instance using the Debug Port exposed.
By default access to the Chrome Devtools Protocol through the Debug Controller is disabled, to use the methods of the Chrome Devtools Protocol you need to enable it in the kuzzlerc file
true and rebooting your instance.
Debug Modules are still accessible when
security.debug.native_debug_protocol is disabled.
Debug Modules #
Debug Modules are modules of Kuzzle that are exposed through the Debug Controller actions and allows you to better understand what is happening on your running application and helps you to debug it.
Debug Modules are not related to the Chrome Devtools Protocol and perfectly safe to use. They do not expose the debugger directly, whereas the Chrome Devtools Protocol could be used to execute code remotely which is why access to the Chrome Devtools Protocol is disabled by default. It should only be enabled when you need to take memory snapshot, use breakpoint, the cpu profiler, etc...
Debug Kuzzle remotely using the Debug Controller and the Chrome Inspector #
To be able to debug Kuzzle remotely using the Chrome Inspector tool you need:
- A user allowed to access to all Debug Controller's actions. See the Permissions page on how to setup the proper permissions.
- To set the config
true, to allow the Debug Controller to execute actions from the Chrome Devtools Protocol, then restart your application.
- Kourou, the Kuzzle CLI, installed. You can install it using
npm install -g kourou.
- The Chrome Browser installed.
How to Debug #
Step 1 - Setup proxy server #
To debug Kuzzle remotely using the Chrome Inspector, you need to open a proxy server that will connected to Kuzzle to translate commands sent by the Chrome Inspector with the Chrome Devtools Protocol's format into actions of the Debug Controller. Don't worry this is very easy to do, you just have to use Kourou to perform this:
kourou app:debug-proxy --host <Kuzzle Host> --port <Kuzzle Port> --username <username> --password <user password>
This will open a proxy server that will connects to your Kuzzle instance using the given username and password and will do the translation automatically.
Remember that the user must be allowed to use all the actions of Debug Controller and you need to set the config option
true, to allow the Debug Controller to execute actions from the Chrome Devtools Protocol.
Once the proxy server has started and is successfully connected to your Kuzzle instance, you will will see a message like this in your terminal:
[ℹ] Connecting to ws://<host>:<port> ... [ℹ] Connected to Kuzzle node: knode-lackadaisical-archimedes-79903 [✔] Listening on port 9222, forwarding to Kuzzle at <host>:<port> [ℹ] Showing to Chrome Debugger as "Kuzzle Debugger - <host>:<port>" [ℹ] Waiting for Chrome Debugger to connect...
[✔] Listening on port 9222, forwarding to Kuzzle at <host>:<port>
You can see here that the proxy server is listening on port
9222. This will be needed for the next step.
Step 2 - Configure Chrome Inspector #
The proxy server is correctly running, you now need to open the Chrome Inspector to debug your instance. To do so, open the url
chrome://inspect in the Chrome Browser.
This will show you the Chrome debugger interface which will be used to debug the Kuzzle instance.
To allow the Chrome Inspector to see our proxy server exposed by the command
you need to add
localhost:9222 to the list of targets the Chrome Inspector can see and debug.
Here we are using the port
9222 but keep in mind that this port can be any other number. You need to change it accordingly on what port the proxy server is listening to, see end of Step 1 - Setup proxy server
The host will always be localhost since it's the IP of the proxy server that is running on your local machine.
1 - Click on the
Configure button, a dialog will appear where you can enter the IP and Port of your local proxy server.
2 - Enter your local target, here
3 - Confirm
If everything worked so far, you should see a new Remote Target called
Kuzzle Debugger - <Instance Host>:<Instance Port>.
4 - You can now click on
inspect and you're done.
Step 3 - Debugging #
You can now fully use the Chrome Inspector to debug you instance.
Step 4 - After Debugging #
Don't forget to set the
security.debug.native_debug_protocol configuration setting back to
false once you're done debugging to increase the security of your instance. Doing so, if one of your admin users with access to the Debug Controller gets compromised, it won't harm your application.