Default configurations
The official PHP image gives you PHP. Everything a production container needs on top of that is yours to add: a safe user, the right extensions, health checks, and logs your platform can read. Our images ship with all of it set up. Here's every default, and how to change each one.
Runs as www-data, not root
Every image runs as www-data. If someone exploits your app, they get an unprivileged user inside the container instead of root. Many Kubernetes clusters also require non-root containers.
On Linux, only root can listen on ports below 1024. Our web servers use higher ports:
| Variation | Listens on |
|---|---|
cli | nothing |
fpm | 9000 (FastCGI) |
fpm-nginx, fpm-apache, frankenphp | 8080 (HTTP) and 8443 (HTTPS) |
Map them to 80 and 443 on the host (80:8080) or put a reverse proxy in front. See Configuring SSL.
www-data keeps the operating system's own IDs: 33:33 on Debian and 82:82 on Alpine. Files you mount or copy in must be readable by that user. Switching between Debian and Alpine changes the owner you need. See Understanding file permissions.
Every setting is an environment variable
PHP, PHP-FPM, and web server settings come from environment variables. The image applies them each time the container starts. The defaults are production values.
There's no php.ini to mount and no config file to edit. Change a setting in your Compose file and restart the container. The environment variable specification lists every variable, its default, and which variations read it.
Your own ini files still work
PHP loads every .ini file in /usr/local/etc/php/conf.d/ in alphabetical order. A later file overrides an earlier one. Our image adds two:
| File | Purpose |
|---|---|
serversideup-docker-php.ini | Our defaults. Each setting reads an environment variable, such as memory_limit = ${PHP_MEMORY_LIMIT}. View it on GitHub. |
zzz-serversideup-docker-php-debug.ini | Empty unless LOG_OUTPUT_LEVEL=debug, which writes display_errors and error_reporting overrides into it. |
serversideup-docker-php.ini, such as custom.ini or php.ini, loads first, and our defaults override it. Name yours so it sorts after, such as zzz-custom-php.ini.For most settings, an environment variable is simpler than an ini file. See Changing php.ini settings.
The extensions Laravel and WordPress reach for
We add these extensions to the ones the official PHP build includes:
| Extension | Why it's included |
|---|---|
| mbstring | Multibyte string functions. Laravel and PHPUnit require it. The official build stopped including it in PHP 8.6. |
| opcache | Caches compiled PHP. It's off by default, so code edits show up right away. Set PHP_OPCACHE_ENABLE=1 in production. See Production performance tuning. |
| pcntl | Signal handling for Laravel queue timeouts and Horizon. |
| pdo_mysql | MySQL and MariaDB. |
| pdo_pgsql | PostgreSQL. |
| redis | Redis for caching and queues. Horizon requires it. |
| zip | Reading and writing ZIP files, such as Laravel Dusk attachments. |
| mysqli | fpm-apache only. WordPress uses it. |
The official build already includes ctype, curl, dom, fileinfo, filter, openssl, pdo_sqlite, session, sodium, tokenizer, xml, and others. To list everything an image has, run:
docker run --rm serversideup/php:8.5-cli php -m
Need another one? install-php-extensions intl adds it. See Installing additional PHP extensions.
Composer and the tools you'd install anyway
Composer 2 and install-php-extensions are in every image. We also add a few operating system packages, each for a reason:
| Package | Variations | Used for |
|---|---|---|
libfcgi-bin (Debian), fcgi (Alpine) | fpm, fpm-nginx, fpm-apache | The php-fpm-healthcheck script, which talks FastCGI to PHP-FPM. |
gettext-base (Debian), gettext (Alpine) | fpm-nginx | envsubst, which fills environment variables into the NGINX config templates at startup. |
nginx (from nginx.org) | fpm-nginx | The web server. |
apache2 (from packages.sury.org) | fpm-apache | The web server. Debian's own package, rebuilt on each Apache release. |
libstdc++6 (Debian), libstdc++ (Alpine) | frankenphp | The file watcher FrankenPHP uses for --watch. |
procps | All Debian images | pgrep, which the Laravel health check scripts use. Alpine has it built in. |
zip | All Debian images | The zip command. |
shadow | All Alpine images | usermod and groupmod, which docker-php-serversideup-set-id uses to change the www-data IDs. |
Health checks are built in
Every image except cli ships a Docker HEALTHCHECK that works with no configuration. The web server variations request /healthcheck on their HTTP port. fpm asks PHP-FPM's status page.
Set HEALTHCHECK_PATH: "/up" to check that Laravel boots, not only the web server. Health checks covers how each variation checks itself. Laravel health checks covers /up and the scripts for queue, Horizon, and scheduler containers.
Logs go where your platform looks
Every variation writes logs to the container's stdout and stderr, never to files. docker logs, Kubernetes, and log collectors pick them up with no setup. Each web server follows its own official image:
| Variation | Access log | Error and runtime log | Default level |
|---|---|---|---|
fpm-nginx | stdout | stderr | warn |
fpm-apache | stdout | stderr | warn |
fpm | off | stderr (PHP-FPM closes stdout) | warn |
frankenphp | stderr | stderr | info |
cli | none | stderr | warn |
PHP errors go to stderr in every variation (PHP_ERROR_LOG=/dev/stderr). LOG_OUTPUT_LEVEL sets the level for PHP, PHP-FPM, and the web server together.
FrankenPHP follows Caddy and the official FrankenPHP image. Its access log and runtime log share one structured format, with a level on every entry. Both go to stderr. The format is JSON unless stderr is a terminal (CADDY_LOG_FORMAT=auto). Laravel Octane only reads stderr. If you use Octane, leave CADDY_LOG_OUTPUT at its default.
stderr as errors. Google Kubernetes Engine, for example, tags stderr as ERROR unless the entry is JSON with a severity. FrankenPHP's JSON entries carry a level your pipeline can map. For the other variations, move a log with NGINX_ACCESS_LOG, NGINX_ERROR_LOG, or PHP_ERROR_LOG.Startup scripts prepare the container
Before the main process starts, the entrypoint runs every .sh file in /etc/entrypoint.d/ in version-sort order (sort -V). That means 5-* runs before 10-*. Add your own scripts to the same folder. Adding your own start-up scripts explains the order.
| Script | What it does | Variations |
|---|---|---|
0-container-info.sh | Prints the image and PHP versions, the user and its IDs, and key PHP settings. SHOW_WELCOME_MESSAGE=false hides it. | all |
1-log-output-level.sh | Applies LOG_OUTPUT_LEVEL to PHP and PHP-FPM. | all |
5-fpm-pool-user.sh | When the container runs as root, sets the PHP-FPM pool's user and group to PHP_FPM_CHILD_PROCESS_USER and PHP_FPM_CHILD_PROCESS_GROUP. | fpm, fpm-nginx, fpm-apache |
5-generate-ssl.sh | Generates a self-signed certificate when SSL_MODE is not off and none is provided. | fpm-nginx, fpm-apache, frankenphp |
10-init-webserver-config.sh | Builds the web server config from templates and enables the site for the current SSL_MODE. | fpm-nginx, fpm-apache |
50-laravel-automations.sh | When AUTORUN_ENABLED=true, runs php artisan storage:link, php artisan migrate --force, then php artisan optimize. See Laravel automations. | all |
Set DISABLE_DEFAULT_CONFIG=true to skip all of these scripts. Your own scripts in /etc/entrypoint.d/ still run.
DISABLE_DEFAULT_CONFIG=true, fpm-nginx has no nginx.conf and fpm-apache has no site enabled, because 10-init-webserver-config.sh builds both. Provide your own web server configuration before you set it.