Cloud: Container Image and Pipeline Build

A Magento deployment that changes on a running server (Composer on the server, setup:di:compile on the server, files edited in place) cannot run on a cluster: every pod would have its own copy. The image therefore carries everything that is code, and the chart of this series (page 36) expects exactly this from it:

Adobe’s pipeline deployment model separates three systems, and the separation is what makes the image possible. The development system is an installed Magento with a database where the developer creates store views, registers themes, enables modules and changes configuration; it is the only place where app:config:dump can run. The build system has the code, PHP and Composer and produces the generated code and the static files; Adobe’s page says that it needs no installed Commerce and no database connection when config.php already carries what the build would otherwise ask the database for. The production system receives the result and does not change it. On this series:

bin/magento app:config:dump is a module command of Magento_Deploy. Magento registers module commands only when the deployment configuration is available, which the 2.4.9 code decides by the presence of install/date in env.php (DeploymentConfig::isAvailable(), read in the 2.4.9 tag), and the command reads its values from the configuration sources, which for the scopes and the system configuration are database tables. A build that has no installation has nothing to dump. So the dump is not a step of the Docker build, in spite of what a shortcut such as "run app:config:dump in the image build" suggests: it is a step of the development system, and its output (app/etc/config.php) is a source file that is committed. The image build consumes it.

What the dump writes, from Adobe’s page and the 2.4.9 sources of ApplicationDumpCommand and the di.xml files that register its sources: the config types scopes (websites, store groups, store views), themes (the registered themes with their parents), i18n and system (system configuration values). Settings that a module declares as sensitive or system-specific go to env.php and are not part of the commit. A configuration path that is set in config.php or env.php is locked in the Admin (the field is shown as disabled), and the releases page explains why scopes matter for the release: the importer applies them from the file, including deletions.

Source: Adobe Commerce docs: Export configuration settings

What to dump is a decision, because config.php is shared by every environment of the image:

The guard runs at the start of the build, before anything slow:

Source: Adobe Commerce docs: config.php reference

The guard checks what a database-less build needs and what a reviewer forgets: a non-empty module list with the four Pocket Coffee modules enabled, a scopes section and a themes section that contains the shop’s theme, no key that looks like a secret and no base URL. The theme keys have the form area/Vendor/theme (frontend/PocketCoffee/roast); confirm the form on your own dump before you rely on it. It is a script of this series, not a Magento command, and it was run against five fixtures (a good file, a file without themes, a disabled module, an api_key with a value and a base URL), each ending as the listing says.

Source: GitHub: magento/magento2 2.4.9, the Magento project layout

Source: Docker Docs: .dockerignore files

The ignore list is a security control, not only a speed-up. COPY . ./ copies whatever the context holds: an auth.json that a developer keeps next to composer.json, a .env file or a .pem would become part of the image and of every layer cache. vendor, generated, var and pub/static are excluded because the build produces them; a developer’s local copy must not leak in. The modules and the theme live in app/code and app/design so that the Composer layer depends only on composer.json and composer.lock (modules installed as path repositories would need their sources before composer install and would lose that cache).

