Why You Should Avoid Using the "official" Drupal Docker Image for Production Projects

Drupal

Docker

Share on

The "official" Drupal image on Docker Hub (https://hub.docker.com/_/drupal) includes the Drupal code in a given version, along with a consistent set of other necessary stack elements (Apache, general PHP extensions, etc.). While this solution may seem convenient at first glance, it has several major limitations for production use. Here’s why it’s better to avoid this approach and opt for a custom Docker image instead.

Problem #1: Missing Extensions

The official image does not include third-party libraries or specific PHP extensions your project might need. For example, it is impossible to install Drupal Commerce or any other module requiring extensions like bcmath (or zip).

Consequences:
- You will always need to create your own Docker image (via a custom `Dockerfile`) based on the official image, then install the missing dependencies (repos, PECL extensions, etc.). This adds a significant build step, whereas one would expect a "plug and play" solution.
- For companies with strict security policies (restricted internet access, use of an internal repository like Artifactory), this approach complicates maintenance. You must ensure internal version compatibility while relying on the choices made by the official Docker image.

Problem #2: Mixing Compatible Versions

The official Drupal image on Docker Hub combines two critical elements:
- The Drupal version (the provided core code).
- The PHP version (with unclear compatibility rules).

Problem:
- A Drupal version tag will provide the Apache/PHP stack in its latest compatible version.
- A PHP version tag will provide the Drupal code in its latest version compatible with that PHP version.

Result: It is impossible to choose both a specific Drupal version and a specific PHP version simultaneously. This constraint limits flexibility and can lead to incompatibilities.

Problem #3: Embedded Drupal Code

In a project, you typically don’t limit yourself to Drupal’s core code. You add modules, and in most cases, you use Composer to manage dependencies.

Example of a classic workflow:

FROM php:8.4-cli-alpine AS layer-composer
COPY --from=composer:2 /usr/bin/composer /usr/bin/composer
# Build the code
...

Then, the built code is copied into the Drupal layer:

FROM drupal:11.3-php8.4
COPY --from=layer-composer /drupal /opt/drupal

Major Risk:

The Docker COPY command is equivalent to `cp`. You therefore risk mixing two versions of Drupal:

• The code provided by the official image.
• Your code built via Composer.

Real-world case:

• You target a Drupal image for a specific PHP version.
• Your build layer focuses only on PHP, and you build Drupal version 10.
• The official image automatically includes the latest compatible version of Drupal (for example, version 11).
• If a file has changed location between versions (such as the MySQL driver), your deployment will fail.

Testimonial: This scenario cost me 3 hours of debugging and significant adjustments to the Dockerfile.

Problem #4: Limited Support

An all-in-one bundle may seem appealing, but when problems arise, resolution becomes more complex. Why?

• Fewer users = fewer shared experiences.
• Fewer documented solutions available online.

Conclusion: Opt for a Custom Docker Image

To avoid these pitfalls, build your own Docker image by following community best practices. Here is an example of an optimized structure:

# Build with Composer
FROM php:8.4-cli-alpine AS layer-composer
COPY --from=composer:2 /usr/bin/composer /usr/bin/composer
WORKDIR /drupal
COPY myapp/ ./
RUN composer install --no-dev --no-interaction --no-autoloader --no-scripts

# Build Node (for theme assets)

# FPM + Nginx with Supervisord
FROM php:8.4-fpm
# Install required PHP extensions
# Install Nginx and Supervisord
COPY --from=layer-composer /drupal /var/www/html
...

Why is this approach better?

• Full control over Drupal and PHP versions.
• Flexibility to add specific dependencies.
• Simplified maintenance aligned with community standards.

In summary: A custom Docker image, built step by step, will save you stability, security,

If you still want to use the official image:

Delete its content before copying your code to avoid conflicts:

FROM drupal:11.3-php8.4
RUN rm -rf /opt/drupal
COPY --from=layer-composer /drupal /opt/drupal

But take a look at https://www.drupal.org/docs/develop/local-server-setup/docker-with-solr-cloud-integration/docker-configuration before with a strong focus on this crystal clear message at the begining : 

Image