Upgrade to v3
Version 3 rebuilt the images on the official PHP images and runs them as an unprivileged user. Most v2 setups need changes to ports, file ownership, and how extensions are installed.
Stay on v2 while you migrate
Add -v2.2.1 to your tag so you aren't upgraded before you're ready:
services:
php:
image: serversideup/php:8.2-fpm-nginx-v2.2.1
Breaking changes
| Change | Likelihood of impact | You're affected if |
|---|---|---|
| Web servers listen on 8080 and 8443 | High | You use fpm-nginx or fpm-apache |
Files belong to www-data, not webuser | High | You mount volumes or COPY files into the image |
| Debian and Alpine replace Ubuntu | High | Your Dockerfile runs Ubuntu commands or uses ppa:ondrej/php |
| Renamed and removed variables | Medium | You set any of the variables listed |
AUTORUN_ENABLED defaults to false | Medium | You rely on the Laravel automations |
SSL_MODE defaults to off | Medium | You relied on HTTPS by default |
S6 Overlay only in fpm-nginx and fpm-apache | Low | You added S6 services to cli or fpm |
| MSMTP is removed | Low | Your app sends mail through MSMTP |
Web servers listen on 8080 and 8443
Unprivileged users can't bind ports below 1024. NGINX and Apache now listen on 8080 for HTTP and 8443 for HTTPS. Update your port mappings, for example 80:8080 and 443:8443. See Default configurations.
Files belong to www-data, not webuser
Version 2 ran as webuser (UID 9999) with a login shell. Version 3 uses the www-data user that ships with the official PHP images: UID and GID 33 on Debian and 82 on Alpine.
chownmounted volumes on your hosts to match, for example33:33.- Copy files with the right owner:
COPY --chown=www-data:www-data . /var/www/html. - To match your own UID in development, see Understanding file permissions. For Docker Swarm host volumes, the change-volume-permissions script can help.
Debian and Alpine replace Ubuntu
The images build on the official PHP images, which use Debian or Alpine. PHP comes from php.net instead of ppa:ondrej/php. Remove Ubuntu-specific commands from your Dockerfile. Replace packages like php-redis with install-php-extensions. See Installing additional PHP extensions.
Renamed and removed variables
| v2 | v3 |
|---|---|
WEBUSER_HOME | APP_BASE_DIR |
DEBUG_OUTPUT | LOG_OUTPUT_LEVEL=debug |
PHP_POOL_NAME | PHP_FPM_POOL_NAME |
PHP_PM_CONTROL, PHP_PM_MAX_CHILDREN, PHP_PM_START_SERVERS, PHP_PM_MIN_SPARE_SERVERS, PHP_PM_MAX_SPARE_SERVERS | PHP_FPM_PM_CONTROL, PHP_FPM_PM_MAX_CHILDREN, PHP_FPM_PM_START_SERVERS, PHP_FPM_PM_MIN_SPARE_SERVERS, PHP_FPM_PM_MAX_SPARE_SERVERS. The old names are ignored, so your PHP-FPM tuning is lost until you rename them. |
PUID, PGID | Removed, because changing IDs at runtime needs root. See Understanding file permissions. |
MSMTP_RELAY_SERVER_HOSTNAME, MSMTP_RELAY_SERVER_PORT | Removed with MSMTP |
Check every variable you set against the environment variable reference.
AUTORUN_ENABLED defaults to false
The Laravel automations no longer run unless you set AUTORUN_ENABLED=true. See Laravel automations.
SSL_MODE defaults to off
The images serve HTTP only by default. Set SSL_MODE to turn HTTPS on. See Configuring SSL.
S6 Overlay only in fpm-nginx and fpm-apache
The other variations don't include S6 Overlay. Move start-up scripts for them to /etc/entrypoint.d. See Adding your own start-up scripts.
MSMTP is removed
MSMTP was removed for security and image size. Send mail through an external SMTP service. If you need MSMTP, install it in your own Dockerfile.
New features
- Built on the official PHP Docker images.
- Runs as an unprivileged user by default.
- Tags for an exact PHP patch, such as
8.2.12instead of8.2. - Start-up scripts in
/etc/entrypoint.d, with no S6 Overlay knowledge needed. - Laravel automations for
config:cache,route:cache,view:cache,event:cache,migrate --force --isolated, andstorage:link. - Images published to GitHub Packages as well as Docker Hub.
If your CI runs builds as root
Build a separate CI target that stays as root. Keep www-data for the image you deploy. When the container runs as root, the image sets PHP-FPM's worker user to www-data for you (PHP_FPM_CHILD_PROCESS_USER). Start from the multi-stage Dockerfile in Understanding file permissions and add a ci target that sets USER root.
Migration checklist
- Test in a non-production environment first.
- Update the image tag and the port mappings to
8080and8443. - Check every environment variable you set.
- In your Dockerfile, remove Ubuntu commands and
ppa:ondrej/php, install extensions withinstall-php-extensions, andCOPYwith--chown=www-data:www-data. chownhost volumes to33:33(Debian) or82:82(Alpine).- Add
PHP_OPCACHE_ENABLE=1in production. - Deploy.