Xdebug 3 on GitPod with Apache

Question

I am trying to get Xdebug 3 to run on GitPod with Apache. Installation works well, also "Launch on currently open script".

The challenge is to connect Xdebug to the debug client. That seems to fail if one is just using xdebug.client_host = localhost, because of the Docker environment. Normally one would use xdebug.client_host = host.docker.internal, but simply declaring that does not work on GitPod.

Answer 1

With help on the Gitpod Discord, here is the solution. It is implemented in the repo on Github.

No changes or pathmappings in VScode needed. Default launch.json works.

Xdebug settings for "Listen to Xd" to be copied to Apache (e.g. /etc/php/8.2/apache2/conf.d/99-custom.ini)

xdebug.mode = debug
xdebug.start_with_request = yes
xdebug.discover_client_host=1

Xdebug settings for CLI to be copied (e.g. /etc/php/8.2/cli/conf.d/)

xdebug.mode = off
xdebug.start_with_request = yes

Docker caches the copy commands and this can lead to a lot of confusion when debugging. So I moved them to the .gitpod.yml, which also initializes the ports and installs the php-debug extension for VScode.

image:
  file: .gitpod.dockerfile
  context: .env
  
ports:
- port: 8080
  onOpen: open-preview
- port: 9003
  onOpen: ignore

tasks:
- name: Apache
  init: >
    sudo cp .env/xdebug_cli.ini /etc/php/8.2/cli/conf.d/99-custom.ini &&
    sudo cp .env/xdebug_web.ini /etc/php/8.2/apache2/conf.d/99-custom.ini
  command: >
    apachectl start &&
    multitail /var/log/apache2/access.log -I /var/log/apache2/error.log

vscode:
  extensions:
    - felixfbecker.php-debug

Answer 2

I think tmy2017/php-ddd-cargo-sample xdebug.ini shows some solution via docker run --add-host host.docker.internal:host-gateway, but I don't know how to implement this in my use case?

To implement this in your Gitpod setup, you might need to update the custom Docker image and incorporate a similar extra_hosts configuration.

.gitpod.dockerfile:

FROM gitpod/workspace-full:latest

# rest of your code

USER root
# Add extra_hosts configuration
RUN echo "extra_hosts:" >> /etc/docker/daemon.json && \
    echo "  - host.docker.internal:host-gateway" >> /etc/docker/daemon.json
USER gitpod

# rest of your code

That would include the extra_hosts configuration similar to the one in the docker-compose.yml from the provided GitHub commit.
That way, you can check if host.docker.internal can be resolved correctly within your Gitpod environment.