Contributing

Thanks for your interest in contributing to this project! Please use read this entire guide before submitting a pull request.

Improve the docs

Improving the docs is very easy. If you find a simple mistake, look at the bottom of the Table Of Contents section and click "Edit this page".

If you'd like to contribute bigger documentation changes, take a look at the /docs directory. Our entire site is available in that directory and you can see the process to easily install this on your machine by reading /docs/README.md.

Project dependencies

You must have these installed on your system.

• Docker (container engine): https://www.docker.com/products/docker-desktop

How things work

1. All files are stored in the /src folder
2. GitHub Actions will automatically build and deploy the images

Running things locally

To run a build, simply run ./scripts/dev.sh (with Docker Desktop running). This will show you a help menu with all the available options.

Example: Build a FPM-NGINX image running PHP 8.2.12 on Debian Bookworm

bash scripts/dev.sh --variation fpm-nginx --version 8.2.12 --os bookworm

This will build serversideup/php:8.2.12-fpm-nginx-bookworm locally on your machine for testing and inspection.

By default, local builds start from the official PHP image on Docker Hub, which is fast. CI compiles PHP from source instead (see How PHP is built). To build exactly what CI builds, add --build-php-base with a full patch version. Compiling PHP takes several minutes. The compiled base only exists in your local image store. It needs Docker's default builder and can't be combined with --push.

bash scripts/dev.sh --variation fpm-nginx --version 8.4.27 --os bookworm --build-php-base

Published Beta Images

We also have beta images that are published to our Docker Hub and GitHub Packages repositories.

⚙️ Variation	🚀 Version
cli	Debian Based Alpine Based
fpm	Debian Based Alpine Based
fpm-apache	Debian Based
fpm-nginx	Debian Based Alpine Based
frankenphp	Debian Based Alpine Based

Running a test web server:

Sometimes you need to just run a test web server locally to see if your changes work. Below is a good example on how to quickly do this.

docker run --rm -v $(pwd):/var/www/html -p 80:8080 -p 443:8443 serversideup/php:8.4-fpm-nginx

How PHP versions are selected for distribution

The file scripts/conf/php-versions-base-config.yml selects which PHP versions are built and the rules for each one, like base OS and default versions.

The scripts/get-php-versions.sh script downloads the latest active releases from PHP and merges them into a final file called scripts/conf/php-versions.yml. To pin a minor version to a specific patch (or hold back a bad release), list it under that minor's patch_versions in the base config. A pinned patch replaces the one from php.net.

The php-versions.yml file will include all final versions for tagging and building.

We generate our tags with a file called scripts/assemble-docker-tags.sh which handles all the advanced logic of compiling our tags together.

How PHP is built

We compile PHP from the php.net tarball with the same Dockerfiles that build the official PHP images. A security release can ship as soon as php.net publishes it, without waiting for the official images on Docker Hub. No step of the build depends on PECL.

For every PHP version, base OS, and upstream variant (cli, fpm, or zts), scripts/prepare-php-base.sh downloads docker-library/php at a pinned commit and changes only three things in its Dockerfile:

• The PHP version, download URL, and SHA256 are set to the patch we're building. The SHA256 comes from php.net, and the GPG signature check stays exactly as upstream runs it.
• The pecl update-channels call is removed, so a PECL outage can't fail the build.
• PHP_BUILD_PROVIDER names us, so php -v shows "Built by Server Side Up (https://serversideup.net/php)". We compile and ship these binaries, so PHP questions should come to us rather than docker-library.

The build phase compiles each base once and saves it to a private registry, then every variation is built on top of it. Bases are always compiled without the build cache. That way every run picks up the latest Debian and Alpine packages PHP links against, like curl, Brotli, and OpenSSL, without waiting for a new official image. The redis extension is built from its GitHub source for the same reason.

Release candidates work the same way. A version like 8.6-rc in the base config builds the newest release candidate on php.net's release candidates feed, from docker-library's 8.6-rc directory, so testers get each RC as soon as php.net publishes it.

Each variation names the docker-library variant it builds on with php_base (cli, fpm, or zts). When upstream changes its variants for a new PHP version, set php_base_overrides on that minor version. For example, docker-library builds every 8.6 image with ZTS and has no separate zts variant, so 8.6 sets frankenphp: cli.

PHP 8.1 is no longer on docker-library's master branch. Its entry in the base config sets docker_library_ref to the last commit that had it. Do the same for any other version docker-library drops.

All the scripts above are designed to run locally and in GitHub Actions. Feel free to execute these scripts to see the help menus and how they work.

GitHub Actions

We use GitHub Actions exclusively to publish all of our releases. If the image exists from DockerHub or GitHub Packages, it will never be published from a local machine.

See .github/workflows/action_publish-images-beta.yml for an example of how we publish our beta images.

Linting

Every pull request starts with a lint group that runs before any image is built: actionlint for the workflows, ShellCheck for the scripts, and hadolint for the Dockerfiles, plus fixture tests for the helper scripts in scripts/ that CI relies on. Run the same checks locally before you push:

docker run --rm -v "$PWD:/repo" -w /repo rhysd/actionlint:latest -color

docker run --rm -v "$PWD:/repo" -w /repo koalaman/shellcheck:stable --severity=warning \
  scripts/*.sh scripts/tests/*.sh src/common/usr/local/bin/* src/s6/usr/local/bin/* .oss-scanner/run-variation $(find src -path '*entrypoint.d*' -name '*.sh')

docker run --rm -v "$PWD:/repo" -w /repo hadolint/hadolint:latest hadolint src/variations/*/Dockerfile .oss-scanner/Dockerfile

