There are quite some guides around to connect xdebug-docker to PHPStorm, or xdebug to netbeans... but not a lot regarding xdebug-docker and netbeans. After struggling I managed to find a way. Here is how.

Configuring docker

The Docker image must have xdebug installed. I use the following lines to do so:

FROM php:7.4-cli
[...]

RUN pecl channel-update pecl.php.net && pecl install xdebug-2.8.1 \
    && docker-php-ext-enable xdebug

Running the image

After building you docker image (above is just an extract, you may need many other things for your project), here is how I run it. And here is where I struggled most...

docker run \
  --name=project_name \
  -v /home/me/dev/project/xdebug.ini:/usr/local/etc/php/conf.d/xdebug.ini \
  -v /home/me/dev/project:/home/me/dev/project \
  --rm \
  --env XDEBUG_CONFIG=\"idekey=my-ide-key\" \
  --network=host \
  -ti my-docker-img bash

The first -v option is copying a local xdebug.ini file inside the docker, at a location it will be read by PHP. From my image inherited from FROM php:7.4-cli, I know the folder /usr/local/etc/php/conf.d/xdebug.ini will do.

This is a flexible way to play with parameters in your docker PHP config. Expect this will not work from the first time...

In my case this xdebug.ini file contains:

xdebug.remote_enable=on
xdebug.remote_autostart=off
xdebug.remote_host=127.0.0.1
xdebug.remote_log="/tmp/xdebug.log"
xdebug.idekey="my-ide-key"
xdebug.remote_port=9123

These are the required minimal configuration. I highly suggest to use a remote_log parameter, because if it fails, it's where you'll have valuable data.

The idekey will be used in Netbeans as well as the remote port.

The line -v /home/me/dev/project:/home/me/dev/project is also very important. Your project file names and directories inside your container must be the same as your host architecture. If not, Netbeans will stop but will be unable to show you the actual line.

The line --env XDEBUG_CONFIG=\"idekey=my-ide-key\" is kind of duplicate of the xdebug.ini configuration xdebug.idekey="my-ide-key"... This parameter needs (also?) to be an environment variable, so don't forget it.

The line --network=host is also very important. It means that the xdebug.remote_host=127.0.0.1 will also be the host IP. Otherwise, xdebug will be stuck inside your docker and unable to talk to the Host, where Netbeans sits.

In your docker, check your xdebug parameters are properly set by using the command php -i | grep xdebug. You will see such an output, reflecting your configuration (and the configuration used the next time you use the php command):

...
xdebug.remote_enable => On => On
xdebug.remote_handler => dbgp => dbgp
xdebug.remote_host => 127.0.0.1 => 127.0.0.1
xdebug.remote_log => /tmp/xdebug.log => /tmp/xdebug.log
xdebug.remote_log_level => 7 => 7
xdebug.remote_mode => req => req
...

If it looks OK, carry on, otherwise fix your config first.

Configuring Netbeans

This is the easier part. Go to Tools | Options | PHP | Debugging.

Make these parameters match the xdebug.ini config in your docker, as visible on the picture (fields Debugger Port and Session ID)

Launching your debugging session

In Netbeans, click on the following icon (or ctrl+F5):

Place a breakpoint somewhere in your application, as early as possible (or use the Stop at first line option provided by Netbeans, as visible in the screenshot above).

breakpoint (red square) set at line 63 here

In your docker launch a PHP command, like php bin/phpunit.

The command will stop, and Netbeans will be stop at the required line. BINGO!

The debugger stopped here (green arrow)

Basic debugger use

The most useful commands to me are the following one (step into, go to next instruction etc.)

And the Variables and Call Stack panels. You can display them from the Window | Debugging menu if they don't show up automatically.

Troubleshooting

Make sure your configuration is active

php -i | grep xdebug is a good start. If you don't run your project with the php command, be sure (by displaying a phpinfo() for example) that the xdebug.ini is applied, e.g. in a place which is considered by your PHP executable.

Read the logs

If you copied my documentation, there should be a logging file, inside your docker, at the location: /tmp/xdebug.log. Read that!

Check the xdebug.ini parameters match the Netbeans ones.

I am sure you checked it 10 times but who knows...