How to add xdebug to php:8.1-fpm-alpine Docker container?

Asked 24/7, 2022 at 9:39 Answered 25/7, 2022 at 5:17

docker docker-compose phpunit xdebug xdebug-3

I have this dockerfile for my phpunit container:

FROM php:8.1-fpm-alpine

WORKDIR /var/www/html

RUN apk add --no-cache --repository http://dl-cdn.alpinelinux.org/alpine/edge/community/ --allow-untrusted gnu-libiconv
ENV LD_PRELOAD /usr/lib/preloadable_libiconv.so php

ENV PHP_MEMORY_LIMIT=1G
ENV PHP_UPLOAD_MAX_FILESIZE: 512M
ENV PHP_POST_MAX_SIZE: 512M

RUN docker-php-ext-install pdo

RUN apk add --no-cache libpng libpng-dev && docker-php-ext-install gd && apk del libpng-dev

RUN apk update \
    && apk upgrade \
    && apk add --no-cache \
        freetype \
        libpng \
        libjpeg-turbo \
        freetype-dev \
        libpng-dev \
        jpeg-dev \
        libwebp-dev \
        libjpeg \
        libjpeg-turbo-dev

RUN docker-php-ext-configure gd \
        --with-freetype=/usr/lib/ \
        --with-jpeg=/usr/lib/ \
        --with-webp=/usr

RUN NUMPROC=$(grep -c ^processor /proc/cpuinfo 2>/dev/null || 1) \
    && docker-php-ext-install -j${NUMPROC} gd


RUN apk add --no-cache sqlite-libs
RUN apk add --no-cache icu sqlite git openssh zip
RUN apk add --no-cache --virtual .build-deps icu-dev libxml2-dev sqlite-dev curl-dev
RUN docker-php-ext-install \
        bcmath \
        curl \
        ctype \
        intl \
        pdo \
        pdo_sqlite \
        xml
RUN apk del .build-deps

RUN docker-php-ext-enable pdo_sqlite

RUN apk add php81-pecl-xdebug
RUN docker-php-ext-enable xdebug

And the output is:

Step 19/22 : RUN apk add php81-pecl-xdebug
 ---> Using cache
 ---> 2108d3d7b95d
Step 20/22 : RUN docker-php-ext-enable xdebug
 ---> Running in 443d625bb28d
error: 'xdebug' does not exist

usage: /usr/local/bin/docker-php-ext-enable [options] module-name [module-name ...]
   ie: /usr/local/bin/docker-php-ext-enable gd mysqli
       /usr/local/bin/docker-php-ext-enable pdo pdo_mysql
       /usr/local/bin/docker-php-ext-enable --ini-name 0-apc.ini apcu apc

Possible values for module-name:
bcmath.so ctype.so curl.so gd.so intl.so opcache.so pdo.so pdo_sqlite.so sodium.so xml.so

Some of the above modules are already compiled into PHP; please check
the output of "php -i" to see which modules are already loaded.
ERROR: Service 'phpunit' failed to build: The command '/bin/sh -c docker-php-ext-enable xdebug' returned a non-zero code: 1

What is the problem here? As I see the xdebug package has benne installed successfully and the docker-php-ext-enable xdebug command still not see the xdebug extension.

I checked it with php -i and the xdebug isn't listed there.

How can I solve this issue?

Vasta answered 24/7, 2022 at 9:39 Comment(0)

Thanks for ArmiMousavi & Derick's help here is a working final configuration. I just exploded one liner command to separated RUN to debug build issues.

FROM php:8.1-fpm-alpine

WORKDIR /var/www/html

RUN apk add --no-cache --repository http://dl-cdn.alpinelinux.org/alpine/edge/community/ --allow-untrusted gnu-libiconv
ENV LD_PRELOAD /usr/lib/preloadable_libiconv.so php

ENV PHP_MEMORY_LIMIT=1G
ENV PHP_UPLOAD_MAX_FILESIZE: 512M
ENV PHP_POST_MAX_SIZE: 512M

RUN docker-php-ext-install pdo

