Create a Custom PHP-FPM Container with MongoDB Support
Introduction
When developing a PHP website or application, you should always ensure that it is capable of dealing with high traffic once it goes into production. Here is where the Bitnami PHP-FPM container comes in. It bundles a PHP FastCGI implementation with some additional features such as adaptative process spawning, accelerated upload support, or functions for managing time-consuming tasks. These enhancements that make it ideal for busy sites.
On the other hand, you should choose a database capable of scaling and offering high-availability in highly-demanding scenarios. NoSQL solutions such as MongoDB have proven that are an effective choice in these cases.
This tutorial walks you through the process of using the Bitnami Docker PHP-FPM container as a base image to build a new one with the MongoDB extension already installed. Once the image is built, this guide will show you how to run the container to check the installation of the MongoDB extension.
Assumptions and prerequisites
This guide makes the following assumptions:
- You have basic knowledge of Docker containers.
- You have a Docker environment installed and configured. Learn more about installing Docker.
- You have a Docker Hub account. Register for a free account. (Optional).
Step 1: Create the project working directory
To begin the process, create a working directory for your container's code on your Docker host, as shown below:
cd ~
mkdir my-custom-php-fpm-container
cd my-custom-php-fpm-container
Step 2: Create a Dockerfile
A Dockerfile is similar to a recipe: it contains all the ingredients needed to create a Docker image. Typically, each line represents a separate step and begins with an instruction keyword followed by a series of arguments. Learn more about the Dockerfile format.
To create a PHP-FPM image that includes the MongoDB module, create a file named Dockerfile and fill it with the following content:
FROM bitnami/php-fpm:7.3-prod
RUN apt-get update && apt-get install -y autoconf build-essential
RUN pecl install mongodb
RUN echo "extension=mongodb.so" >> /opt/bitnami/php/etc/php.ini
Let's take a closer look at the steps in the build stages:
The FROM instruction kicks off the Dockerfile and specifies the base image to use. This example uses the Bitnami's PHP-FPM container for production as a base image. The RUN instruction executes a shell command. In this case, you can find three commands for the following actions:
- Update dependencies and install the autoconf package.
- Install the MongoDB extension.
- Include the MongoDB extension in the php.ini file.
Step 3: Build the Docker image
Once the Dockerfile is created, run the docker build command to build the image.
If you want to publish the Docker image (optional) add your Docker username account before the image name.
docker build -t my-custom-docker-php-fpm:latest .
This is an example of the output you should see during the build process:

This command creates an image named custom-docker-php-fpm, tagged as version latest. This tag uniquely identifies a Docker image, allowing you to deploy a specific version of the application if needed.
Once the build process is complete, use the docker images command to verify that the image was added to your local repository.
docker images | grep custom-docker-php-fpm
Step 4: Run the Docker image
Run your new Docker image in a container to test it with the docker run command.
docker run custom-docker-php-fpm &
To check if the container is running, execute the docker ps command. You should see an output similar to this:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
6250efbcdc87 custom-docker-php-fpm "php-fpm -F --pid /o…" 25 seconds ago Up 23 seconds vigilant_kapitsa
Step 5: Test the installation of the MongoDB extension
The last step is to test if the MongoDB extension has been correctly installed. To do so, it is necessary to access the container and run a set of commands. Follow these instructions:
- Access the container by running the docker exec command as it is shown below. Remember to replace the CONTAINER_ID placeholder with the id you have obtained running the docker ps command:
docker exec -it CONTAINER_ID bash
- With the command above, you will access the container as root. Execute the following to check if the MongoDB extension is present in your container:
php -m | grep mongo
You should see "mongodb" as the resulting output:

For additional information about what PHP modules and extensions are installed on your container you can run the php -m command. For extended information about each module such as version, directory, environment, etc., run the php -i command.
Step 6: Publish the Docker image (optional)
Now that your Docker image is built and contains all customizations, you can upload it into a public registry. This tutorial uses Docker Hub, but you can select one of your own choice, such as:
To upload the image to Docker Hub, follow the steps below:
- Log in to Docker Hub:
docker login
- Push the image to your Docker Hub account. Replace the DOCKER_USERNAME placeholder with the username of your Docker Hub account:
docker push DOCKER_USERNAME/my-custom-docker-php-fpm-container:latest
- Confirm that you see the image in your Docker Hub repositories dashboard.