Skip to content

Customizing Docker Images

Customizing Docker Images

It's common to have a requirement for the web or db images which is not bundled in them by default. There are two easy ways to extend these docker images:

  • webimage_extra_packages and dbimage_extra_packages in .ddev/config.yaml
  • An add-on Dockerfile in your project's .ddev/web-build or .ddev/db-build

Adding extra Debian packages with webimage_extra_packages and dbimage_extra_packages

You can add extra Debian packages if that's all that is needed with lines like this in .ddev/config.yaml:

webimage_extra_packages: [php-yaml, php7.3-tidy]
dbimage_extra_packages: [telnet, netcat]

Then the additional packages will be built into the containers during ddev start

How to figure out what packages you need

The web container is a Debian 10 Buster image, and its PHP distributions are packaged (thank you!) by

If you need a PHP extension, most PHP extensions are built in the distribution. You can google the extension you want, or download and search the Packages list from the sury distribution. For example, the "bcmath" PHP extension is provided by "php-bcmath". Many packages have version-specific names, for example php7.3-tidy.

If you need a package that is not a PHP package, you can view and search standard Debian packages at, or just use google.

To test that a package will do what you want, you can ddev ssh and then sudo apt-get update && sudo apt-get install <package> to verify that you can install it and you get what you need. A php extension may require killall -USR2 php-fpm to take effect. After you've tried that, you can add the package to webimage_extra_packages.

Adding extra Dockerfiles for webimage and dbimage

For more complex requirements, you can add .ddev/web-build/Dockerfile or .ddev/db-build/Dockerfile.

Examples of possible Dockerfiles are given in .ddev/web-build/Dockerfile.example and .ddev/db-build/Dockerfile.example (These examples are created in your project when you ddev config the project.)

You can use the .ddev/*-build/ directory as the Docker "context" directory as well. So for example if a file named README.txt exists in .ddev/web-build, you can use ADD README.txt / in the Dockerfile.

An example web image .ddev/web-build/Dockerfile might be:

RUN npm install --global gulp-cli

Another example would be changing the installed nodejs version to a preferred version, for example nodejs 12:

# Install whatever nodejs version you want
RUN sudo apt-get remove -y nodejs
RUN curl -sSL --fail${NODE_VERSION}.x | bash -
RUN apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y -o Dpkg::Options::="--force-confold" --no-install-recommends --no-install-suggests nodejs

Remember that the Dockerfile is building a docker image that will be used later with ddev. At the time the Dockerfile is executing, your code is not mounted and the container is not running, it's just being built. So for example, an npm install in /var/www/html will not do anything useful because the code is not there at image building time.

Last update: 2021-10-16