Building and Publishing Custom Docker Images for PHP Applications

5 min readUpdated on

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:

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

bash
docker login

Enter your Docker Hub username and a personal access token (Account settings, Security) when prompted.

4. Build Your Image

bash
docker build -t username/php:8.4-fpm -f ./Dockerfile .

5. Push Your Image to Docker Hub

bash
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:

yaml
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.

Source Code

Related articles

Existing system support

Need help with a live application?

I help companies improve live systems, clean up delivery workflows, and ship new features without adding avoidable complexity.

Comments (0)
Sign in to leave a comment

You need to be signed in to add a comment.

Login

Need someone to take responsibility for the next step?

Let’s talk about your project and define a scope that actually makes sense for your goals.