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.veloctl env sync --service service_name --remote-debug -f velocity.yaml
This command will start
veloctl env sync
, as well as the following:- 1.Make the container run the debugger command instead of running your original application command
- 2.Expose the debugger port locally
- 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.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
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.Make sure
nodemon
is included as part of your application image, for example by executing:
npm install --save-dev nodemon
- 2.Add a
debug
target to yourpackage.json
, as such:
"scripts": {
"prepare": "husky install",
"start": "node .",
"debug": "nodemon --inspect ."
}
- 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:
- 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. - 5.Start debugging using your IDE!
This example will use
delve
as a remote debugger.- 1.Make sure the
delve
debugger binary is included in your Docker image. This can be done, for example, by adding to following to yourDockerfile
:
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:
- 3.
- 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.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:
- 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. - 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
Last modified 2mo ago