Cloud: Production Container Image

The prestashop/prestashop image (source repository PrestaShop/docker) packages a release of the shop with PHP. The -fpm variant runs php-fpm instead of Apache. The table lists what it does, as read from the entrypoint script /tmp/docker_run.sh and from the running container, and what that means for a pod. Its environment variables and the problems of the first start are on Installation and Local Environments; this table is only about the production gap.

Source: PrestaShop/docker: Dockerfiles and entrypoint, Docker Hub: prestashop/prestashop and PrestaShop devdocs: Installing PrestaShop with Docker

So the production image is built on top of the official one but never started the official way. It keeps what is valuable in it (the release, the right PHP extensions at the right versions, a tested layout) and replaces the entrypoint, the configuration, the user and the folders. Two ways exist to get there:

The Dockerfile has seven stages and three build targets, which become three tags in one ECR repository:

The build targets are called app, web and installer; the tags are <git-sha>, <git-sha>-nginx and <git-sha>-install, which is what the chart of the Helm page expects (image.nginxTagSuffix and image.installTagSuffix). <git-sha> is the full commit SHA, so the tag of an image is the same string as github.sha in the release workflow and as image.tag in the chart values. The two runtime tags are built from the same commit, so the code that Nginx serves as static files and the code that PHP executes cannot differ. The suffix tags keep the three images in one repository and one lifecycle policy; the repository settings are on Container registry on AWS.

Why Nginx gets its own image and not the files through a shared volume: the shop’s PHP files must not be reachable from a second place, a shared code volume is a writable thing that every pod can change, and a copy of the static files (2,775 files, 89 MB in the test) is small. Nginx never reads a PHP file: it passes the script path to php-fpm, which has the file (see the Nginx section).

The two lock files, composer.lock for every module that has a composer.json and package-lock.json for the theme, are what make two builds of the same commit install the same dependencies. Commit them. (The placeholder modules of the test had no dependencies, so Composer ran without a lock file and said so; a real build must not.)

Source: Docker: Multi-stage builds and Dockerfile reference

The stages, in the order Docker runs them:

Build and tag all three from one commit (BuildKit, see BuildKit and Buildx):

Source: Docker: docker buildx build

The listing was built with these three --target options, with --tag names of a local test, and produced images of 1.91 GB (app), 138 MB (web) and 1.86 GB (installer). The app image adds 45 MB to the official one, almost all of it the shop’s renamed and cleaned directories. The two large images share every layer below the last four, so they cost little extra to store and to pull.

PrestaShop’s back office lives in a folder under the shop root. The release package names it admin; the installer renames it to a random name so that /admin/ is not a known address. In a cluster the name must be the same in every pod, in the Nginx container, and in the next release, so it is fixed once, at build, with mv admin "${ADMIN_DIR}". Pocket Coffee uses admin-pocketcoffee, so the back office is at https://www.pocketcoffee.example/admin-pocketcoffee/.

Three facts, read from the 9.2.0 source and observed, explain why the rename belongs in the image and why it comes before anything else:

The name is not a secret. Anyone who sees a back-office asset URL has it, and it appears in the redirects of the login page. Treat it as a way to keep scanners off the log, not as access control: restrict the path in the load balancer, WAF or Gateway rules, as described on Cloud: Cache, Sessions and the Back Office in a Cluster and Security. Because the name is baked into the image, changing it is a release, and a single name for staging and production avoids two images.

The probe results of the test show the effect: /admin-pocketcoffee/ answered 302 to the login page, and /admin/ answered 404 from the shop.

The files are part of the image: COPY modules/ ./modules/, a Composer install for each module that has dependencies, and the theme built in its own stage. Three details matter.

