Dockerizing PHP-FPM

When to use

• The user wants to package a PHP-FPM application into a Docker image for deployment.
• The user wants to configure PHP opcache (and JIT) inside a production container image.
• The user wants to shrink a bloated PHP Docker image or speed up its build.

When NOT to use

• Do not apply production image hardening when the user only wants a throwaway local dev container with bind-mounted source.
• Do not use this skill for Kubernetes manifests, service meshes, or multi-service orchestration concerns.

Core guidance

• Prefer official php-fpm-alpine, pin the exact tag — Base the runtime on an official php:<version>-fpm-alpine image and pin the full version tag (e.g. php:8.3.14-fpm-alpine) rather than latest or a bare major.
• Use a multi-stage build to keep the runtime image lean — Split the Dockerfile into a build stage (Composer, node, compilers) and a slim runtime stage that copies only vendor/ and the application code.
• Enable opcache with validate_timestamps=0 in production images — In production images set opcache.enable=1, opcache.validate_timestamps=0, and a generous opcache.memory_consumption; never disable timestamp validation locally.

Quick recipe

1. Start a composer build stage, copy composer.json/composer.lock, and run composer install --no-dev --optimize-autoloader before copying source. (verify: The build stage produces a populated vendor/ directory)
2. In a php:<version>-fpm-alpine runtime stage, install required extensions, then COPY --from=build the application and vendor/, and set a non-root USER. (verify: docker run --rm img php -m lists every extension the app needs)
3. Copy a docker-php-ext-opcache ini enabling opcache with validate_timestamps=0 into conf.d, then verify throughput. (verify: php -i | grep opcache.enable shows On and timestamps validation off)

Best practices

• Run composer install --no-dev --optimize-autoloader --no-interaction --prefer-dist in the build stage so dev tooling and unoptimized autoloading never ship
• Copy composer.json and composer.lock, run composer install, and only then COPY the application source, so the vendored dependency layer is cached
• Create an unprivileged user in the image and set USER so the FPM master and workers do not run as root

Anti-patterns

See references/anti-patterns.md.

Common mistakes

1. Package manager cache bloats the image — Leaving apt/apk caches and build-only -dev packages in the final layer inflates the image by hundreds of MB. Fix: Use apk add --no-cache, or for apt run rm -rf /var/lib/apt/lists/* in the same RUN, and remove build-only packages after compiling extensions.
2. Assuming PHP extensions ship with the base image — The official PHP images ship a minimal extension set; pdo_mysql, intl, gd, and zip are not present by default. Fix: Install extensions explicitly with docker-php-ext-install (or pecl install plus docker-php-ext-enable) in the build stage and verify with php -m.
3. validate_timestamps=0 serves stale code after a deploy — With opcache.validate_timestamps=0, editing files in a running container has no effect — PHP keeps serving the cached bytecode. Fix: Treat the image as immutable — build a new image per release and restart the container; never hot-edit files in a validate_timestamps=0 production container.

Version notes

• Opcache JIT available from PHP 8.0 (PHP >=8.0) — The opcache JIT (opcache.jit, opcache.jit_buffer_size) is available from PHP 8.0; on 7.4 images tune classic opcache only.

Security

• Not applicable — no I/O, auth, or untrusted input.

Testing

• Activation and decision behavior are verified in eval/scenarios/devops/docker-php.yaml.

Additional resources

• references/anti-patterns.md
• references/core.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Related: databases/redis, devops/ci-github-actions, devops/deployment-strategies, devops/env-config