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.

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

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

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

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

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 (eg, 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