The theme is a folder in themes/. Its assets are built at image build time (npm ci, npm run build; the Hummingbird sources need Node 24, see Themes: Hummingbird and Classic). Which theme a shop uses is again a database value (the theme_name of the shop row), set by bin/console prestashop:theme:enable <name>, which is one more line for the migrate Job. In the test the command could not be confirmed: it answered "The selected theme is invalid" for the placeholder theme (which has only a theme.yml) and an error about a missing language context for the installed classic theme, so this page documents the command from the source and the console reference, and you must run it against your real theme in a staging environment before relying on it.

One more build step is needed for a read-only shop. When the Symfony container of the back office is compiled, PrestaShop deletes the files src/Entity/index.php of every active module, because API Platform would execute their exit statements (PrestaShopExtension::preprendApiConfig). With a read-only root file system that deletion is a fatal error on the first request of a pod: the test showed "Failed to remove file /var/www/html/modules/ps_accounts/src/Entity/index.php …​ Read-only file system". The app stage therefore deletes exactly those files at build, so the pods never have to:

Source: PrestaShop 9.2.0: PrestaShopExtension.php

The directory-listing guard those files provided is an Apache-era convention; Nginx serves no listing unless autoindex is on.

The core autoloader cannot be rebuilt. The 9.2.0 image has no composer.json in the shop root (the release package removes it, and the kernel says so in a comment), only composer.lock, so composer dump-autoload --classmap-authoritative has nothing to work from. The generated vendor/composer files contain a class map of 13,844 classes, but it is not set as authoritative: a class that is not in the map is looked up on disk. For the core the work is therefore done by OPcache, not by Composer; the modules' own autoloaders are the ones you can optimize, which is why the modules stage uses --classmap-authoritative.

PrestaShop also has a legacy class index, var/cache/prod/class_index.php, built on the first request (it maps the classes of classes/, controllers/ and override/). It is created in var/cache and lives with the pod, see the cache section.

The assets are already built. The back office assets are in the release package (admin/themes/new-theme/public/ and admin/themes/default/public/), which the test served with status 200 from the renamed folder through Nginx, and the Hummingbird and Classic assets are in their theme folders. The command assets:install, which the installer runs for the bundles, is only needed on a fresh install, which is the install Job’s business, not the web image’s. Your own theme’s assets are built in the theme stage. The only assets written at run time are the combined and compressed ones (CCC) under themes/<theme>/assets/cache/ and the generated default images under img/, both covered in the next sections and on Performance and Caching.

Source: PHP manual: OPcache configuration and PHP manual: the configuration file

The image already enables OPcache with 256 MB and 20,000 files, so this file changes three OPcache settings, repeats the memory size so that the file stands on its own, and adds the session handler.

OPcache is off for the command line (opcache.enable_cli = 0), so every bin/console run in a Job compiles every file again. That is normal and cheap next to the database work of a migration.

The PHP-FPM pool file is a second file in the image:

Source: PHP manual: FPM configuration

listen = 127.0.0.1:9000 is the most important line: it removes the FastCGI port from the pod network (the official image binds all interfaces). pm = static with a fixed pm.max_children makes the memory of a pod predictable, which is what the Kubernetes memory limit and the autoscaler need; the number 8 is a starting point to measure with the memory of your own pages, and the sizing method is on Cloud: Autoscaling, Observability, Backups and Security. clear_env = no is the image’s own setting and is what lets PHP workers see the environment of the container; without it the workers would have none of the variables that the configuration reads. ping.path makes php-fpm answer /fpm-ping itself, which the probe uses (see the Nginx section).

The install/ folder holds the web installer. The 9.2 installer removes it after a successful install, and the Docker entrypoint removes it again afterwards, which fails because the folder is gone (the problem is described on Installation and Local Environments); the change is documented in the 9.2 core updates. A production image does not depend on that: rm -rf install in the app stage removes it at build, so no pod ever has it, whatever happened to the database. The installer target keeps it for the one Job that needs it. In the test the probe /install/ answered 404 from the shop.

