Getting Started

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:

VariationListens on
clinothing
fpm9000 (FastCGI)
fpm-nginx, fpm-apache, frankenphp8080 (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:

FilePurpose
serversideup-docker-php.iniOur defaults. Each setting reads an environment variable, such as memory_limit = ${PHP_MEMORY_LIMIT}. View it on GitHub.
zzz-serversideup-docker-php-debug.iniEmpty unless LOG_OUTPUT_LEVEL=debug, which writes display_errors and error_reporting overrides into it.
A file that sorts before 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:

ExtensionWhy it's included
mbstringMultibyte string functions. Laravel and PHPUnit require it. The official build stopped including it in PHP 8.6.
opcacheCaches 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.
pcntlSignal handling for Laravel queue timeouts and Horizon.
pdo_mysqlMySQL and MariaDB.
pdo_pgsqlPostgreSQL.
redisRedis for caching and queues. Horizon requires it.
zipReading and writing ZIP files, such as Laravel Dusk attachments.
mysqlifpm-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:

Terminal
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:

PackageVariationsUsed for
libfcgi-bin (Debian), fcgi (Alpine)fpm, fpm-nginx, fpm-apacheThe php-fpm-healthcheck script, which talks FastCGI to PHP-FPM.
gettext-base (Debian), gettext (Alpine)fpm-nginxenvsubst, which fills environment variables into the NGINX config templates at startup.
nginx (from nginx.org)fpm-nginxThe web server.
apache2 (from packages.sury.org)fpm-apacheThe web server. Debian's own package, rebuilt on each Apache release.
libstdc++6 (Debian), libstdc++ (Alpine)frankenphpThe file watcher FrankenPHP uses for --watch.
procpsAll Debian imagespgrep, which the Laravel health check scripts use. Alpine has it built in.
zipAll Debian imagesThe zip command.
shadowAll Alpine imagesusermod 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:

VariationAccess logError and runtime logDefault level
fpm-nginxstdoutstderrwarn
fpm-apachestdoutstderrwarn
fpmoffstderr (PHP-FPM closes stdout)warn
frankenphpstderrstderrinfo
clinonestderrwarn

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.

Some platforms treat 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.

ScriptWhat it doesVariations
0-container-info.shPrints 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.shApplies LOG_OUTPUT_LEVEL to PHP and PHP-FPM.all
5-fpm-pool-user.shWhen 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.shGenerates a self-signed certificate when SSL_MODE is not off and none is provided.fpm-nginx, fpm-apache, frankenphp
10-init-webserver-config.shBuilds the web server config from templates and enables the site for the current SSL_MODE.fpm-nginx, fpm-apache
50-laravel-automations.shWhen 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.

With 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.