Skip to content

Latest commit

 

History

History
109 lines (81 loc) · 11.9 KB

AGENTS.md

File metadata and controls

109 lines (81 loc) · 11.9 KB

Agent instructions

Repository map

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.

Build and test

Only these commands are known to work:

  • make generate installs the PHP tools of ci/ and runs ci/console generate in webdevops/php:8.4-alpine, which regenerates docker/, .github/workflows/build.yaml, the README banner and the Docker Hub pages. Run it after every change to template/, provisioning/, conf/ or a Dockerfile.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 and webdevops/toolbox come from local images or Docker Hub.
  • ./build-local.sh [version] builds all PHP images of one version.
  • make check installs the PHP tools of ci/ and checks the PHP code in ci/ with GrumPHP: coding standard, PHPStan, Rector, composer audit and the PHPUnit tests. Run it after every change to ci/. GrumPHP and PHPStan only check files that Git knows (git ls-files), so git add new files first; PHPUnit runs every test anyway. make test runs only the tests. Changes to ci/src come 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 builds ci/image-tests/Dockerfile (make test-image-runner) and runs it with the Docker socket (make test-image-run); the CI runs make test-image-run after loading the runner that the job image-test-runner passes on.
  • In an image test, a file that a service writes as application and a command of the test writes as root (docker exec) belongs in /app, not in /tmp. The runners of GitHub Actions set fs.protected_regular, under which even root may not open a file of another user in a sticky directory with O_CREAT; a Docker host without it, as many local ones, lets such a test pass that then fails in the CI.
  • make generate, make check and make test run 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.

Packages come with tests

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() in ci/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 is PhpChecks.
  • Check with make test-image that 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.

Keep the documentation up to date

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

When to update it

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

How to update it

  1. 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 by ci/console generate:github-ci from conf/console.yml and ci/)
    Base image FROM line in docker/<image>/<tag>/Dockerfile
    Variables and defaults ENV in template/Dockerfile/** and docker/**/Dockerfile.twig, scripts in provisioning/**/bin and provisioning/**/provision
    Which files end up in which image conf/provision.yml
  2. Change sources, not generated files. Dockerfile and conf/ under docker/ are generated. Edit Dockerfile.twig, template/ or provisioning/ and run make generate.

  3. 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");', or php-fpm -i for 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/nginx or /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 ENVIRONMENT in ci/image-tests/ImageTestCase.php, the check of its effect into a trait in ci/image-tests/Checks/.

    Check every image a statement names, not just one representative: images differ in what they inherit (for example cli only works where APPLICATION_USER is set). Check both the Debian and the Alpine variant whenever their implementation differs (separate files under provisioning/*/alpine, apk vs. apt, httpd vs. apache2, crond vs. cron). Test examples with the exact command you document, and make sure a check cannot pass on an error message.

  4. 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. Anything docs/known-issues.md lists as not working must never appear as working anywhere else. An ENV line or a script that reads a variable is no proof that it works: SERVICE_POSTFIX_OPTS is passed to postfix start, which ignores it. When you fix a known issue, remove its entry in the same pull request.

  5. Keep lists in sync. The tag lists in README.md and in docs/images/*.md must 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 run make generate; change their texts in conf/readme-banner.yml and conf/dockerhub.yml. An image that is no longer built moves from built to discontinued in conf/dockerhub.yml; make generate fails until it does. A statement on a Docker Hub page follows the same rules as the documentation. webdevops/php-official is not listed in the README; it is a deprecated name of webdevops/php. The defaults in docs/environment-variables.md must match what a container reports.

  6. Follow the style.

    • English, GitHub Markdown, relative links, diagrams as Mermaid. No documentation tooling.
    • Usage examples use docker compose, not docker run.
    • Change the README only where needed; keep its structure and wording.
  7. Say how you verified it. In the pull request description, list each documented change and the check that confirmed it.