6.1 KiB

Raw Permalink Blame History

Remote debugging container

An Alpine container that builds a C++ demo project and runs codelldb as a DAP (Debug Adapter Protocol) server on port 13000. Any DAP-compatible editor can connect to it, set breakpoints, and debug the program running inside the container.

 YOUR EDITOR  ──DAP over TCP:13000──▶  REMOTE CONTAINER
                                       ├── codelldb (DAP server, 127.0.0.1:13001)
                                       ├── socat    (forwarder, 0.0.0.0:13000 ─▶ 13001)
                                       └── /project/build/debugapp (C++17, -g3 -O0)

Build and run standalone

You don't need docker-compose or the devstation container — the remote works on its own.

# Build (run from repository root)
docker build -t dap-debug-remote -f remote/Dockerfile .

# Run
docker run -d --name remote \
  -p 13000:13000 \
  --cap-add SYS_PTRACE \
  --security-opt seccomp:unconfined \
  dap-debug-remote

SYS_PTRACE and seccomp:unconfined are required so codelldb can control the child process (set breakpoints, read memory, single-step).

To use a different external port, set DAP_PORT:

docker run -d --name remote -p 8080:8080 -e DAP_PORT=8080 \
  --cap-add SYS_PTRACE --security-opt seccomp:unconfined \
  dap-debug-remote

Connecting to a non-local host

debugServer and most editors connect to localhost. If the remote container runs on another machine, tunnel the port over SSH:

ssh -L 13000:localhost:13000 user@remote-host

Connect from VSCode

Prerequisites

Install the CodeLLDB extension (vadimcn.codelldb) from the VSCode marketplace. This registers the "lldb" debug type, which VSCode needs even when connecting to an external DAP server.

Configure launch.json

Open common/project/ as your workspace folder in VSCode (so source paths match), then create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Remote launch (codelldb :13000)",
      "type": "lldb",
      "request": "launch",
      "program": "/project/build/debugapp",
      "cwd": "/project",
      "stopOnEntry": false,
      "sourceMap": {
        "/project": "${workspaceFolder}"
      },
      "debugServer": 13000
    }
  ]
}

Field	Why
`type: "lldb"`	Tells VSCode to use the CodeLLDB extension's session handler
`request: "launch"`	codelldb on the remote starts the program for you
`program` / `cwd`	Paths inside the container (not local)
`sourceMap`	Maps container paths (`/project`) to your local workspace folder so VSCode opens the right source files
`debugServer: 13000`	Key field — tells VSCode to connect to an already-running DAP server on this port instead of launching codelldb locally

Set breakpoints in src/calculator.cpp, press F5 (or Run ▸ Start Debugging), and select the configuration. The program runs in the container and stops at your breakpoints.

Without the CodeLLDB extension

If you don't want to install CodeLLDB, use the webfreak.debug extension (debug) which provides a generic "type": "cppdbg" adapter. However, the CodeLLDB approach above is recommended because it speaks the same DAP dialect as the server.

Connect from Neovim (your own installation)

Add this to your nvim-dap configuration:

local dap = require("dap")

-- Connect to codelldb running on the remote container.
dap.adapters.codelldb = {
  type = "server",
  host = "localhost",   -- or the remote host IP
  port = 13000,
}

dap.configurations.cpp = {
  {
    name = "Remote launch (codelldb :13000)",
    type = "codelldb",
    request = "launch",
    program = "/project/build/debugapp",
    cwd = "/project",
    stopOnEntry = false,
  },
}
dap.configurations.c = dap.configurations.cpp

Then <leader>dc (or :DapContinue) and select the configuration.

Using the included devstation container? The adapter configuration is already baked in — see devstation/README.md.

Connect from Emacs (dap-mode)

(require 'dap-codelldb)

;; Tell dap-mode to connect to the remote DAP server instead of launching
;; codelldb locally.
(dap-register-debug-template
 "Remote launch (codelldb :13000)"
 (list :type "codelldb"
       :request "launch"
       :program "/project/build/debugapp"
       :cwd "/project"
       :stopOnEntry nil
       :dap-server-host "localhost"
       :dap-server-port 13000))

Run M-x dap-debug and select the template. See the dap-mode wiki for details.

Connect from any DAP client

The remote exposes a standard DAP server on port 13000. Any tool that can act as a DAP client can connect:

CLI testing — send a raw DAP initialize request to verify the server is alive:

echo '{"command":"initialize","arguments":{"adapterID":"test"},"type":"request","seq":1}' | nc localhost 13000

Custom tooling — implement the DAP client side of the protocol and connect to localhost:13000.

Environment variables

Variable	Default	Description
`DAP_PORT`	`13000`	External port that socat listens on (mapped to `0.0.0.0`)

codelldb's internal port (13001) is fixed and not configurable from outside.

Troubleshooting

"Connection refused" Make sure the container is running (docker ps) and the port is mapped (-p 13000:13000). Check logs: docker logs remote.

Breakpoints don't hit Ensure you are setting breakpoints in the source files and that the configuration uses request: "launch" (not "attach"). With launch, codelldb starts the program itself.

Source files not found in VSCode The sourceMap in launch.json must map /project to your local workspace folder. If you opened the repo root instead of common/project/, adjust the mapping: "sourceMap": { "/project": "${workspaceFolder}/common/project" }.

Can't reconnect after ending a session The entrypoint restarts codelldb automatically. Wait ~1 second after terminating a session before starting a new one.

6.1 KiB Raw Permalink Blame History