Port Forwarding for WSL2+Vscode, Docker Desktop with Wordpress+Xdebug3(+Certbot)

Quickly setup port fowarding for WSL2 to receive Xdebug signal within a Docker Container

Port Forwarding for WSL2+Vscode, Docker Desktop with Wordpress+Xdebug3(+Certbot)


Editor: VScode in WSL2
Development files: in WSL2
Docker: Docker Desktop v4.14.1(WSL2 based engine)
Windows 11 Home or Pro

Key Command(Powershell)

To allow xdebug data into WSL2 via port forwarding.
netsh interface portproxy set v4tov4 listenport=9003 listenaddress=WINDOWS_HOST_IP connectport=9003 connectaddress=$($(wsl hostname -I).Trim());




# xdebug.start_with_request = yes
xdebug.discover_client_host = 0

Potential Networking Issues

  • Windows Host IP could be either
    • via WSL HOST IP: 172.xxx (Windows11 Home)
    • via Internet IP: 192.xxx (Windows11 Pro)
  • Make sure port 9003 is not blocked by the Firewall

Browser Extension

  • Xdebug helper
    To trigger debug mode

or set xdebug.start_with_request = yes to debug on every request


for plugin development. For other usage, change the "pathMappings" accordingly.

  // Use IntelliSense to learn about possible attributes.
  // Hover to view descriptions of existing attributes.
  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
  "version": "0.2.0",
  "configurations": [
        "name": "Listen for Xdebug",
        "type": "php",
        "request": "launch",
        "port": 9003,
        "pathMappings": {
            "/var/www/html/wp-content/plugins/the-custom-plugin": "${workspaceRoot}",


Certbot Support for HTTPS environment

FROM wordpress:6.1.0-php8.1-apache

# Install packages under Debian
RUN apt-get update && \
    apt-get -y install git

# Install XDebug from source as described here:
# https://xdebug.org/docs/install
# Available branches of XDebug could be seen here:
# https://github.com/xdebug/xdebug/branches
RUN cd /tmp && \
    git clone https://github.com/xdebug/xdebug.git && \
    cd xdebug && \
    git checkout xdebug_3_1 && \
    phpize && \
    ./configure --enable-xdebug && \
    make && \
    make install && \
    rm -rf /tmp/xdebug

# Certbot
RUN apt update && \
    apt install python3 python3-venv libaugeas0 -y && \
    python3 -m venv /opt/certbot/ && \
    /opt/certbot/bin/pip install --upgrade pip && \
    /opt/certbot/bin/pip install certbot certbot-apache && \
    ln -s /opt/certbot/bin/certbot /usr/bin/certbot

# Run the following command to generate certificate
# docker exec CONTAINER certbot --apache --non-interactive --agree-tos --email $EMAIL --domains $DOMAINS

# Copy xdebug.ini to /usr/local/etc/php/conf.d/
COPY ./xdebug.ini /usr/local/etc/php/conf.d/

# Since this Dockerfile extends the official Docker image `wordpress`,
# and since `wordpress`, in turn, extends the official Docker image `php`,
# the helper script docker-php-ext-enable (defined for image `php`)
# works here, and we can use it to enable xdebug:
RUN docker-php-ext-enable xdebug