The app stage ends with USER www-data (uid and gid 33), and the web stage with USER nginx (uid 101). uid 33 is the owner that the EFS access point of the shared volume uses (see Cloud: Shared Media and Writable Paths), so the pods and the shared files agree on who owns what. Nginx comes from nginxinc/nginx-unprivileged, which listens on port 8080, because a non-root process cannot bind port 80. The test ran both containers with --read-only, --cap-drop=ALL and --security-opt=no-new-privileges: PHP-FPM then runs as uid 33 with an empty capability set (CapEff: 0000000000000000), Nginx as uid 101, and the shop worked. php-fpm prints a harmless notice, "'user' directive is ignored when FPM is not running as root".

With a read-only root file system the shop must be given every path it writes to. The paths below were found by running the image read-only and exercising it: about 40 front-office URLs (home, categories, products, pages, the login page), the back-office login and dashboard, three bin/console module installs and a module upgrade, while reading the error log. The full analysis of which of them are per pod and which must be shared is on Cloud: Shared Media and Writable Paths; this table is what the image needs.

Source: Kubernetes: Configure a Security Context for a Pod or Container

Paths that this test did not exercise (for example translations/, mails/, var/modules and the theme customization screens) are not in the table; the writable-paths page covers them from the source. The excerpt of the Deployment that these paths, the user and the probes make is below; the complete chart, with the helpers pc.* and the values file, is on the Helm page. It was validated with kubeconform -strict against the Kubernetes 1.36 schemas.

Source: Kubernetes: Deployments and Kubernetes: emptyDir

Mounting the shared claim over img/ hides the img/ folder of the image (the logo placeholders, the folder skeleton). The first deployment must seed the volume once, as the shared media page describes. The Nginx container mounts the same folders read-only: it serves media files and never writes them. The startup probe allows 24 times 5 seconds for the cache warm-up; the liveness probe, the PodDisruptionBudget and the topology spread are on the Helm page.

One more protection concerns the configuration file. The back office’s Performance page rewrites app/config/parameters.php when you change the cache settings: PhpParameters::saveConfiguration() dumps the whole evaluated configuration, secrets included, with var_export. On the image the file is owned by root and has mode 0444, so the write fails with an error and a literal copy of the secrets is never written; the settings that the Performance page would write are environment variables of the release instead.

The shop reads its configuration from app/config/parameters.php, in two places: the legacy bootstrap (config/bootstrap.php turns the file into the constants _DB_SERVER_, _DB_PASSWD_, _COOKIE_KEY_ and others, through a cached copy var/cache/<env>/appParameters.php that is refreshed only when the file is newer than the copy) and the Symfony container (app/config/set_parameters.php loads the same file and sets each key as a container parameter). When the file is missing, the second falls back to empty placeholders, which is why a shop without it fails at the database connection and not with a clear message. The image’s file is a small piece of PHP that reads the environment:

Source: PrestaShop 9.2.0: set_parameters.php and config/bootstrap.php

Five points about it:

The environment comes from a Kubernetes Secret that the External Secrets Operator fills from AWS Secrets Manager (the names are in the table), mapped as in this table. The ExternalSecret that produces the Secret is on the Helm page.

The entrypoint adds the checks and the warm-up, then hands over:

Source: Dockerfile reference: ENTRYPOINT and Kubernetes: Using Secrets as environment variables

It passes shellcheck, and the test ran it three ways: with a complete environment (it starts), with none (it prints "pocketcoffee: missing environment variables: PS_SECRET PS_COOKIE_KEY …​" and exits with status 64 before PHP starts, so a pod with a missing Secret key fails at once with a clear line and never serves a broken shop), and with PS_WARMUP=0 for Jobs. The entrypoint prints the host, database and user and never a secret.

Rotating a secret is a rollout: the values are read when PHP starts, and the cache described next stores them too. Pods must be restarted after a rotation, and the cookie keys must not be rotated casually (the operations page covers the procedure).

A natural idea is to run bin/console cache:warmup in the Dockerfile so that pods start fast. Three findings show that it does not work, and what to do instead.

