Docker Multi-Stage Build Knowledge Base

Patterns and best practices for multi-stage Docker builds in PHP applications.

Multi-Stage Build Flow

┌─────────────────────────────────────────────────────────────────────────────┐
│                    MULTI-STAGE BUILD PIPELINE                                │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│   Stage 1: deps            Stage 2: extensions       Stage 3: build         │
│   ┌──────────────┐         ┌──────────────┐         ┌──────────────┐       │
│   │  Composer     │         │  PHP Ext     │         │  App Build   │       │
│   │  Install      │         │  Compile     │         │  Assets      │       │
│   │              │         │              │         │  Optimize    │       │
│   │  vendor/     │         │  *.so files  │         │  Cache warm  │       │
│   └──────┬───────┘         └──────┬───────┘         └──────┬───────┘       │
│          │                        │                        │               │
│          │    COPY --from=deps    │  COPY --from=extensions│               │
│          └────────────┐   ┌──────┘    ┌───────────────────┘               │
│                       │   │           │                                    │
│                       ▼   ▼           ▼                                    │
│                  ┌─────────────────────────┐                               │
│                  │   Stage 4: production    │                               │
│                  │   ┌───────────────────┐ │                               │
│                  │   │  Minimal base     │ │                               │
│                  │   │  + vendor/        │ │                               │
│                  │   │  + extensions     │ │                               │
│                  │   │  + app code       │ │                               │
│                  │   │  + optimized cfg  │ │                               │
│                  │   └───────────────────┘ │                               │
│                  │   Final image: ~80MB    │                               │
│                  └─────────────────────────┘                               │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Stage Naming Convention

deps

composer:2

extensions

php:8.4-fpm-alpine

build

php:8.4-cli-alpine

dev

php:8.4-fpm-alpine

production

php:8.4-fpm-alpine

Stage 1: Composer Dependencies

# syntax=docker/dockerfile:1
FROM composer:2 AS deps

WORKDIR /app

# Copy only dependency manifests first for layer caching
COPY composer.json composer.lock ./

# Install production deps only (no dev)
RUN composer install \
    --no-dev \
    --no-scripts \
    --no-autoloader \
    --prefer-dist \
    --no-interaction

# Copy source and dump optimized autoloader
COPY src/ src/
COPY config/ config/

RUN composer dump-autoload --optimize --classmap-authoritative

Stage 2: PHP Extensions Builder

FROM php:8.4-fpm-alpine AS extensions

RUN apk add --no-cache --virtual .build-deps \
        $PHPIZE_DEPS \
        icu-dev \
        libpq-dev \
        libzip-dev \
        freetype-dev \
        libjpeg-turbo-dev \
        libpng-dev \
    && docker-php-ext-configure gd \
        --with-freetype --with-jpeg \
    && docker-php-ext-install -j$(nproc) \
        intl \
        pdo_pgsql \
        zip \
        gd \
        opcache \
    && pecl install redis apcu \
    && docker-php-ext-enable redis apcu \
    && apk del .build-deps

Stage 3: Production Final

FROM php:8.4-fpm-alpine AS production

# Runtime-only dependencies (no build tools)
RUN apk add --no-cache \
    icu-libs \
    libpq \
    libzip \
    freetype \
    libjpeg-turbo \
    libpng

# Copy compiled extensions from builder stage
COPY --from=extensions /usr/local/lib/php/extensions/ /usr/local/lib/php/extensions/
COPY --from=extensions /usr/local/etc/php/conf.d/ /usr/local/etc/php/conf.d/

# Copy vendor directory from deps stage
COPY --from=deps /app/vendor /app/vendor

# Copy application code
COPY . /app

WORKDIR /app

# PHP production configuration
RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini"

USER www-data

EXPOSE 9000
CMD ["php-fpm"]

Cache Optimization Patterns

BuildKit Cache Mounts

# Cache composer packages across builds
RUN --mount=type=cache,target=/root/.composer/cache \
    composer install --no-dev --optimize-autoloader

# Cache APK packages across builds
RUN --mount=type=cache,target=/var/cache/apk \
    apk add --no-cache icu-dev libpq-dev

Layer Ordering for Cache Hits

# Ordered from least to most frequently changed:
1. Base image + system packages     (rarely changes)
2. PHP extensions                   (changes with requirements)
3. Composer dependencies            (changes with composer.lock)
4. Application configuration        (changes occasionally)
5. Application source code          (changes frequently)

Cache From Pattern (CI/CD)

# Build with cache from registry
docker build \
    --cache-from=registry.io/app:deps-cache \
    --cache-from=registry.io/app:latest \
    --target production \
    -t registry.io/app:latest .

ARG Scoping Across Stages

# Global ARG (before first FROM) — available in FROM lines only
ARG PHP_VERSION=8.4

FROM php:${PHP_VERSION}-fpm-alpine AS base
# PHP_VERSION is NOT available here unless redeclared
ARG PHP_VERSION
RUN echo "Building with PHP ${PHP_VERSION}"

FROM php:${PHP_VERSION}-cli-alpine AS build
# Must redeclare ARG in each stage that needs it
ARG APP_ENV=prod
RUN echo "Building for ${APP_ENV}"

COPY --from Patterns

# Copy from named stage
COPY --from=deps /app/vendor /app/vendor

# Copy from external image
COPY --from=composer:2 /usr/bin/composer /usr/local/bin/composer

# Copy specific extension files
COPY --from=extensions /usr/local/lib/php/extensions/no-debug-non-zts-*/ \
    /usr/local/lib/php/extensions/no-debug-non-zts-*/

# Copy with ownership
COPY --from=build --chown=www-data:www-data /app /app

Parallel Builds with BuildKit

# Enable BuildKit for parallel stage execution
DOCKER_BUILDKIT=1 docker build .

# Or via docker buildx
docker buildx build --target production .

BuildKit automatically detects independent stages and builds them in parallel:

deps ──────────────┐
                    ├──▶ production
extensions ────────┘
     │
build ──── (depends on deps, runs after)

Target Selection

# Build only development image
docker build --target dev -t app:dev .

# Build only production image
docker build --target production -t app:prod .

# Build specific intermediate stage for debugging
docker build --target extensions -t app:ext-debug .

Minimizing Final Image

php:8.4-fpm-alpine

php:8.4-fpm

.dockerignore

.git

tests/

docs/

composer install --no-dev

--classmap-authoritative

apk add --no-cache

rm -rf /var/cache/apk/*

References

For base image selection guidance, see

docker-base-images-knowledge

docker-php-extensions-knowledge