| Path | Content |
|---|---|
template/ |
Shared Twig templates for the Dockerfiles: the layout, which writes the header, and the macros (source) |
docker/<image>/<tag>/Dockerfile.twig |
Per-image Twig template; the layout includes it, and it imports the macros it uses from template/Dockerfile/ (source) |
provisioning/ |
Scripts and configuration files copied into the images (source); conf/provision.yml says which go where. provisioning/baselayout holds the commands of /usr/local/bin (apt-install, docker-run-bootstrap, ...), which toolbox keeps under /baselayout for the other images |
docker/<image>/<tag>/Dockerfile, docker/<image>/<tag>/conf/ |
Generated by ci/console generate, never edited by hand |
ci/ |
PHP generators behind ci/console generate: the Dockerfiles (generate:dockerfile), their conf/ (generate:provision), .github/workflows/build.yaml (generate:github-ci) and the README banner (generate:readme-banner) |
ci/tests/ |
PHPUnit tests of ci/src; ci/tests/Fixtures/repository is a small repository they run against |
ci/grumphp.yml, ci/phpstan.neon, ci/rector.php, ci/fractor.php |
Checks of the PHP code in ci/, from pluswerk/grumphp-config |
conf/readme-banner.yml, ci/resources/readme-banner/ |
Texts and font outlines of the README banner (source) |
docs/assets/readme-banner-*.svg |
README banner, generated by ci/console generate:readme-banner, never edited by hand |
conf/dockerhub.yml |
Texts of the Docker Hub pages: per repository the short description, the introduction, the example and the links, or for an image that is no longer built the month of its last build and its replacement (source) |
docs/dockerhub/<repository>.md |
Docker Hub pages, generated by ci/console generate:dockerhub, never edited by hand; the job dockerhub-description in .github/workflows/build.yaml uploads them, see Building in CI |
ci/image-tests/ |
Image tests (PHPUnit): a test class per image in Images/, the checks as traits in Checks/; ci/console test:image runs them against a container of the image |
tests/ |
container-structure-test definitions run by the CI |
docs/ |
User documentation |
webdevops/php-official is a deprecated name of webdevops/php: the CI publishes the image of docker/php/<tag> under that name too, but only for the tags listed under docker: aliases in conf/console.yml. Do not add new tags there. The tags that are built are the -t "webdevops/..." lines in .github/workflows/build.yaml.
Only these commands are known to work:
make generateinstalls the PHP tools ofci/and runsci/console generateinwebdevops/php:8.4-alpine, which regeneratesdocker/,.github/workflows/build.yaml, the README banner and the Docker Hub pages. Run it after every change totemplate/,provisioning/,conf/or aDockerfile.twig, and commit the result; the CI fails if a generated file is out of date or missing.docker build -t webdevops/<image>:<tag> docker/<image>/<tag>builds one image; its parent andwebdevops/toolboxcome from local images or Docker Hub../build-local.sh [version]builds all PHP images of one version.make checkinstalls the PHP tools ofci/and checks the PHP code inci/with GrumPHP: coding standard, PHPStan, Rector,composer auditand the PHPUnit tests. Run it after every change toci/. GrumPHP and PHPStan only check files that Git knows (git ls-files), sogit addnew files first; PHPUnit runs every test anyway.make testruns only the tests. Changes toci/srccome with tests.make test-image IMAGE=webdevops/<image>:<tag>runs the image tests of that image against a container of it;REFERENCE=<image>tests another image, e.g. a local build, with the same tests. It buildsci/image-tests/Dockerfile(make test-image-runner) and runs it with the Docker socket (make test-image-run); the CI runsmake test-image-runafter loading the runner that the jobimage-test-runnerpasses on.- In an image test, a file that a service writes as
applicationand a command of the test writes as root (docker exec) belongs in/app, not in/tmp. The runners of GitHub Actions setfs.protected_regular, under which even root may not open a file of another user in a sticky directory withO_CREAT; a Docker host without it, as many local ones, lets such a test pass that then fails in the CI. make generate,make checkandmake testrun as your user, so the files they write belong to you. Do not write into the checkout as root.
Besides generate, check and test, the Makefile has structure-test. make structure-test runs container-structure-test against your local images of bootstrap, base, base-app, php, php-dev and php-nginx, the images that have a suite in tests/structure-test. It tests only the tags in .github/workflows/build.yaml and fails if a test fails, if docker fails or if no such image exists locally; run it inside webdevops/dockerfile-build-env with the Docker socket mounted. The CI runs the image tests for every image except toolbox, and container-structure-test for the six images above; to check a change by hand, start the image and try it as described below.
A pull request that adds a package or a tool to an image also adds a test for it, in the same pull request:
- Add an image test that runs the tool and checks its output, not only that the file exists, for example
testFileCommand()inci/image-tests/Checks/PhpChecks.php. - Put it into a trait in
ci/image-tests/Checks/that the test classes of every image with the package use; for all PHP images that isPhpChecks. - Check with
make test-imagethat the test fails on an image without the package and passes on one with it. - In the pull request description, say how much bigger the images get: absolute and in percent, on average over the images that get the package.
The documentation is part of every change. A pull request that changes what users of the images see also updates the documentation in the same pull request. Never leave it for a follow-up.
Where the documentation lives:
| File | Content |
|---|---|
README.md |
Entry point: short intro, quick start, supported tags ("Debian PHP" / "Alpine PHP") |
CONTRIBUTING.md |
Build process: the generated files and make generate, the CI and make check, building and testing locally, the image tests, PHP extension builds |
docs/README.md |
Image overview, platforms and nightly updates, how the images build on each other (Mermaid diagram) |
docs/environment-variables.md |
Every environment variable with its default and effect; uploads and long requests |
docs/customization.md |
Commands, scripts at start and build time, tools for your Dockerfile, services, cron jobs and their time zone, healthcheck, configuration files and placeholders, supervisord, locales, application user and changing its UID |
docs/images/*.md |
One page per image family: tags, base image, services, settings, development variant. php.md also has Debian or Alpine, production, installing extensions, mail and Xdebug with an IDE |
docs/known-issues.md |
Options and tools that do not work, with affected images and workaround; migration from older images |
docs/discontinued-images.md |
Replacements for images and tags that are no longer built (nginx, apache, the alpine tags of bootstrap, base and base-app, storage, vsftp, ssh) or deprecated (php-official) |
docs/dockerhub/*.md |
The pages on Docker Hub: a start page per built image with its tags and links into docs/, a warning per image that is no longer built. Generated from conf/dockerhub.yml; change the texts there |
Update the documentation whenever a change touches any of these:
- an environment variable or
php.*/fpm.*setting (added, removed, renamed, new default, new effect) - a published image or tag, for example a new or dropped PHP version
- a base image or operating system version
- a PHP extension that is added or removed
- a service, hook directory, entrypoint command or helper tool such as
docker-service - the build process, the CI workflow or the commands in
CONTRIBUTING.md
-
Find the source of truth. Check the code, not older documentation:
Question Where to look Published images and tags -t "webdevops/..."tags in.github/workflows/build.yaml(generated byci/console generate:github-cifromconf/console.ymlandci/)Base image FROMline indocker/<image>/<tag>/DockerfileVariables and defaults ENVintemplate/Dockerfile/**anddocker/**/Dockerfile.twig, scripts inprovisioning/**/binandprovisioning/**/provisionWhich files end up in which image conf/provision.yml -
Change sources, not generated files.
Dockerfileandconf/underdocker/are generated. EditDockerfile.twig,template/orprovisioning/and runmake generate. -
Verify every statement in a running container. Build the image (or use the image the CI built) and try the option. Do not rely on reading the scripts alone. Examples:
- PHP settings:
php -r 'echo ini_get("memory_limit");', orphp-fpm -ifor values the CLI overrides - PHP-FPM settings:
php-fpm -tt - Web server settings: an HTTP request against the container, or the rendered configuration under
/opt/docker/etc/nginxor/opt/docker/etc/httpd - Service options: the command line of the running process
- Hooks: a script that writes a marker file, then check the marker
Where you can, make the check an image test, so that the CI repeats it: a variable goes into
ENVIRONMENTinci/image-tests/ImageTestCase.php, the check of its effect into a trait inci/image-tests/Checks/.Check every image a statement names, not just one representative: images differ in what they inherit (for example
clionly works whereAPPLICATION_USERis set). Check both the Debian and the Alpine variant whenever their implementation differs (separate files underprovisioning/*/alpine, apk vs. apt,httpdvs.apache2,crondvs.cron). Test examples with the exact command you document, and make sure a check cannot pass on an error message. - PHP settings:
-
Document only what works. Never describe an option that has no effect as working. Fix it, or leave it out and list it in
docs/known-issues.md. If it works only in some images, say exactly which. Anythingdocs/known-issues.mdlists as not working must never appear as working anywhere else. AnENVline or a script that reads a variable is no proof that it works:SERVICE_POSTFIX_OPTSis passed topostfix start, which ignores it. When you fix a known issue, remove its entry in the same pull request. -
Keep lists in sync. The tag lists in
README.mdand indocs/images/*.mdmust match the tags pushed by.github/workflows/build.yaml. The README banner and the Docker Hub pages follow the built tags by themselves when you runmake generate; change their texts inconf/readme-banner.ymlandconf/dockerhub.yml. An image that is no longer built moves frombuilttodiscontinuedinconf/dockerhub.yml;make generatefails until it does. A statement on a Docker Hub page follows the same rules as the documentation.webdevops/php-officialis not listed in the README; it is a deprecated name ofwebdevops/php. The defaults indocs/environment-variables.mdmust match what a container reports. -
Follow the style.
- English, GitHub Markdown, relative links, diagrams as Mermaid. No documentation tooling.
- Usage examples use
docker compose, notdocker run. - Change the README only where needed; keep its structure and wording.
-
Say how you verified it. In the pull request description, list each documented change and the check that confirmed it.