diff --git a/AGENTS.md b/AGENTS.md index 6058067d2..6b3777400 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -31,6 +31,15 @@ Only these commands are known to work: Besides `provision`, the Makefile has `structure-test` and `setup`, which the `webdevops/dockerfile-build-env` image runs while it is built. `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 serverspec for every image except `toolbox` and `dockerfile-build-env`, 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 a shared example to `tests/serverspec/spec/shared/` that runs the tool and checks its output, not only that the file exists, for example `misc::file` in `tests/serverspec/spec/shared/misc/tools.rb`. +- Include it in the collection of every image that gets the package; for all PHP images that is `collection::php` in `tests/serverspec/spec/collection/php.rb`. +- Check 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. diff --git a/docker/php-official/8.2-alpine/Dockerfile b/docker/php-official/8.2-alpine/Dockerfile index 6e63c33c6..16c664007 100644 --- a/docker/php-official/8.2-alpine/Dockerfile +++ b/docker/php-official/8.2-alpine/Dockerfile @@ -84,6 +84,7 @@ RUN --mount=type=bind,from=ghcr.io/php/pie:bin,source=/pie,target=/usr/local/bin set -x \ # Install php environment && apk-install \ + file \ imagemagick \ graphicsmagick \ ghostscript \ diff --git a/docker/php-official/8.2/Dockerfile b/docker/php-official/8.2/Dockerfile index a40e266fa..2235a9d97 100644 --- a/docker/php-official/8.2/Dockerfile +++ b/docker/php-official/8.2/Dockerfile @@ -85,6 +85,7 @@ RUN --mount=type=bind,from=ghcr.io/php/pie:bin,source=/pie,target=/usr/local/bin # Install php environment && apt-install \ # Install tools + file \ imagemagick \ graphicsmagick \ ghostscript \ diff --git a/docker/php-official/8.3-alpine/Dockerfile b/docker/php-official/8.3-alpine/Dockerfile index 7671ad2bb..91e766232 100644 --- a/docker/php-official/8.3-alpine/Dockerfile +++ b/docker/php-official/8.3-alpine/Dockerfile @@ -84,6 +84,7 @@ RUN --mount=type=bind,from=ghcr.io/php/pie:bin,source=/pie,target=/usr/local/bin set -x \ # Install php environment && apk-install \ + file \ imagemagick \ graphicsmagick \ ghostscript \ diff --git a/docker/php-official/8.3/Dockerfile b/docker/php-official/8.3/Dockerfile index 89e05d4ad..ad2833860 100644 --- a/docker/php-official/8.3/Dockerfile +++ b/docker/php-official/8.3/Dockerfile @@ -85,6 +85,7 @@ RUN --mount=type=bind,from=ghcr.io/php/pie:bin,source=/pie,target=/usr/local/bin # Install php environment && apt-install \ # Install tools + file \ imagemagick \ graphicsmagick \ ghostscript \ diff --git a/docker/php-official/8.4-alpine/Dockerfile b/docker/php-official/8.4-alpine/Dockerfile index e7c866566..126a6dfb3 100644 --- a/docker/php-official/8.4-alpine/Dockerfile +++ b/docker/php-official/8.4-alpine/Dockerfile @@ -84,6 +84,7 @@ RUN --mount=type=bind,from=ghcr.io/php/pie:bin,source=/pie,target=/usr/local/bin set -x \ # Install php environment && apk-install \ + file \ imagemagick \ graphicsmagick \ ghostscript \ diff --git a/docker/php-official/8.4/Dockerfile b/docker/php-official/8.4/Dockerfile index f4f544149..9e3cf5143 100644 --- a/docker/php-official/8.4/Dockerfile +++ b/docker/php-official/8.4/Dockerfile @@ -85,6 +85,7 @@ RUN --mount=type=bind,from=ghcr.io/php/pie:bin,source=/pie,target=/usr/local/bin # Install php environment && apt-install \ # Install tools + file \ imagemagick \ graphicsmagick \ ghostscript \ diff --git a/docker/php-official/8.5-alpine/Dockerfile b/docker/php-official/8.5-alpine/Dockerfile index 2eded84c6..a888149d4 100644 --- a/docker/php-official/8.5-alpine/Dockerfile +++ b/docker/php-official/8.5-alpine/Dockerfile @@ -84,6 +84,7 @@ RUN --mount=type=bind,from=ghcr.io/php/pie:bin,source=/pie,target=/usr/local/bin set -x \ # Install php environment && apk-install \ + file \ imagemagick \ graphicsmagick \ ghostscript \ diff --git a/docker/php-official/8.5/Dockerfile b/docker/php-official/8.5/Dockerfile index c4fdb7222..79bbedd6c 100644 --- a/docker/php-official/8.5/Dockerfile +++ b/docker/php-official/8.5/Dockerfile @@ -85,6 +85,7 @@ RUN --mount=type=bind,from=ghcr.io/php/pie:bin,source=/pie,target=/usr/local/bin # Install php environment && apt-install \ # Install tools + file \ imagemagick \ graphicsmagick \ ghostscript \ diff --git a/docs/customization.md b/docs/customization.md index 38cafe979..20780bbac 100644 --- a/docs/customization.md +++ b/docs/customization.md @@ -70,6 +70,7 @@ These commands are installed in the images. Use them in `RUN` lines of your own | `apt-install ` | Runs `apt-get update`, installs the packages without recommended packages and removes the package lists again | Debian- and Ubuntu-based images, including `bootstrap:ubuntu-22.04` | | `apk-install ` | Installs packages with `apk add --no-cache` | Alpine-based images, including `bootstrap:alpine` | | `docker-image-cleanup` | Removes package lists and caches; use it at the end of a `RUN` that installed packages | all except `toolbox`; fails in the Alpine `php-*` images, see [Known issues](known-issues.md#docker-image-cleanup-in-the-alpine-php-images) | +| `file ` | Shows the type of a file, for example `file --mime-type upload.bin`; tools such as GrumPHP's BOM check call it | `php`, `php-apache`, `php-nginx` and their `-dev` images | | `go-replace -s -r -- ` | Replaces text in files; the same tool fills the [placeholders](#placeholders) | all | | `gosu ` | Runs a command as another user, for example `application` | all except `toolbox` | | `docker-service enable `, `docker-service disable `, also `docker-service-enable` and `docker-service-disable` | Enables or disables a [service](#services); enabling installs it if needed | all except `bootstrap` and `toolbox` | diff --git a/template/Dockerfile/images/php.jinja2 b/template/Dockerfile/images/php.jinja2 index acd99ac3d..16eab6f41 100644 --- a/template/Dockerfile/images/php.jinja2 +++ b/template/Dockerfile/images/php.jinja2 @@ -42,6 +42,7 @@ # Install php environment && apt-install \ # Install tools + file \ imagemagick \ graphicsmagick \ ghostscript \ @@ -196,6 +197,7 @@ {% macro officialAlpine(role='', version='') -%} # Install php environment && apk-install \ + file \ imagemagick \ graphicsmagick \ ghostscript \ diff --git a/tests/serverspec/spec/collection/php.rb b/tests/serverspec/spec/collection/php.rb index 68158f3f3..21b28be6d 100644 --- a/tests/serverspec/spec/collection/php.rb +++ b/tests/serverspec/spec/collection/php.rb @@ -16,6 +16,7 @@ include_examples 'misc::graphicsmagick' include_examples 'misc::imagemagick' include_examples 'misc::ghostscript' + include_examples 'misc::file' include_examples 'base::syslog-ng' end diff --git a/tests/serverspec/spec/shared/misc/tools.rb b/tests/serverspec/spec/shared/misc/tools.rb index 400c27c98..04fe31b4c 100644 --- a/tests/serverspec/spec/shared/misc/tools.rb +++ b/tests/serverspec/spec/shared/misc/tools.rb @@ -30,3 +30,20 @@ its(:exit_status) { should eq 0 } end end + +shared_examples 'misc::file' do + it "should include file" do + expect(file("/usr/bin/file")).to be_executable + end + + describe command('file --version') do + its(:stdout) { should match %r!^file-5\.[0-9]+! } + its(:exit_status) { should eq 0 } + end + + # The magic database works: it tells a PHP script from a binary + describe command("printf ' /tmp/file-test.php && file --brief --mime-type /tmp/file-test.php /usr/local/bin/php") do + its(:stdout) { should eq "text/x-php\napplication/x-pie-executable\n" } + its(:exit_status) { should eq 0 } + end +end