bash scripts/tests/run.sh

The script tests live in one file, scripts/tests/run.sh, as plain assertions over a small set of sample images. CI runs the same file on a GitHub runner, whose jq and yq versions can differ from your machine, so a green run there is the one that counts.

The Depot runner labels we use are listed in .github/actionlint.yaml so actionlint recognizes them. New linters belong in .github/workflows/service_lint.yml.

What happens when you open a pull request

Every pull request that touches src/, scripts/, or the workflows builds the full image matrix for both amd64 and arm64. Jobs are grouped by variation, so you can see at a glance whether cli, fpm, fpm-apache, fpm-nginx, and frankenphp all build.

• Pull requests from forks are built on isolated builders and never leave them. Each build job also loads its amd64 image and runs the image tests against it, so a green check means your change builds everywhere and passes the tests on amd64. Fork builds can't save the compiled PHP base images, so they start from the official PHP images on Docker Hub instead. In the hours after a new PHP release, before Docker Hub has it, fork builds fail. Changes to how PHP is compiled are only tested when a maintainer runs the build for your PR.
• Pull requests from this repository go through the same three phases as a release: build, test, publish. Images are published to serversideup/php-dev with your PR number as the tag prefix (for example serversideup/php-dev:699-8.4-fpm-nginx-alpine) only after the image tests pass. A comment on the PR shows the status and the pull commands.
• Every run ends with a summary table listing each image with its compressed size per architecture, so a size regression is visible before merge.
• Nothing is published until it passes the image tests. Every build is saved to a private registry first. Every image is pulled from there on native amd64 and arm64 runners and checked: it starts, runs unprivileged, has no world-writable files or directories, reports the right PHP version, loads the default extensions, becomes healthy, and serves a PHP file through its web server. Only then is the exact same image promoted to Docker Hub, and the published digest is checked against the tested one, so what you pull is what was tested. If any image fails to build or fails its test, nothing from that run is published. You can run the same check locally with bash scripts/test-image.sh serversideup/php-dev:<tag>.
• Transient failures heal themselves. If a few jobs fail because a registry or mirror hiccupped, CI re-runs just those jobs once. If a release or weekly rebuild is still red after that, CI opens an issue for the maintainers with the failed jobs and their errors.
• Maintainers can publish a fork's images for testing by running the "Docker Publish (PR Images)" workflow manually with the PR number.

Dependency versions

Every version that ships in the image is pinned in scripts/conf/php-versions-base-config.yml. Most live under dependencies, where each key is passed to the Dockerfiles as a build arg of the same name. The NGINX version for each OS lives under operating_systems. PHP itself is the exception: its patch versions come from php.net at build time.

Renovate watches every pin and opens a pull request when a newer version is out. Its Dependency Dashboard issue lists each one with its current and available versions. The rules live in renovate.json.

To update a dependency by hand, edit its line in the base config. To add a new one, add a line under dependencies with a # renovate: comment above it. Then declare an ARG with the same name in each Dockerfile stage that uses it:

dependencies:
  # renovate: datasource=github-releases depName=just-containers/s6-overlay versioning=loose
  S6_VERSION: v3.2.3.2

A merged update reaches the published images with the next release.

NGINX versions

We install NGINX from the official NGINX repos. Renovate checks the package listings on nginx.org for each OS and updates the nginx_version lines in one pull request.

NGINX repository key verification

• Debian (APT): We import the official NGINX GPG key from https://nginx.org/keys/nginx_signing.key and verify it against a pinned fingerprint via the SIGNING_FINGERPRINT build arg.
• Alpine (APK): APK uses a raw RSA public key (nginx_signing.rsa.pub). We verify this key by pinning the SHA‑256 of the DER‑encoded public key via the SIGNING_ALPINE_RSA_PUB_SHA256 build arg. You can provide multiple comma‑separated hashes to support key rotation.

Compute the Alpine key hash when updating:

curl -sS https://nginx.org/keys/nginx_signing.rsa.pub -o /tmp/nginx_signing.rsa.pub

# macOS
openssl rsa -pubin -in /tmp/nginx_signing.rsa.pub -outform DER 2>/dev/null | shasum -a 256 | awk '{print $1}'

# Linux
openssl rsa -pubin -in /tmp/nginx_signing.rsa.pub -outform DER 2>/dev/null | sha256sum | awk '{print $1}'

Build with the new hash (optionally include the old hash during rotation)

docker build \
  --build-arg SIGNING_ALPINE_RSA_PUB_SHA256="<new-hash>,<old-hash>" \
  -f src/variations/fpm-nginx/Dockerfile .

Reference: Installing NGINX Open Source → Alpine packages.

Why allow multiple hashes? This is optional, but useful during a short rotation window:

• Ensure CI builds across branches/runners succeed while the upstream key change propagates.
• Avoid flakes from CDN/caching delays where some environments still see the old key.
• Let you pre-stage the new value before the official switch, then remove the old afterwards.

If you control all builds centrally and can update quickly, pass a single hash.

Helping out

If you're really eager to help out, here are a few places to get started:

• Help answer questions on our GitHub Discussions and our Discord
• Chime in on issues labeled "Help Wanted"
• Open a feature request and tell us how we can improve
• Run performance tests and share your results
• Say good things and tag us on X (formerly Twitter): @serversideup, @danpastori, @jaydrogers