Upgrade guide

Watch the GitHub repository for releases (Watch → Custom → Releases) so you hear about changes whichever tag you use. Release notes for every version are on GitHub releases.

When images are rebuilt

Code merges into main and ships first as a beta pre-release. After testing, we publish a GitHub release, which builds every image and pushes it to Docker Hub and GitHub Packages. Two other triggers rebuild the floating tags between releases.

Floating and version-pinned tags

A tag that ends in a release version, such as -v5.0.5, is version-pinned. Every other tag floats.

For most projects, use a floating tag on a PHP minor version, such as 8.5-fpm-nginx. PHP stays on 8.5 while patches and OS updates arrive. Test a pulled image before it reaches production.

How specific the PHP version in a floating tag is changes what you get:

• 8-fpm-nginx follows the newest PHP 8.x minor.
• 8.5-fpm-nginx follows the newest 8.5.x patch.
• 8.5.12-fpm-nginx stays on PHP 8.5.12. It gets the weekly OS updates until 8.5.13 ships, then it is no longer rebuilt.

latest is the cli variation on the newest stable PHP. Don't use it for an app. Choosing an image lists every variation, operating system, and tag.

Apply your own security updates

Patch an image yourself when a CVE is disclosed after your version-pinned tag was released. Do the same on a floating tag when you need a fix before the next rebuild. Either way, extend our image in your own Dockerfile and test the result before you deploy it.

Update operating system packages

The images run as the unprivileged www-data user. Switch to root for the package manager, then back.

FROM serversideup/php:8.5-fpm-nginx-v5.0.5

USER root
RUN apt-get update \
    && apt-get upgrade -y \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* /usr/share/doc/*
USER www-data

FROM serversideup/php:8.5-fpm-nginx-alpine-v5.0.5

USER root
RUN apk update \
    && apk upgrade \
    && rm -rf /var/cache/apk/*
USER www-data

Update Composer

Every variation copies Composer from the official composer image. Copy a newer one over it the same way:

FROM serversideup/php:8.5-cli-v5.0.5

COPY --from=composer:2 /usr/bin/composer /usr/bin/composer

Replace composer:2 with an exact version such as composer:2.9.8 if you need reproducible builds.

PHP and OS versions we no longer build

We build an end-of-life PHP version while its official docker-library Dockerfile exists and the OS underneath still gets security updates. Once the OS is end of life too, a rebuild can't deliver patches. That's when we stop. The tags stay pullable but freeze at their last build. The full rule is in our security policy.

PHP 8.1 is end of life but still built on bookworm, trixie, and alpine3.22, because those bases still get security updates. It stops when they do.

If you're on a frozen tag, move to a supported PHP version and base from Choosing an image.

Installing packages on a frozen Bullseye image

Debian moved bullseye and bullseye-updates to archive.debian.org. The last copy of bullseye-security is only on snapshot.debian.org. Its release file has expired, so apt must skip the expiry check. This is the same approach docker-php-extension-installer uses. The recipe also installs a newer install-php-extensions, because the frozen images ship one from before that fix.

FROM serversideup/php:7.4-fpm-nginx

USER root

RUN printf '%s\n' \
      'deb http://archive.debian.org/debian bullseye main' \
      'deb http://archive.debian.org/debian bullseye-updates main' \
      'deb http://snapshot.debian.org/archive/debian-security/20260903T220410Z bullseye-security main' \
      > /etc/apt/sources.list \
    && printf 'Acquire::Check-Valid-Until "false";\n' > /etc/apt/apt.conf.d/99no-check-valid-until \
    && docker-php-serversideup-install-php-ext-installer 2.11.15

RUN docker-php-serversideup-dep-install-debian "mariadb-client" \
    && install-php-extensions intl

USER www-data

Once Debian publishes bullseye-security on archive.debian.org, replace the snapshot.debian.org line with deb http://archive.debian.org/debian-security bullseye-security main.

The Alpine 3.16 tags need no changes. Alpine keeps every past release on its mirrors, so apk add still works. The packages are just as unpatched.

Upgrade to a new major version

Floating tags always come from the newest major version. A major version has breaking changes. Read its page before you pull, or pin to the last release of your current major while you review:

• Upgrade to v5 from v4
• Upgrade to v4 from v3
• Upgrade to v3 from v2

Upgrade one major version at a time and work through each page in order.