How do I install XDebug on docker's official php-fpm-alpine image?

Question

I'm using wordpress:php7.1-fpm-alpine which is based on php:7.1-fpm-alpine (https://github.com/docker-library/wordpress/blob/master/php7.1/fpm-alpine/Dockerfile).

I've tried RUN pecl install xdebug-2.5.0 && docker-php-ext-enable xdebug

which results in an error when building:

Step 19/19 : RUN pecl install xdebug-2.5.0     && docker-php-ext-enable xdebug
 ---> Running in 52c988e12cb2
downloading xdebug-2.5.0.tgz ...
Starting to download xdebug-2.5.0.tgz (267,640 bytes)
........................................................done: 267,640 bytes
76 source files, building
running: phpize
Configuring for:
PHP Api Version:         20160303
Zend Module Api No:      20160303
Zend Extension Api No:   320160303
Cannot find autoconf. Please check your autoconf installation and the
$PHP_AUTOCONF environment variable. Then, rerun this script.

Elodia

Did the solution offered at github.com/docker-library/wordpress/issues/244 work? – Ferrel

Well I don't really think that is the complete solution. I would need to determine all the dependencies. – Elodia

Answer 1

The following is sufficient for simply installing xdebug on that image:

FROM wordpress:php7.1-fpm-alpine

RUN apk add --no-cache $PHPIZE_DEPS \
    && pecl install xdebug-2.5.0 \
    && docker-php-ext-enable xdebug

Building that and then running from a shell inside the resulting image produces the following:

$ php -i | grep Xdebug
    with Xdebug v2.5.0, Copyright (c) 2002-2016, by Derick Rethans

Sackville

If you use a non-Alpine-based base image, use apt instead of apk, e.g. RUN apt -qy install $PHPIZE_DEPS && pecl install xdebug-2.5.0 && docker-php-ext-enable xdebug – Menander

in my case it runs perfectly with CLI, but won't run with FPM. Hence the php -i doesn't give the whole picture. I'm still trying to figure it out, if anybody has an advice. – Tref

I hate that phpize and $PHPIZE_DEPS are never mentioned in the docker hub page. – Shriner

For people using php:7.3-fpm-alpine and up, remember to remove the "-2.5.0" from the xdebug package. So instead of putting in install xdebug-2.5.0, you put in install xdebug – Mistook

Instead of removing 2.5.0, I'd suggest updating it to 3.0.4 (pecl.php.net/package/xdebug) so you still know which version you're getting and have an explicit place to create a natural cache bust when you need/want to update it. – Sackville

Answer 2

If you are concerned about image size you can remove the dependencies:

FROM wordpress:php7.1-fpm-alpine 
RUN apk --update --no-cache add autoconf g++ make && \
    pecl install -f xdebug && \
    docker-php-ext-enable xdebug && \
    apk del --purge autoconf g++ make

Millicentmillie

Wonderful answer. – Trinidad

Answer 3

Great answer @msanchez_aplyca. Although more correctly removing the build dependancies via apk would be:

RUN apk add --no-cache --virtual .build-deps $PHPIZE_DEPS \
    && pecl install xdebug-2.5.0 \
    && docker-php-ext-enable xdebug \
    && apk del -f .build-deps

Overtask

Answer 4

For PHP >= 7.2 you need to use Xdebug 2.6.0+

For example, install the Xdebug 3.0.0 (released on the 25th November 2020)

Compatible with PHP 8.0

RUN apk add --no-cache --virtual .build-deps $PHPIZE_DEPS \
    && pecl install xdebug-3.0.0 \
    && docker-php-ext-enable xdebug \
    && apk del -f .build-deps

Now you set it up by adding something like (using Xdebug 3.0.0 syntax, more info here):

# Configure Xdebug
RUN echo "xdebug.start_with_request=yes" >> /usr/local/etc/php/conf.d/xdebug.ini \
    && echo "xdebug.mode=debug" >> /usr/local/etc/php/conf.d/xdebug.ini \
    && echo "xdebug.log=/var/www/html/xdebug/xdebug.log" >> /usr/local/etc/php/conf.d/xdebug.ini \
    && echo "xdebug.discover_client_host=1" >> /usr/local/etc/php/conf.d/xdebug.ini \
    && echo "xdebug.client_port=9000" >> /usr/local/etc/php/conf.d/xdebug.ini

Miraculous

Answer 5

