Set up Xdebug on a Docker Container with Centos 7, and PHP 7.3

July 26, 2020

On this post we are setting up a Docker Container for Centos 7 and PHP 7.3 with an installation of Xdebug.


If you compare this Dockerfile with our previous one for PHP 7.3 you will notice that we have included the php-devel package. This is required since we will be using pecl to install Xdebug, which will build, install and load it.

Additionally we will need to install the make package.

FROM centos:7

# Install Apache
RUN yum -y update
RUN yum -y install httpd httpd-tools

# Install EPEL Repo
RUN rpm -Uvh \
 && rpm -Uvh

# Install PHP
RUN yum --enablerepo=remi-php73 -y install php php-bcmath php-cli php-common php-gd php-intl php-ldap php-mbstring \
    php-mysqlnd php-pear php-soap php-xml php-xmlrpc php-zip php-devel

# Update Apache Configuration
RUN sed -E -i -e '/<Directory "\/var\/www\/html">/,/<\/Directory>/s/AllowOverride None/AllowOverride All/' /etc/httpd/conf/httpd.conf
RUN sed -E -i -e 's/DirectoryIndex (.*)$/DirectoryIndex index.php \1/g' /etc/httpd/conf/httpd.conf

# Required for Xdebug compilation
RUN yum -y install make

# Install Xdebug
RUN pecl install xdebug

# Add Xdebug to PHP configuration
RUN echo "" >> /etc/php.ini \
 && echo "[xdebug]" >> /etc/php.ini \
 && echo "zend_extension = /usr/lib64/php/modules/" >> /etc/php.ini \
 && echo "xdebug.remote_enable = 1" >> /etc/php.ini \
 && echo "xdebug.remote_autostart = 1" >> /etc/php.ini \
 && echo "xdebug.remote_host = host.docker.internal" >> /etc/php.ini


# Start Apache
CMD ["/usr/sbin/httpd","-D","FOREGROUND"]

You can also download this Dockerfile here

The Dockerfile also updates the /etc/php.ini file, by adding the following xdebug section:

zend_extension = /usr/lib64/php/modules/
xdebug.remote_enable = 1
xdebug.remote_autostart = 1
xdebug.remote_host = host.docker.internal

  • Note that we have specified host.docker.internal as the IP address of our host machine, instead of an actual IP address. That is a docker variable that will be translated into the IP address of the machine running the docker container.

Create the Docker Image and Container

Now we create the Docker Image.

docker build -t image_apache .

Then we create the Docker Container.

Notice that we need to indicate the path of our local folder that will be served as the root of the Apache Web Server, which in this example is /path_to/my_website. Replace it with the location of your site's root folder.

docker run -tid -p 4000:80 --name=container_apache -v /path_to/my_website:/var/www/html image_apache

After the Docker Container is created, you can go to the url http://localhost:4000 to open the local website.

Check Xdebug Installation

To check Xdebug has been correctly installed and configured, open a terminal window into the Docker Container with the following command:

docker exec -it container_apache bash

Then, on the terminal window inside the container, we will use the php -i instruction to get information about our PHP installation. We will also use the grep utility to display only the information relevant to Xdebug:

php -i | grep xdebug

You will see an output similar to this one (excerpts):

xdebug support => enabled
Support Xdebug on Patreon, GitHub, or as a business:
xdebug.auto_trace => Off => Off
xdebug.cli_color => 0 => 0


xdebug.remote_autostart => On => On
xdebug.remote_connect_back => Off => Off
xdebug.remote_cookie_expire_time => 3600 => 3600
xdebug.remote_enable => On => On
xdebug.remote_host => host.docker.internal => host.docker.internal
xdebug.remote_log => no value => no value




Check the Dockerfile on Github here.

Download the Image from Docker Hub here.