repo.magento.com requires authentication: Adobe’s page says to create a pair of keys in the Commerce Marketplace, with the public key as the user name and the private key as the password, tied to a MAGEID that is entitled to the Adobe Commerce packages. Mage-OS needs no keys: it serves the same code as mage-os/* packages from the public repository https://repo.mage-os.org/, which answered on 2026-10-29 with the project package mage-os/project-community-edition in version 3.6.0. A shop on Mage-OS passes no secret at all; the BuildKit mount below is simply empty. What else protects the credentials of a shop is on Security.

The keys are a build-time secret, and the Dockerfile treats them as one:

Source: Composer documentation: Authentication for privately hosted packages

Source: Adobe Commerce docs: Get your authentication keys

composer install --no-dev --prefer-dist --optimize-autoloader installs from the lock file (never update in a build: the lock file is the bill of materials of the release), without the test frameworks and tools of the development requirements, from dist archives, and with an optimised class map. Not --classmap-authoritative: Magento’s autoload section adds app/code/ and generated/code/ as PSR-0 paths, and an authoritative map would not load the classes that setup:di:compile creates after Composer ran. The build runs composer dump-autoload --optimize --no-dev once more after the shop’s own modules are in place, so that they are in the class map too. A package that Composer must fetch from a private Git repository needs the git binary in the vendor stage; the example installs none, because Magento and Mage-OS ship dist archives.

The extensions below are the union of Adobe’s list of required extensions for Commerce (generated from a running installation) and the require section of composer.json of the 2.4.9 tag; Mage-OS 3.6.0’s composer.json lists the same without ext-ftp, and installing it does no harm. The column "In php:8.5`" is the result of `php -m in a php:8.5-cli container (PHP 8.5.12 on Debian 13) on 2026-10-29: the FPM variant of the official image is built the same way.

Three details of the php-base stage. The development packages that the compile needs (libicu-dev, libpng-dev and the others) are installed and removed in one RUN, and the runtime libraries of the extensions that were built are kept with the idiom of the official image’s own Dockerfile (list the shared objects that the compiled extensions link against, mark their packages manual, purge the rest). AVIF is not compiled into gd; a shop that serves AVIF adds libavif-dev and --with-avif. The stage ends with a check that fails the build if one of the required extensions is not loaded, so a base-image change cannot remove an extension silently. This stage changes rarely and is cached.

Source: Docker Docs: Dockerfile reference

Source: Docker Official Image php: How to install more PHP extensions

vendor. One layer, keyed on composer.json and composer.lock. The BuildKit cache mount keeps Composer’s download cache between builds on the same builder; it is not part of the image.

build: mode and env.php. ENV MAGE_MODE=production makes the build run in production mode: bin/magento takes the mode from the environment variable MAGE_MODE or from env.php, and setup:static-content:deploy refuses to run in another mode unless you give it -f (checkAppMode() in the 2.4.9 source). The throwaway env.php (docker/build-env.php, the listing below) exists for one reason: Cli::getApplicationCommands() registers the module commands only if DeploymentConfig::isAvailable() is true, and that is the case when install/date is set. It holds no connection and no key; rm deletes it in the last step of the stage.

Source: Adobe Commerce docs: env.php reference

build: setup:di:compile. It reads the modules list of the deployment configuration (that is config.php), compiles only the modules that are enabled there, fails with "You cannot run this command because modules are not enabled" when the list is empty, and writes generated/code and generated/metadata. This is the reason the guard script exists: a module that is missing from the committed file is not compiled, and the pods fail at run time with a class that is not generated, on a tree where nothing can generate it. Adobe’s PHP settings page asks for at least 1 GB of memory_limit for compiling and for deploying static assets; the Dockerfile passes 2 GB with -d memory_limit=2G for both, and the builder must have that memory and the sizes of two or three php processes (--jobs 4 for the static content).

build: setup:static-content:deploy. The options and what they cost:

Static content without a database. The static content deployment needs to know the themes and the locales. The locales are on the command line and the themes come from the themes section of config.php. Adobe documents the case in two places: the build system page says that no installation is needed and that the database connection is not required if config.php already holds the exported configuration, and the page on static view files has a section "Deploy static view files without installing Commerce" that starts with app:config:dump on the production system. That is the design of this page. It was not executed here (see the last section), so the first build is also the first proof: if the deployment fails with a database error, the dump is missing scopes or themes, or a module’s observer or plugin reaches the database during the build, and the module is what to fix.

build: the finish. The last RUN deletes env.php, the docker directory and everything under var/, creates the mount points, asserts that the products of the build exist (deployed_version.txt, generated/code, generated/metadata and the locale directories of the theme and the Admin theme), and makes the tree owned by root and readable by all, with no write permission for group and others. deployed_version.txt matters: in production mode a missing file stops every page ("Unable to retrieve deployment version of static files", see the releases page).

nginx. Copies nginx.conf.sample and the whole pub/ of the build stage (static files, entry points, errors/) and the maintenance page, nothing else. No PHP is needed: nginx hands .php requests to FPM in the same pod over 127.0.0.1:9000, but the files must be visible to nginx because the sample’s try_files runs before the hand-over. The base is the unprivileged build of the official image, which listens on a port above 1024, keeps its pid and temporary files in /tmp (an emptyDir in the chart) and runs as uid 101. Because both images are COPY --from=build, they carry the same pub/static and the same deployed_version.txt; the verification script compares them.

php. The last stage of the file, so that docker build . without --target builds it. It adds the RDS bundle, the tree, the two scripts and USER 33:33, and keeps the base image’s CMD ["php-fpm"] and its SIGQUIT stop signal (graceful stop). The chart overrides the pool (listen = 127.0.0.1:9000, clear_env = no) with a file that loads after the image’s own. A theme that needs Node (Hyvä builds its CSS with Tailwind, see Frontend: Hyvä, PWA Studio and Edge Delivery) adds a node stage that runs before setup:static-content:deploy; the rest of the design is unchanged.

Source: Adobe Commerce docs: Required PHP settings

Source: PHP manual: OPcache configuration

opcache.validate_timestamps = 0 is the reason a container is faster than a server. With the default, PHP checks the modification time of every cached file at an interval (opcache.revalidate_freq); Magento includes thousands of files per request, and the files of an image never change, so the check is wasted. The consequence is the contract of this page: a change to the code is a new image and a rollout. kubectl cp or a changed file in a running container is not seen by PHP until the worker restarts, and it must not be done at all on a read-only file system. opcache.save_comments = 1 stays on: Magento reads annotations and generates code from doc comments (Adobe’s page says it is required). opcache.memory_consumption = 512 and opcache.max_accelerated_files = 100000 are starting points: count the PHP files of the image (find vendor app generated -name '*.php' | wc -l) and keep the limit above that number, because a file that does not fit is compiled on every request. Look for a full cache and for restarts in the pod’s metrics rather than in the file; the PHP-FPM and OPcache metrics are on Cloud: Autoscaling, Observability, Backups and Security.

The ConfigMap pocketcoffee-php of the chart mounts zz-pocketcoffee.ini, which loads after this file, sets the same OPcache keys and opcache.enable_cli = 1 for the Jobs and the consumers, and may change them per environment. The baseline in the image is what a pod gets if the ConfigMap is missing, and what bin/magento uses in the build (where opcache.enable_cli is off, which is right for a command that runs once). realpath_cache_size and realpath_cache_ttl are Adobe’s recommended values: they save the path lookups of the many require statements. php.ini-production is the starting file (display_errors off, expose_php off, zend.assertions disabled); the image moves it to php.ini as the documentation of the official image describes.

Production mode is not only a flag. In production mode Magento does not generate classes or static files on demand, does not write to generated/ or pub/static, hides exceptions from the browser and logs them, and the Admin locks the configuration paths that are set in files. The chart turns that into a rule that the file system enforces:

What the tree cannot do is also a design input. The Admin cannot save a value whose path is in config.php or env.php; an extension that writes into app/etc or generated/ at run time (a few do, on first use) fails on the first request and must be fixed or replaced; the Admin’s "Flush Magento Cache" works because the cache is in Valkey, but "Flush Catalog Images Cache" and the media tools work on pub/media, which is the volume or S3. Logs go to var/log by default, so a pod’s logs disappear with the pod unless the application’s handlers write to standard output or an agent ships them; the observability page covers it.

docker build builds one target at a time and shares nothing between two invocations that run on different runners. docker buildx bake reads a file that names several targets and builds the stages they share once, so the vendor and build stages run one time and feed both images. That is how the two tags come from one setup:static-content:deploy.

Source: Docker Docs: Bake file reference

Source: Amazon ECR: Image tag mutability

Source: AWS CLI: ecr batch-get-image

Source: Docker Docs: Build secrets

Points that are easy to get wrong:

The checks that matter run on the finished images, the way the cluster runs them: read-only, as uid 33 and 101, with only /tmp writable. The script exits on the first failed check, and the push happens only after it passed.

Source: Docker Docs: docker container run

What it proves, and what it does not. It proves that the extensions are there, that OPcache does not stat files, that the products of the build exist, that nothing important is writable, that the secret and the throwaway env.php are not in the image and that the two images carry the same deployed_version.txt. It does not prove that Magento runs: that needs the managed services, and the first deployment to a staging cluster with the chart is the test (the releases page verifies a release from a pod). Add to the same place a vulnerability scan of both images (ECR scans on push in this series) and, for supply-chain control, the practices of Image Best Practices and Supply-Chain Security.

Facts checked on 2026-10-29. Adobe’s system requirements for 2.4.9 list PHP 8.5, Composer 2.10 and nginx 1.30 (the table of the 2.4.9 release); the require sections of composer.json in the 2.4.9 tag of magento/magento2 and the 3.6.0 tag of mage-os/mageos-magento2 for the PHP extensions; the Docker Hub registry API for the existence of the tags php:8.5-fpm, nginxinc/nginx-unprivileged:1.30-alpine and composer:2.10; the public Composer repository repo.mage-os.org for the package mage-os/project-community-edition 3.6.0. In the Magento 2.4.9 source: Cli::getApplicationCommands(), DeploymentConfig::isAvailable(), DiCompileCommand (checkEnvironment() and execute()), DeployStaticContentCommand::checkAppMode(), ApplicationDumpCommand with the di.xml files of Magento_Config, Magento_Store and Magento_Theme that register its sources, and Bootstrap for MAGE_MODE; and Adobe’s pages on the build system, on exporting configuration, on static view files and on PHP settings.

Validated by running it. php -l on docker/check-config.php and docker/build-env.php in a PHP 8.5.12 container; the guard against five fixture files, each ending with the documented result; the extension check of the Dockerfile in a php:8.5-cli container (it reported bcmath, ftp, gd, intl, pdo_mysql, soap, sockets, xsl, zip as missing, which is the list in the table above); the ini file loaded by PHP 8.5.12 with the values read back; shellcheck on ci/build-and-push.sh, docker/verify-image.sh, mg-migrate, mg-warmup and on the RUN bodies of the Dockerfile extracted into scripts (only the intended findings remain: the single quotes around the PHP snippets and the word splitting of the official image’s idiom); the quoting of verify-image.sh in a stock PHP container; nginx -t in nginxinc/nginx-unprivileged:1.29-alpine with the rendered default.conf of page 36 and a tree laid out as the nginx stage lays it out, and that container started read-only as uid 101 (/healthz and a versioned static URL answered 200, /setup/index.php and /update/ answered 404, and index.php and get.php answered 502 because there was no FPM, which shows that nginx finds the entry points); docker buildx bake --print on the bake file; xmllint on the two figures.

Not run: docker build and docker buildx bake itself. The Docker disk of the machine that checked this page was full (no space available to the Docker daemon), so no image was built. Consequently the Dockerfile as a whole has not been executed. Not verified: the compilation of the extensions on php:8.5-fpm, composer install against repo.magento.com or repo.mage-os.org, setup:di:compile, setup:static-content:deploy without a database, the size and the build time of the images, docker build --check and hadolint (not installed), verify-image.sh against real images, the nginx 1.30 line (the local image was 1.29; the 1.30 tag exists), PHP-FPM as uid 33 in a read-only container, the push to ECR, a GitHub Actions run and a Mage-OS or Adobe Commerce installation from this image. Treat the Dockerfile as a reviewed draft whose first build is its test, run it once on a machine with free disk before it becomes the pipeline, and fix what that run shows in this order: the extension stage, Composer, the compile, the static content.