RUN apk add --no-cache libpng libpng-dev && docker-php-ext-install gd && apk del libpng-dev

RUN apk update \
    && apk upgrade \
    && apk add --no-cache \
        freetype \
        libpng \
        libjpeg-turbo \
        freetype-dev \
        libpng-dev \
        jpeg-dev \
        libwebp-dev \
        libjpeg \
        libjpeg-turbo-dev

RUN docker-php-ext-configure gd \
        --with-freetype=/usr/lib/ \
        --with-jpeg=/usr/lib/ \
        --with-webp=/usr

RUN NUMPROC=$(grep -c ^processor /proc/cpuinfo 2>/dev/null || 1) \
    && docker-php-ext-install -j${NUMPROC} gd


RUN apk add --no-cache sqlite-libs
RUN apk add --no-cache icu sqlite git openssh zip
RUN apk add --no-cache --virtual .build-deps icu-dev libxml2-dev sqlite-dev curl-dev
RUN docker-php-ext-install \
        bcmath \
        curl \
        ctype \
        intl \
        pdo \
        pdo_sqlite \
        xml
RUN apk del .build-deps

RUN docker-php-ext-enable pdo_sqlite

# Add xdebug
RUN apk add --no-cache --virtual .build-deps $PHPIZE_DEPS
RUN apk add --update linux-headers
RUN pecl install xdebug-3.1.5
RUN docker-php-ext-enable xdebug
RUN apk del -f .build-deps

# 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

Vasta answered 25/7, 2022 at 5:17 Comment(3)

You're still hard coding Xdebug's version (3.1.5), and writing your log to a web-server readable location (/var/www.... You probably should also use port 9003 (the default), as that would never conflict with PHP-FPM, which also uses 9000 by default. – Teenybopper 25/7, 2022 at 7:39

alright, so the default port is good enough by default. The /var/www... directory isn't relevant for me, because it's running only on github action, not on a live server. Finally the fixed version number is better than a fluid one, because I can be sure it's working in my environment. – Vasta 25/7, 2022 at 8:26

AWESOME!!! You saved life! – Brimful 5/7, 2023 at 14:15

try this one and remove :

RUN apk add php81-pecl-xdebug
RUN docker-php-ext-enable xdebug

and instead replace with:

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

and then:

# 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

and then let me know about the result

Elouise answered 24/7, 2022 at 12:50 Comment(8)

I upgraded to this command pecl install xdebug-3.2.0alpha1 because of php8.1 isn't compatible with xdebug 3.0.0, and now the result is

ERROR: Service 'phpunit' failed to build: The command '/bin/sh -c pecl install xdebug-3.2.0alpha1' returned a non-zero code: 1

– Vasta 24/7, 2022 at 13:10

please provide more info not just last line. for example the above error was "error: 'xdebug' does not exist" . Is it still this one? – Elouise 24/7, 2022 at 13:20

configure: error: rtnetlink.h is required, install the linux-headers package: apk add --update linux-headers ERROR: /tmp/pear/temp/xdebug/configure --with-php-config=/usr/local/bin/php-config' failed ERROR: Service 'phpunit' failed to build: The command '/bin/sh -c pecl install xdebug-3.2.0alpha1' returned a non-zero code: 1 ` – Vasta 24/7, 2022 at 13:21

sorry, but in comments isn't so much possibility to present more detailed report... do you have any suggestion? – Vasta 24/7, 2022 at 13:23

ok try to add "apk add --update linux-headers" before them – Elouise 24/7, 2022 at 13:27

It is not good advice to use xdebug-3.0.0 — you really want to use the latest stable release. Doing pecl install xdebug should get you the latest stable version (which is supported by PHP 8.1: xdebug.org/docs/compat – Teenybopper 24/7, 2022 at 13:45

And also do what the error messages tells you to: apk add --update linux-headers – Teenybopper 24/7, 2022 at 13:46

echo "xdebug.log=/var/www/html/xdebug/xdebug.log" - is also bad advice, you don't want your log files to be readable through your web server – Teenybopper 24/7, 2022 at 13:51

Recommended topics

Hot tags