How I build my custom PHP image (dommin/php-8.4-fpm), publish it to Docker Hub and rebuild it from GitHub Actions.
Why Create Custom Docker Images?
I keep my own PHP image for three reasons: every developer and CI job gets the same PHP version and extensions, builds don't reinstall the common packages each time, and PHP is versioned independently of application code.
It is the dommin/php-8.4-fpm image from the earlier articles, with PHP 8.4, common extensions, Node.js and Composer.
Planning Your Custom PHP Image
Key Considerations:
Start from the Debian-based php:8.4-fpm. Decide which PHP extensions and system packages the apps need, which tools go in (Composer, Node.js, Git), and how to match file permissions between host and container (USER_ID/GROUP_ID).
Requirements Example:
For Laravel I need:
- PHP 8.4 with FPM
- Extensions: PDO, MySQL, PostgreSQL, GD, Zip, BCMath, Redis, etc.
- Composer
- Node.js and NPM
- Git for Composer dependencies
Building Your Custom PHP Image
The Dockerfile:
FROM php:8.4-fpm
ARG USER_ID=1000
ARG GROUP_ID=1000
RUN apt-get update && apt-get install -y --no-install-recommends \
git curl unzip zip \
libpng-dev libjpeg-dev libwebp-dev libfreetype6-dev \
libonig-dev libxml2-dev libzip-dev \
imagemagick libmagick++-dev \
libpq-dev \
autoconf g++ make \
supervisor \
rsync \
wget gnupg2 \
&& mkdir -p /etc/apt/keyrings \
&& curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg \
&& echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_22.x nodistro main" > /etc/apt/sources.list.d/nodesource.list \
&& apt-get update \
&& apt-get install -y nodejs \
&& pecl install redis imagick xdebug \
&& docker-php-ext-enable redis imagick xdebug \
&& docker-php-ext-configure gd --with-freetype --with-jpeg --with-webp \
&& docker-php-ext-install -j$(nproc) \
pdo_mysql pdo_pgsql mysqli \
zip bcmath pcntl intl \
gd opcache \
&& wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | gpg --dearmor -o /etc/apt/keyrings/google-chrome.gpg \
&& echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/google-chrome.gpg] https://dl.google.com/linux/chrome/deb/ stable main" > /etc/apt/sources.list.d/google-chrome.list \
&& apt-get update \
&& apt-get install -y google-chrome-stable \
&& apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
RUN groupmod -g ${GROUP_ID} www-data \
&& usermod -u ${USER_ID} -g www-data www-data \
&& mkdir -p /var/www /var/log/supervisor /var/run/supervisor \
&& chown -R www-data:www-data /var/www /var/log/supervisor /var/run/supervisor
COPY --from=composer:2 /usr/bin/composer /usr/bin/composer
WORKDIR /var/www
EXPOSE 9000
CMD ["php-fpm"]
Key Components Explained:
Node.js 22.x comes from NodeSource, Composer is copied from the official composer image, and USER_ID/GROUP_ID remap www-data to the host user. Besides the usual extensions, the image also installs Xdebug, Imagick, supervisor and Google Chrome. Xdebug is enabled by default, which slows every PHP request, so use this image for development and CI; for production build a slimmer image without Xdebug and Chrome. The Chrome repository is added with a signed keyring (apt-key is deprecated), and NodeSource the same way instead of piping a script into bash.
Publishing to Docker Hub
The image goes to Docker Hub.
1. Create a Docker Hub Account
If you haven't already, sign up for a Docker Hub account.
2. Create a Repository
Click "Create Repository" on the dashboard, name it (e.g. username/php) and set it public or private.
3. Log in to Docker Hub from CLI
docker login
Enter your Docker Hub username and a personal access token (Account settings, Security) when prompted.
4. Build Your Image
docker build -t username/php:8.4-fpm -f ./Dockerfile .
5. Push Your Image to Docker Hub
docker push username/php:8.4-fpm
6. Verify Your Upload
Visit your repository on Docker Hub to ensure your image was uploaded.
Automating Builds with GitHub Actions
A GitHub Actions workflow rebuilds and pushes the image on every push to main. It needs DOCKER_USERNAME and DOCKER_PASSWORD as repository secrets (use a Docker Hub access token, not your account password). Each build is also tagged with the commit SHA, so you can pin a project to an exact image instead of latest:
name: Build images
on:
push:
branches:
- main
env:
PHP_IMAGE: dommin/php-8.4-fpm:latest
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: docker/login-action@v3
with:
username: ${{ secrets.DOCKER_USERNAME }}
password: ${{ secrets.DOCKER_PASSWORD }}
- name: Build images
run: docker build -t $PHP_IMAGE -t dommin/php-8.4-fpm:${{ github.sha }} -f ./8.4-fpm/Dockerfile .
- name: Push images
run: docker push --all-tags dommin/php-8.4-fpm
Conclusion
The image is built from the Dockerfile above, published as dommin/php-8.4-fpm:latest and rebuilt by the workflow on every push to main.