Resolving PHP GD library issues in Drupal

Introduction

For a while now, one persistent issue has been bugging me: a warning on Drupal's 'status report' page that reads:

It was time to dig into the problem and resolve this warning once and for all.

When running Drupal in a Docker environment, you might encounter issues with image file support — one of the most common being the lack of JPEG and WebP support in the PHP GD library. This article outlines the steps I took to troubleshoot and finally resolve this issue, highlighting both the failed attempts and the final solution that worked.

The problem

Despite having the GD library installed, Drupal was still unable to process JPEG and WebP images — two widely used formats in web projects. The status report clearly indicated that while GIF and PNG were supported, JPEG and WEBP were not. This meant that any attempt to upload or manipulate images in these formats would fail. The challenge was to properly configure the GD library in the Docker environment to add support for these formats.

Initial Dockerfile setup

The project’s Docker setup was using a Dockerfile.base.local to build a custom PHP image. The initial Dockerfile looked something like this:

FROM {id-reference}.dkr.ecr.ap-southeast-2.amazonaws.com/php-apache:php8.2.12-apache2.4.56-bullseye
# Enable Apache modules
RUN set -ex; \
   if command -v a2enmod; then \
       a2enmod rewrite remoteip ;\
       { \
           echo RemoteIPHeader X-Forwarded-For ;\
           echo RemoteIPTrustedProxy 10.0.0.0/8 ;\
           echo RemoteIPTrustedProxy 172.17.0.0/24 ;\
           echo RemoteIPTrustedProxy 192.168.0.0/16 ;\
       } > /etc/apache2/conf-available/remoteip.conf;\
       a2enconf remoteip;\
   fi
# Install necessary PHP extensions
RUN apt-get update && apt-get install -y --no-install-recommends \
   zlib1g-dev \
   libpng-dev \
   libjpeg-dev \
   libwebp-dev \
   libpq-dev \
   libzip-dev \
   libxml2-dev \
   docker-php-ext-install gd && \
   docker-php-ext-configure gd --with-jpeg --with-webp
# Additional Dockerfile setup steps...

However, despite libjpeg-dev and libwebp-dev being installed and docker-php-ext-configure properly configured, Drupal still failed to recognise support for JPEG and WebP.

Troubleshooting the issue

Step 1: Verifying GD installation

I first confirmed that the GD extension was installed by running the following commands inside the Docker container:

php -m | grep gd
php -r 'var_dump(gd_info());'

The output showed that while the GD library was installed, it lacked support for both JPEG and WebP:

array(14) {
 ["GD Version"]=>
 string(26) "bundled (2.1.0 compatible)"
 ["FreeType Support"]=>
 bool(false)
 ["GIF Read Support"]=>
 bool(true)
 ["GIF Create Support"]=>
 bool(true)
 ["JPEG Support"]=>
 bool(false)
 ["PNG Support"]=>
 bool(true)
 ["WebP Support"]=>
 bool(false)
}

Step 2: Reconfiguring GD with Docker

Next, I tried reconfiguring the GD extension inside the Docker container using the following commands:

docker-php-ext-configure gd --with-jpeg=/usr/include --with-webp=/usr/include
docker-php-ext-install gd

Although this worked temporarily when run inside the container, the changes were not persistent across rebuilds. When running docker compose down and docker compose up, JPEG and WebP support would revert to false.

The solution

To ensure that the GD library was consistently configured with JPEG and WebP support during the Docker build process, I made the following adjustments to the Dockerfile

FROM {id-reference}.dkr.ecr.ap-southeast-2.amazonaws.com/php-apache:php8.2.12-apache2.4.56-bullseye
# Enable Apache modules and configure RemoteIPTrustedProxy for Apache
RUN set -ex; \
   if command -v a2enmod; then \
       a2enmod rewrite remoteip ;\
       { \
           echo RemoteIPHeader X-Forwarded-For ;\
           echo RemoteIPTrustedProxy 10.0.0.0/8 ;\
           echo RemoteIPTrustedProxy 172.17.0.0/24 ;\
           echo RemoteIPTrustedProxy 192.168.0.0/16 ;\
       } > /etc/apache2/conf-available/remoteip.conf;\
       a2enconf remoteip;\
   fi
# Copy the NetSkope CA Certificate
COPY ./nscacert.pem /etc/ssl/certs/nscacert.pem
RUN echo "openssl.cafile = /etc/ssl/certs/nscacert.pem" >> /usr/local/etc/php/php.ini
# Install necessary libraries and configure GD with JPEG and WebP support
RUN apt-get update && apt-get install -y --no-install-recommends \
   zlib1g-dev \
   libpng-dev \
   libjpeg-dev \
   libwebp-dev \
   libpq-dev \
   libzip-dev \
   libxml2-dev \
   msmtp \
   vim \
   curl \
   unzip \
   default-mysql-client && \
   docker-php-ext-configure gd --with-jpeg=/usr/include --with-webp=/usr/include && \
   docker-php-ext-install -j "$(nproc)" \
   gd \
   opcache \
   pdo_mysql \
   pdo_pgsql \
   zip \
   soap && \
   apt-get clean && rm -rf /var/lib/apt/lists/*
# Additional Dockerfile setup...

The key change here was ensuring that docker-php-ext-configure gd --with-jpeg=/usr/include --with-webp=/usr/include was included during the build process. This guarantees that the GD library is properly configured and compiled with support for both JPEG and WebP.

Rebuilding the Docker container

After making the changes, I rebuilt the Docker container using:

docker compose down
docker compose build --no-cache
docker compose up -d

Using --no-cache ensures that Docker rebuilds the image from scratch, applying all configuration changes.

Verifying the solution

Once the container was up and running, I verified that JPEG and WebP support were now enabled by running:

php -r 'var_dump(gd_info());'

This time, the output showed:

["JPEG Support"]=> bool(true)
["WebP Support"]=> bool(true)

Finally, I cleared the Drupal cache using drush cr to remove the warning message from the status report.

The wrap

Through trial and error, I was able to resolve the issue of missing JPEG and WebP support in Drupal’s GD library. By properly configuring the GD extension in the Dockerfile and ensuring the changes were persistent across container rebuilds, the problem was successfully resolved.

If you're encountering similar issues in your Docker-based Drupal environment, make sure that your Dockerfile properly configures and installs the GD extension with all necessary image format support. This will ensure that your Drupal site can handle various image formats without any hiccups.