Skip to content

Docker Compose Upgrade Guide

The intention of this document is to highlight the changes between our legacy and current Docker Compose stacks.

We recommend that developers use this document in conjunction with our skpr/examples repository for working examples.

Multi-Arch Docker Images

Skpr recently shipped image support for multiple architectures, most importantly, Apple Silicon.

As a result, all multi-arch Docker images are tagged as v2.

Below outlines the steps you will need to take to upgrade each Docker Compose service:

Nginx

Docker Compose Change

To upgrade you will need to update the image field for the Docker Compose nginx service.

Before:

image: skpr/nginx:1.x-dev

After:

Choose the image which aligns with your project.

# Standard
image: skpr/nginx:dev-v2-latest

# PHP-FPM
image: skpr/nginx-php-fpm:dev-v2-latest

# Drupal
image: skpr/nginx-drupal:dev-v2-latest

Nginx Configuration Change

The configuration directory structure for our Nginx images has changed to better support projects overriding our default values.

Please see the skpr/image-nginx for information on this directory structure.

There are 2 locations which you will need to consider updating.

  • Skpr Packaging (.skpr/package/nginx)
  • Docker Compose volumes

PHP-FPM

Docker Compose Change

To upgrade you will need to update the image field for the Docker Compose php-fpm service.

Before:

image: skpr/php-fpm:8.0-1.x-dev

After:

# Standard
image: skpr/php-fpm:8.0-dev-v2-latest

PHP-CLI

Docker Compose Change

To upgrade you will need to update the image field for the Docker Compose php-cli service.

Before:

image: skpr/php-cli:8.0-1.x-dev

After:

# Standard
image: skpr/php-cli:8.0-dev-v2-latest

VirtioFS

Docker Desktop recently shipped support for VirtioFS to resolve performance and file permissions issues.

To enable VirtioFS support see this Docker blog post.

Docker Compose Change

This results in a simplied Docker Compose configuration:

Before:

volumes:
  - data:/data

After:

volumes:
  - ./:/data

Remove the old volume:

volumes:
  data:
    driver: local
    driver_opts:
      o: bind
      type: none
      device: ${PWD}

Exec vs Run

Previously we adopted a docker-compose run model for our local development command line services eg. php-cli and node.

Recently we have noticed developers running into issues when using this approach in conjunction with our network_mode: service:nginx approach (make all services connect using localhost).

This issue has become more common in the recent releases of Docker Compose v1 and v2.

To avoid this issue and support all versions of Docker Compose, we decided to swap to a docker-compose exec model.

Command

Before:

docker-compose run php-cli bash

After:

docker-compose exec php-cli bash

Docker Compose Change

We use the sleep command so the service is running for docker-compose exec.

Before:

php-cli:
  image: skpr/php-cli:8.0-dev-v2-latest

After:

php-cli:
  image: skpr/php-cli:8.0-dev-v2-latest
  command: /bin/bash -c "sleep infinity"

Remove Additional Operating System Docker Compose Files

After applying the above changes (especially the VirtioFS change) you will notice that you do not require any of the OS specific files eg. OSX, Catalina or Linux.

Typically these files contain configuration related to NFS Support and/or OSX/Catalina paths. All of which have been resolved with the VirtioFS upgrade.

Review these files and delete where necessary.

Before:

docker-compose.catalina.yml
docker-compose.linux.yml
docker-compose.osx.yml
docker-compose.yml

After:

docker-compose.yml