So the cache is built when the pod starts, in var/cache, an emptyDir, from the pod’s own environment and the live database. That is the loop in the entrypoint: one cache:warmup per kernel, with these options.

Without the optional warmers a pod starts in about 5 to 10 seconds and compiles each Twig template on first use, which spreads the cost over the first requests of each pod. With them the pod needs up to a minute and 800 MB for three kernels before it serves anything. Pods start often (every deployment, every scale-up), so the image uses --no-optional-warmers, and the readiness and startup probes of the excerpt make sure that no traffic arrives before the container is ready. (After the test traffic, var/cache was 58 MB.)

The warm-up is also why the cache must not be cleared from the back office in production: the Symfony cache of one pod is not the cache of the others, see Cloud: Cache, Sessions and the Back Office in a Cluster. A new release replaces the pods, which is the only cache clear a cluster needs.

Jobs are different. A Job runs one bin/console command in a container, and the command builds the admin cache itself when var/cache is empty; the warm-up of the entrypoint does not apply because it runs only before php-fpm. Give the Job an emptyDir for var/cache and var/logs as the web pods have.

The memcached extension is the one thing the Dockerfile above does not install, because it needs system libraries. If the Memcached option is chosen, add this RUN to the base stage, before the COPY lines, and rebuild:

Source: PHP manual: Memcached installation and php-memcached

This block was not built on the check date. In the test environment apt-get update on the Debian 12 (bookworm) base of the official image, and on debian:bookworm-slim, failed with "At least one invalid signature was encountered" for all three repositories, so no package could be installed (the official php:8.4-fpm image, which is based on Debian 13, updated normally). The phpredis extension does not need system libraries and builds with pecl alone, which is why the Dockerfile above installs that one and was built and run. Build the memcached block yourself, and check that php -m lists memcached before relying on it.

The web target is Nginx with the files a browser fetches and this server block. Nginx does not have the PHP files; it passes the script path to php-fpm on loopback, and php-fpm reads the file from its own container.

Source: PrestaShop devdocs: Configure Nginx and Nginx: ngx_http_fastcgi_module

The block is the one of Installation and Local Environments (rewrites, denied paths and the extra rules that the documented sample lacks), with the changes the pod needs:

The static stage copies only files that a browser can use: style sheets, scripts, images, fonts and robots.txt, from every folder except var, vendor, src, tools and app. That is why no template, configuration file or PHP script is in the Nginx image, and the deny rules above are a second layer, not the only one.

The status codes the pod pair returned on the test shop (installed for pocketcoffee.example, requests sent with that Host header and X-Forwarded-Proto: https):

For the web server’s own tuning (compression, headers, expiry), see the Nginx section of Performance and Caching; the CDN and the WAF rules in front of it are on the operations page.

Four checks catch most mistakes, and all four ran in the test. They need no cluster and no registry.

Source: Docker: docker container run

The second command needs a database that the settings in test.env can reach (a throwaway MySQL 8.4 container on the same Docker network, with the installer target run once against it, was used in the test) and a file with the test-only values of the variables above, never production values. --network container:pc-fpm puts Nginx in the network namespace of the php-fpm container, which is what two containers of a pod share, so 127.0.0.1:9000 works in the test as it does in the cluster. (The test used a multi-line PEM key through -e, because an --env-file cannot hold one; the keys of the test were generated by the installer and are not in this page.)

Run on 2026-10-29 on Docker 29.9.2 (arm64), in a scratch directory outside the repository, with a placeholder module set (three modules, one with a composer.json and a PSR-4 class) and a placeholder theme (a package.json whose build script writes a style sheet):

Not run: the memcached extension block (apt could not verify the Debian 12 repositories on the check date), a real theme and real modules (the placeholders passed composer and npm but not prestashop:theme:enable), the build from php:8.5-fpm and the release package, a cluster, ECR and the External Secrets Operator. The images, containers and network of the test were removed afterwards.