How to Upgrade PHP in Docker Containers Safely
In this article11 sections
With Docker, the PHP version is not a property of the server. It is a line in a file. That makes upgrades unusually safe: you build a new image with the new version, test it next to the running one, switch traffic, and keep the old image as the rollback. There is no repository to add, no module to switch and no shared configuration to break. The risk moves to different places: extensions you install in the image, files you mount into the container, and an image tag that quietly changes under you. This guide shows how to upgrade PHP in Docker, for Apache and for PHP-FPM images, how to build and test the new image, how to switch with Docker Compose, and how to keep it reproducible.
It applies to a SiteHarbour VPS or any host that runs Docker. If Docker is not installed yet, start with how to install Docker on Ubuntu 24.04 safely, which also explains why Docker’s published ports can bypass your firewall.
Understand the two common image types
The official php images come in several variants. Two matter for websites:
php:8.4-apachecontains PHP and Apache in one container. It is the simplest to run: one container serves the site.php:8.4-fpmcontains only PHP-FPM, and a separate web server container, such as Nginx, sends it requests on port 9000. It matches how a LEMP server works, and it is the usual choice for larger setups.
Alpine variants, such as php:8.4-fpm-alpine, are smaller, but they use a different C library, and some extensions behave differently on them. Use the Debian-based images unless image size matters to you, and test whichever you choose.
Before you start
- Back up the data that lives outside the image: database dumps and mounted upload folders. Containers are replaceable, data is not.
- Look at what you run now. Open the Dockerfile and the Compose file, and note the base image tag, the extensions installed, and the volumes mounted:
docker compose config
docker compose exec php php -v
docker compose exec php php -m | sort > php-modules-before.txt
Expected: the resolved configuration, the current version and a saved extension list. Run the compatibility checks in how to check your code for PHP compatibility before you upgrade before you change the tag.
Step 1: Pin the version instead of using a moving tag
An image tag such as php:8-fpm or php:latest moves to a new minor version whenever you rebuild, which means an unplanned upgrade. Use a tag that names the minor version, such as php:8.4-fpm, which still receives patch releases but not a new minor version. For strict reproducibility in production, pin the image digest as well, and update it on purpose.
Step 2: Change the base image and keep the extensions
In the Dockerfile, change the first line. Then check each extension install, because the way you add them depends on the image:
FROM php:8.4-fpm
RUN apt-get update && apt-get install -y --no-install-recommends \
libzip-dev libpng-dev libjpeg-dev libicu-dev libonig-dev \
&& docker-php-ext-configure gd --with-jpeg \
&& docker-php-ext-install -j"$(nproc)" pdo_mysql mysqli gd intl zip mbstring bcmath opcache \
&& rm -rf /var/lib/apt/lists/*
The helper scripts docker-php-ext-install and docker-php-ext-configure build extensions that ship with PHP. Extensions that do not ship with PHP, such as Redis or Imagick, come from PECL with pecl install and docker-php-ext-enable, and not every extension has a release for the newest PHP the day it appears. Check that each one supports the version before you build.
Step 3: Build the new image and test it beside the old one
Build with a new tag, so the running image is untouched:
docker build -t myapp-php:8.4 .
docker run --rm myapp-php:8.4 php -v
docker run --rm myapp-php:8.4 php -m | sort > php-modules-after.txt
diff php-modules-before.txt php-modules-after.txt
Expected: the new version, and either no difference or differences you can explain. A missing extension in the diff is the most common cause of failure after an upgrade, and you find it here, before any visitor does.
Run the application’s test suite inside the new image, and start a second copy of the site on a different port with the same database or a copy of it. Use the copy for any test that writes data. Click through the site with error display on, and read the logs.
Step 4: Check the PHP configuration files
Official images ship with no php.ini, only two templates, php.ini-development and php.ini-production, in /usr/local/etc/php/. Start from the production one, and add your own overrides as small files in /usr/local/etc/php/conf.d/, which are read in order. Mount or copy them in:
COPY docker/php.ini /usr/local/etc/php/conf.d/99-app.ini
Put only your own values in it, such as memory_limit, upload_max_filesize, post_max_size and OPcache settings. This keeps your changes visible, and a new PHP version brings its own defaults for everything else. Check the FPM pool in /usr/local/etc/php-fpm.d/ if you changed process counts, and size them from memory you measure, as in how to optimize PHP-FPM workers on limited RAM.
Step 5: Switch with Docker Compose
Update the service in compose.yaml to use the new image, or build it from the changed Dockerfile:
services:
php:
build: .
image: myapp-php:8.4
restart: unless-stopped
volumes:
- ./app:/var/www/html
- uploads:/var/www/html/storage/uploads
Then deploy it:
docker compose build php
docker compose up -d php
docker compose logs --tail=50 php
Expected: the container starts without errors, and the log shows PHP-FPM ready to handle connections. Reload the web server container if it caches the upstream address, and check the site. With depends_on and health checks in the Compose file, services start in the right order.
Step 6: Fix file ownership
A new image may run PHP as a different user than the old one, and the mounted files then become unwritable. Check the owner that PHP-FPM runs as, normally www-data, and the owner of the mounted folders:
docker compose exec php id
docker compose exec php ls -ln /var/www/html/storage
Expected: the user ID of the PHP process matches the owner of the folders it writes to. A mismatch shows up as uploads that fail or logs that cannot be written. Fix it with chown on the host, or set the container’s user ID to match.
Step 7: Keep the rollback ready
Do not delete the old image. To roll back, change the tag in compose.yaml to the old one and run docker compose up -d php. The old container starts in seconds, with the old PHP and the same mounted data. A rollback does not undo database changes, so restore the dump if the new version caused a migration.
Once the new version has run cleanly for a week, remove the old image with docker image rm, and prune build cache from time to time with docker builder prune.
Common mistakes
- Using a moving tag. A rebuild upgrades you without telling you.
- Forgetting to rebuild the extensions. The new image has none of the old image’s extra extensions unless the Dockerfile installs them.
- Building as root and running as another user. Mounted files become unwritable.
- Testing against the live database. Use a copy for tests that write.
- Not scanning the image. Rebuild regularly to pick up fixes in the base image, and check the result with an image scanner.
Frequently asked questions
Do I need to stop the site to upgrade?
A short restart of the PHP container is usually all that is needed. For zero downtime, run the new container beside the old one and switch the web server’s upstream.
Are Alpine images safe to use?
Yes, but they use a different C library, and some extensions behave differently. Test thoroughly, or use the Debian images.
How do I upgrade a PHP application that runs in Kubernetes?
The idea is the same: build and test a new image tag, then roll it out with a rolling update, and keep the previous tag for rollback.
Where does the data live?
In volumes and bind mounts, not in the container. The container can be replaced at any time, and the data stays.
In Docker, a PHP upgrade is a tag change you can test completely before it touches a visitor. Pin the minor version, keep your extensions in the Dockerfile, build and test the new image beside the old one, keep your own settings in a small override file, check file ownership, and keep the old image as the rollback. For the same job on a classic server, read how to upgrade PHP on Ubuntu with Nginx and PHP-FPM.
Want this done for you? If you would rather have an engineer plan and carry out the work on your own site, you can hire the author through the Upwork profile of Munaf Sheikh.