Search
⌃K

Remote Debugging

Debug your application locally while it is running in a remote container
Debugging is an essential part of the software development process, as it allows you to understand how your application behaves.
Velocity's Remote Debugging feature enables you to run a debug session against the remote container while it is integrated into the rest of your environment.
Remote Debugging is a part of Velocity's veloctl env sync, which means your code will be synced & hot reloaded automatically while you are debugging your code.

Starting a remote debug session

veloctl env sync --service service_name --remote-debug -f velocity.yaml
This command will start veloctl env sync, as well as the following:
  1. 1.
    Make the container run the debugger command instead of running your original application command
  2. 2.
    Expose the debugger port locally
  3. 3.
    Install and expose SSH access if specified (This is optional and intended for some language-specific use cases, such as Ruby.)
When you change your code, veloctl env sync will automatically detect your code change and sync it to the remote container. For more info, see The .velocity.yaml config.
When you abort the veloctl env sync command, the container configuration will return to its original state.
If you are remote debugging an interpreted language (such as Ruby, Python, NodeJS, etc.), you can improve your experience by using the --live-upadate flag, which will hot reload the source files directly instead of rebuilding the image on each change. See The .velocity.yaml config for more details.

Configuring remote debug

Velocity's Remote debugging feature is language agnostic, but the debugging configuration (shown below) will be language, and sometimes application, specific.
Velocity allows you to define this configuration as a yaml file, and commit it alongside your application source code. That way, you define it once, and share it with your team.
The following configuration is needed in your .velocity.yaml file:
version: 1
services:
service_name:
sync:
debug:
command: COMMAND # The command to run the remote debugger
debugger_port: 9229 # the port the debugger listens to
local_port: 9229 # the port to expose locally on the developer's machine
ssh:
expose: false # should we expose SSH locally from the container (disabled by default, needed only in some cases)
local_port: 6060 # the port to expose the SSH locally on the developer's machine
​

Configuration examples

The remote debugging feature is language and application-agnostic, which means you can run it on every service that is written in a language that supports remote debugging.
Velocity gives you the freedom to choose how you want to run your debugger. For a quick start, here are a few examples.
NodeJS
Golang
Ruby
Note: this example will work with all modern JavaScript-based languages and platforms, such as TypeScript. Simply adapt the debug target to use your preferred debugger using your configuration as shown below.
This example will use nodemon as a remote debugger.
  1. 1.
    Make sure nodemon is included as part of your application image, for example by executing:
npm install --save-dev nodemon
  1. 2.
    Add a debug target to your package.json, as such:
"scripts": {
"prepare": "husky install",
"start": "node .",
"debug": "nodemon --inspect ."
}
  1. 3.
    Configure the .velocity.yaml to run the debug target when using remote debugging:
version: 1
services:
service_name:
sync:
debug:
command: npm run debug
debugger_port: 9229
local_port: 9229
As a one-time setup, you will need to configure your IDE to connect to the remote debugger.
As an example, for IntelliJ IDEA, please use the following guide:
  1. 4.
    Head to Starting a remote debug session to start the debug setup. Since NodeJS is an interpreted language, we recommend using the --live-update flag to hot reload source files directly.
  2. 5.
    Start debugging using your IDE!
This example will use delve as a remote debugger.
  1. 1.
    Make sure the delve debugger binary is included in your Docker image. This can be done, for example, by adding to following to your Dockerfile:
RUN go install github.com/go-delve/delve/cmd/[email protected]
2. Configure the .velocity.yaml to run the debugger command when using remote debugging (change the main executable name to your app executable name):
version: 1
services:
service_name:
sync:
debug:
command: dlv --listen=:2345 --headless=true --api-version=2 exec ./main
debugger_port: 2345
local_port: 2345
As a one-time setup, you will need to configure your IDE to connect to the remote debugger.
As an example, for IntelliJ Goland, please use the following guide:
  1. 3.
    Head to Starting a remote debug session to start the debug setup
  2. 4.
    Start debugging using your IDE!
This example will use rdebug-ide as a remote debugger.
For an optimal debugging experience, when using an IDE such as RubyMine, SSH access is needed to the remote container. Velocity can set this up for you automatically.
  1. 1.
    Make sure your application Gemfile contains the debugger dependencies by adding the following:
group :development do
gem 'ruby-debug-ide'
gem 'debase'
end
2. Configure the .velocity.yaml to run the debugger command when using remote debugging:
version: 1
services:
service_name:
sync:
debug:
command: rdebug-ide --host 0.0.0.0 --port 1234 --dispatcher-port 1234 -- bin/rails server -b 0.0.0.0
debugger_port: 1234
local_port: 1234
ssh:
expose: true # expose SSH access
local_port: 6060
​
As a one-time setup, you will need to configure your IDE to connect to the remote debugger.
As an example, for IntelliJ RubyMine, please use the following guide:
  1. 3.
    Go to Starting a remote debug session to start the debug setup. Since Ruby is an interpreted language, we recommend using the --live-reload flag to hot reload source files directly.
  2. 4.
    Start debugging using your IDE
​
The SSH exposure requires rsync to be installed on the container. This can be added to your Dockerfile, for example, using:
RUN apk add rsync

Next Steps:

Previous
Env Sync Tutorial with Python
Next
Env Exec
Last modified 2mo ago