xdebug can be installed via apk, but it takes some tweaking

Determine your PHP extension and config directories

1. Copy the output of php -i to your clipboard.
2. Go to the xdebug Installation Wizard and paste the results in the box.
3. Keep this output handy, as we'll need it later. We are mainly concerned with Extra Configuration Files Path and Extensions directory. Sample xdebug installation wizard output

Figure out where the apk package is being installed

Your results may vary depending on the version you select.

You can find available versions by reviewing the xdebug documentation. As of this writing, only the major PHP releases are listed, but I was able to manually specify a feature release. Just don't include the dot (e.g., 81 NOT 8.1).

Run apk info -a php<your-php-version>-pecl-xdebug to get the contents of the package.

According to the output of apk info -a php81-pecl-xdebug, my locations were:

php81-pecl-xdebug-3.1.5-r0 contains:
etc/php81/conf.d/50_xdebug.ini
usr/lib/php81/modules/xdebug.so

Create your xdebug configuration

I like to keep my xdebug.ini inside my VS Code .devcontainer folder, so that's the route I'll follow for this example. You can also create the configuration file directly in its destination.

If you take the latter path, name the file 99-xdebug.ini per the documentation.

In either case, all you really need is this line to enable xdebug.

zend_extension=xdebug

Additional options are needed to make it do anything useful, but I'll leave that to the reader.

Create your Dockerfile

In your dockerfile, install the package and link/copy the files according to the previous steps. For example:

ADD <local_xdebug.ini_path> <PHP Extra Configuration Files Path>99-xdebug.ini
RUN apk update && apk add php<version>-pecl-xdebug && \
    ln -s /<apk_xdebug.so_path> \
    <PHP Extensions directory>

In my case:

ADD ./xdebug.ini /usr/local/etc/php/conf.d/99-xdebug.ini
RUN apk update && apk add php81-pecl-xdebug && \
    ln -s /usr/lib/php81/modules/xdebug.so \
    /usr/local/lib/php/extensions/no-debug-non-zts-20210902/xdebug.so

Rebuild the container and verify xdebug is enabled

After rebuilding the container, verify that the xdebug module is installed by running php -m

I'm a PHP dummy, so I used the xdebug Installation Wizard as before to verify xdebug was enabled.

Hopefully this saves someone else a couple frustrating hours.

xdebug installed

Fillian

Answer 6

Dockerfile

# Install minimal packages to build Xdebug
RUN apt-get install -y libpng-dev libzip-dev git
RUN docker-php-ext-install zip

# Install Xdebug from source
RUN git clone -b XDEBUG_2_5_5 https://github.com/xdebug/xdebug.git /root/xdebug \
&& cd /root/xdebug && ./rebuild.sh

# xDebug
RUN echo 'zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20131226/xdebug.so' >> $PHP_INI_DIR/conf.d/docker-php-ext-xdebug.ini \
    && echo "xdebug.remote_handler=dbgp" >> $PHP_INI_DIR/conf.d/docker-php-ext-xdebug.ini \
    && echo "xdebug.remote_port=9001" >> $PHP_INI_DIR/conf.d/docker-php-ext-xdebug.ini \
    && echo "xdebug.remote_connect_back=0" >> $PHP_INI_DIR/conf.d/docker-php-ext-xdebug.ini \
    && echo "xdebug.idekey=VSCODE" >> $PHP_INI_DIR/conf.d/docker-php-ext-xdebug.ini \ 
    && echo "xdebug.remote_enable=1" >> $PHP_INI_DIR/conf.d/docker-php-ext-xdebug.ini \
    && echo "xdebug.remote_autostart=1" >> $PHP_INI_DIR/conf.d/docker-php-ext-xdebug.ini \
    && echo "xdebug.remote_host=host.docker.internal" >> $PHP_INI_DIR/conf.d/docker-php-ext-xdebug.ini

Folder .vscode Create a launch.json file and place the code below:

{    
    "version": "0.2.0",
    "configurations": [
        {
            "name": "XDebug",
            "type": "php",
            "request": "launch",
            "hostname": "0.0.0.0",
            "port": 9001,
            "pathMappings": {
                "/var/www/html": "${workspaceFolder}"
            },
        },
    ]
}

If using a docker-compose.yml I recommend putting the extra_hosts, docker-compose.yml:

extra_hosts:
  - "host.docker.internal:host-gateway"

Ether