Migrating from v2 to v3

If you're moving from v2 to v3, there are a number of changes you should be aware of. We've tried to keep these to a minimum, but some of these changes were necessary to make the project more maintainable and easier to use.

👉 Preparing for the migration

If you're an existing user of our v2 images, be sure that your current configurations are NOT set to use the latest images. To do this, you can lock your images into the v2.2.1 tag. This will ensure that you're not automatically upgraded to the v3 images.

For example, if you are using 8.2-fpm-nginx, you would change your docker-compose.yml file to use the v2.2.1 tag:

Original `docker-compose.yml` file

version: '3'
services:
  php:
    image: serversideup/php:8.2-fpm-nginx
    ports:
      - 80:80
    volumes:
      - .:/var/www/html

Updated `docker-compose.yml` file

version: '3'
services:
  php:
    image: serversideup/php:8.2-fpm-nginx-v2.2.1
    ports:
      - 80:80
    volumes:
      - .:/var/www/html

All you need to do is add -v2.2.1 to the end of the image tag. This will ensure that you're not automatically upgraded to the v3 images.

Testing the new images

You can start preparing for the upgrade by setting beta to the image tag. This will allow you to test the new images in a development environment and ensure everything works well for the upcoming release.

🚀 New Features

We've been busy overhauling our PHP Docker Images to make them more production-ready and easier to use. Here are some of the new features we've added:

  • Based on official PHP Images - We're now building an improved developer experience on top of the official PHP Docker images.
  • PHP 8.3 support - We're now shipping the latest and greatest.
  • Pin to the exact minor version - Pin your app to the exact minor version of PHP that you want to use. This means you can pin to 8.2.12 instead of 8.2.
  • Easier start up script customization - We now have a folder called /etc/entrypoint.d that allows you to easily customize your container with scripts. Just put them in numerical order and we'll execute any shell script you want. No S6 Overlay knowledge required.
  • Expanded Laravel Automations - We added automations to run config:cache, route:cache, view:cache, event:cache, migrate --force --isolated, and storage:link
  • NGINX Unit Support - We're offering NGINX Unit as a variation as an alternative to PHP-FPM. This allows you to run PHP applications without the need for a webserver like NGINX or Apache to run with PHP-FPM.
  • Available on GitHub Packages - We're now publishing our images to GitHub Packages. This means you can use our images without needing to authenticate with Docker Hub.

⚠️ Breaking changes

The following changes are considered to be "breaking changes" and will require you to make changes to your application.

Ubuntu is no longer used as a base image

We now use Debian or Alpine as our base OS (because we're using the official PHP images as a base). This is a huge change, but we're confident this will be the best direction moving forward.

ppa:ondrej/php is no longer used

Since we're using PHP.net as the "official source of truth" for getting our PHP versions, this means we're also dropping support for the ppa:ondrej/php repostory. If you're using things like apt-get install php-redis you will need to change your method of installing PHP extensions.

Learn how to install your own PHP extension →

webuser is no longer being used

We used to add a user called webuser with the UID of 9999, but in the current beta we're not. This is an area that we're still going to explore during the beta, so please chime in on the discussion if you have any thoughts.

If you have mounted volumes, you will need to chown the files to match the ID of the www-data user and groups. For Debian, this is 33:33 and for Alpine, this is 82:82.

S6 Overlay is only used in *-fpm-apache and *-fpm-nginx images

Due to compatibility issues, we only use S6 Overlay in our *-fpm-apache and *-fpm-nginx images. If you were using S6 Overlay for our other variations (cli, fpm, etc), you will need to migrate your scripts to use the new /etc/entrypoint.d folder.

SSL_MODE is now set to off by default (HTTP only)

Running end-to-end SSL by default created more problems than good. By default, we're now shipping HTTP-only by default with the option for people to turn this on.

AUTORUN_ENABLED is now set to false by default.

Having this set to "true" by default also created more problems than good. If you want to use any of the Laravel Automation Scripts, be sure to set this to true.

Variable deprecations

  • WEB_APP_DIRECTORY has now been renamed to APP_BASE_DIR
  • DEBUG_OUTPUT has been removed for in favor of LOG_OUTPUT_LEVEL=debug