Releases
Contributing
Repository layout, how to add a PHP version or a variable, and how to work on this documentation.
Repository layout
| Path | Purpose |
|---|---|
alpine/build.sh | Builds all images locally in dependency order. |
alpine/php-versions.txt | Pinned PHP release per supported minor. The single source of truth. |
alpine/check-php-versions.sh | Compares pins with the Alpine repositories and php.net; --update rewrites the file. |
alpine/base/ | Base image: Dockerfile, supervisord.conf, entrypoint-lib.sh, run-service, container-logs. |
alpine/php/ | PHP image: Dockerfile, php.ini.template, php-entrypoint.sh. |
alpine/php-nginx/ | Web image: Dockerfile, Nginx templates, www.conf.template, entrypoint, healthcheck.sh, Supervisor program configs. |
alpine/php-nginx-dev/ | Dev image: Dockerfile, Xdebug and no-cache templates, entrypoint. |
.github/workflows/docker-build.yml | Build, scan and publish pipeline. |
.github/workflows/php-version-bump.yml | Four-hourly PHP pin bump. |
.vex/openvex.json | VEX statements attached to every image. |
ENV.md, SECURITY.md, CLAUDE.md | Variable reference, CVE notes, and repository conventions. |
docs/ | This documentation site. |
Adding a PHP version
- Confirm Alpine edge has the packages:
docker run --rm alpine:3.24 apk search -x --repository=https://dl-cdn.alpinelinux.org/alpine/edge/community --repository=https://dl-cdn.alpinelinux.org/alpine/edge/testing php87. - Add a line to
alpine/php-versions.txt, for example8.7 8.7.0. - Build it locally:
./alpine/build.shor the single-image commands on Building locally. - Update the supported versions in
README.md,CLAUDE.mdand the Introduction page.
Everything else, from the CI matrix to the bump job, reads the file.
Adding a configuration variable
- Add the
ENVdefault to the relevant Dockerfile. - Reference it in the template (
php.ini.template,www.conf.templateor an Nginx template) or handle it in the entrypoint. - Document it in
ENV.md,README.mdand the environment variable reference.
If the setting is already expressible as php.<setting> or fpm.pool.<setting>, consider whether it needs a named variable at all.
Conventions
- Commit messages are short, plain, one-line summaries with no type prefixes.
- Every image must keep zero setuid binaries, zero Trivy CRITICAL or HIGH findings, and pass the smoke tests described in
CLAUDE.md. - Pin everything that can be pinned: actions by SHA, the base by digest, PHP by release.
- Templates must not write into
/etcat runtime; render into/run.
Working on this documentation
The site is a Nuxt 4 application in docs/, built with Nuxt UI and Nuxt Content and deployed as static assets on Cloudflare Workers.
cd docs
pnpm install
pnpm dev # http://localhost:3000
pnpm check # lint and typecheck
pnpm generate # static output in .output/public
Pages are Markdown files under docs/content/; folder and file prefixes control navigation order. Edit a page and the dev server reloads it. Cloudflare builds the docs directory on every push to main that touches it and can give each pull request a preview URL.