How S6 Overlay Enables Multi‑Process Management in PHP Containers

What Is S6 Overlay?

S6 Overlay is a container‑native process management tool that serves as a modern replacement for Supervisor. Built on the lightweight, high‑reliability S6 suite, it is packaged by the just‑containers community for Docker use.

Why Use S6 Overlay with PHP?

PHP applications typically require two concurrent processes: a web server (NGINX or Apache) acting as a reverse proxy, and PHP‑FPM handling the PHP execution. S6 Overlay can coordinate these processes inside a single container, avoiding extra orchestration complexity.

Images That Include S6 Overlay

serversideup/php:*-fpm-apache

– Apache as reverse proxy + PHP‑FPM serversideup/php:*-fpm-nginx – NGINX as reverse proxy + PHP‑FPM

Variants such as cli or fpm that run only a single process do not need S6 Overlay.

Why PHP Needs Multiple Processes

PHP Application – Executes business logic, queries databases, renders pages.

Static Assets – JavaScript, CSS, images, fonts served directly to browsers.

Earlier, Apache’s mod_php combined both roles, leading to high memory and CPU usage because each Apache worker loaded a full PHP runtime even for static requests.

PHP‑FPM and Reverse Proxy

PHP‑FPM separates the PHP interpreter from the web server, creating a pool of workers that are invoked only when PHP code must run, dramatically reducing resource consumption. A reverse proxy (NGINX or Apache) is still required to serve static files and forward .php requests to PHP‑FPM via FastCGI.

Static file requests are served directly by NGINX/Apache, while .php requests are forwarded to PHP‑FPM, which selects an idle worker, executes the script, and returns the response through the proxy.

One‑Container‑One‑Process Myth

Although Docker best practices suggest a single process per container, real‑world PHP deployments often need both a web server and PHP‑FPM. Splitting them into separate containers introduces network, service‑discovery, and port‑mapping overhead that outweighs the benefits for small‑to‑medium projects.

Advantages of S6 Overlay

✅ Designed for containers – Built from the ground up for container environments.

✅ Fine‑grained start‑up control – Custom scripts can run before or after the main process (e.g., migrations, permission tweaks).

✅ Reliable health reporting – The container exits with a non‑zero code when a supervised service fails, allowing orchestrators to react.

✅ Lightweight – Implemented in C with minimal overhead.

Disadvantages of S6 Overlay

It may conflict with certain PaaS platforms that take over the init process or enforce their own process manager, requiring compatibility checks before deployment.

Comparison with Supervisor

Supervisor, popular before containers, runs as PID 1 and launches child processes. When a child like PHP‑FPM crashes, Supervisor can restart it, but the container’s PID 1 (supervisord) remains alive, causing orchestrators to think the container is healthy.

Result: Health status can be misleading, potentially routing traffic to a broken container.

S6 Overlay, by contrast, exits the entire container with a non‑zero code when a critical process cannot be recovered, allowing Kubernetes or Docker to restart the container promptly.

Result: More decisive and accurate failure detection.

Custom Initialization Workflow

S6 Overlay provides staged, dependency‑aware execution of custom scripts before the main php-fpm process starts.

runas-user

– Sets UID/GID for correct file permissions. laravel-automations – Executes migration, cache‑clear, and other automation tasks.

Both scripts must complete successfully before php-fpm starts, because php-fpm declares them as dependencies.

This mechanism gives precise control over startup order, enabling tasks such as database migrations, cache warm‑up, external service checks, or runtime configuration injection.