Vengala Vinay

Having 12+ Years of Experience in Software Development

Home » Beyond the Basics: Advanced Docker Multi-Stage Builds for Optimized Laravel Deployment & PHP 9 Readiness

Beyond the Basics: Advanced Docker Multi-Stage Builds for Optimized Laravel Deployment & PHP 9 Readiness

Optimizing Laravel Docker Images with Multi-Stage Builds

For modern PHP applications, particularly those built with frameworks like Laravel, Docker has become an indispensable tool for consistent development, testing, and deployment. However, a naive `Dockerfile` can lead to bloated images, increasing build times, deployment footprints, and potential attack surfaces. Multi-stage builds offer a sophisticated solution to this problem by allowing us to use multiple `FROM` instructions in a single `Dockerfile`, discarding intermediate build artifacts and keeping only the essential components in the final image.

This approach is particularly beneficial for PHP applications where development dependencies (like compilers, build tools, and testing frameworks) are distinct from production runtime requirements. We can leverage a “builder” stage to compile assets, install Composer dependencies, and perform other build-time tasks, then copy only the necessary artifacts to a lean “runtime” stage.

A Practical Multi-Stage Dockerfile for Laravel

Let’s construct a `Dockerfile` that exemplifies this strategy. We’ll use a PHP base image that includes common extensions, a builder stage for Composer and Node.js dependencies, and a final runtime stage based on a minimal PHP image.

Consider the following `Dockerfile`:

This `Dockerfile` is structured into three distinct stages:

  • Builder Stage (`builder`): This stage starts from a comprehensive PHP image (`php:8.3-fpm-deps`) which includes essential build tools like `gcc`, `make`, and `autoconf`, along with common PHP extensions. It then installs Node.js and npm for frontend asset compilation. Composer dependencies are installed, and frontend assets are built using npm.
  • Runtime Stage (`app`): This stage is based on a minimal PHP image (`php:8.3-fpm-alpine`). It copies the compiled Composer dependencies and the application code from the `builder` stage. Crucially, it *does not* include development dependencies or build tools.
  • Nginx Stage (`webserver`): A separate stage for Nginx is defined, using a lean `nginx:alpine` image. It copies the application code and the compiled assets from the `app` stage and configures Nginx to serve static files and proxy dynamic requests to the PHP-FPM service.
# syntax=docker/dockerfile:1

# --- Builder Stage ---
FROM php:8.3-fpm-deps AS builder

# Install system dependencies and PHP extensions
RUN apt-get update && apt-get install -y \
    git \
    unzip \
    libzip-dev \
    libpng-dev \
    libjpeg-dev \
    libfreetype6-dev \
    libssl-dev \
    libonig-dev \
    libxml2-dev \
    zip \
    && docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install -j$(nproc) gd \
    && docker-php-ext-install pdo pdo_mysql zip bcmath opcache sockets

# Install Node.js and npm
RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && \
    apt-get install -y nodejs

# Install Composer
COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

# Set working directory
WORKDIR /var/www/html

# Copy application files
COPY . .

# Install Composer dependencies
RUN composer install --no-dev --optimize-autoloader --no-interaction

# Install npm dependencies and build frontend assets
RUN npm install && npm run build

# --- Application Runtime Stage ---
FROM php:8.3-fpm-alpine AS app

# Install necessary PHP extensions for runtime
RUN apk add --no-cache \
    libzip-dev \
    libpng-dev \
    libjpeg-turbo-dev \
    freetype-dev \
    openssl-dev \
    libzip \
    libwebp-dev \
    libzip-dev \
    oniguruma-dev \
    icu-dev \
    && docker-php-ext-configure gd --with-freetype --with-jpeg --with-webp \
    && docker-php-ext-install -j$(nproc) gd \
    && docker-php-ext-install pdo pdo_mysql zip bcmath opcache sockets intl \
    && apk del --no-cache freetype-dev libjpeg-turbo-dev libpng-dev libwebp-dev oniguruma-dev icu-dev

# Copy application code and Composer dependencies from builder stage
COPY --from=builder /var/www/html /var/www/html

# Clean up development dependencies (if any were accidentally copied)
RUN rm -rf /var/www/html/vendor/phpunit \
    && rm -rf /var/www/html/vendor/laravel/sail \
    && rm -rf /var/www/html/node_modules

# Expose port for PHP-FPM
EXPOSE 9000

# Set user and group
RUN chown -R www-data:www-data /var/www/html \
    && chmod -R 755 /var/www/html

# Default command to run PHP-FPM
CMD ["php-fpm"]

# --- Nginx Webserver Stage ---
FROM nginx:alpine AS webserver

# Copy application code and compiled assets from app stage
COPY --from=app /var/www/html /var/www/html

# Copy Nginx configuration
COPY docker/nginx/default.conf /etc/nginx/conf.d/default.conf

# Expose port 80
EXPOSE 80

# Start Nginx in foreground
CMD ["nginx", "-g", "daemon off;"]

Explanation of Key Sections and Optimizations

Let’s break down the critical parts of this `Dockerfile` and the reasoning behind the choices made.

Builder Stage: Compiling and Installing Dependencies

The `builder` stage is where the heavy lifting of dependency installation and asset compilation occurs. We start with `php:8.3-fpm-deps` because it provides a more feature-rich environment for compilation compared to minimal Alpine images. This includes essential build tools and common PHP extensions that might be required by Composer packages.

System Dependencies:

RUN apt-get update && apt-get install -y \
    git \
    unzip \
    libzip-dev \
    libpng-dev \
    libjpeg-dev \
    libfreetype6-dev \
    libssl-dev \
    libonig-dev \
    libxml2-dev \
    zip \
    && docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install -j$(nproc) gd \
    && docker-php-ext-install pdo pdo_mysql zip bcmath opcache sockets

Here, we install common development tools and libraries needed for PHP extensions. `docker-php-ext-install` is a script provided by the official PHP Docker images to simplify extension compilation and installation. We enable `gd` with freetype and jpeg support, and other crucial extensions like `pdo_mysql`, `zip`, `bcmath`, `opcache`, and `sockets`.

Node.js and Composer:

# Install Node.js and npm
RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && \
    apt-get install -y nodejs

# Install Composer
COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

We install Node.js from NodeSource for frontend asset management. Composer is copied from the official `composer:latest` image, which is a highly optimized image for Composer itself. This avoids installing Composer via `apt` or compiling it manually.

Dependency Installation and Asset Building:

WORKDIR /var/www/html
COPY . .
RUN composer install --no-dev --optimize-autoloader --no-interaction
RUN npm install && npm run build

The application code is copied into the working directory. Composer dependencies are installed with flags to disable development packages (`–no-dev`), optimize the autoloader, and prevent interactive prompts. Subsequently, `npm install` and `npm run build` compile frontend assets (e.g., JavaScript, CSS) using tools like Vite or Webpack.

Application Runtime Stage: The Lean Final Image

The `app` stage is designed to be as small and secure as possible. It starts from `php:8.3-fpm-alpine`, which is a minimal image based on Alpine Linux, significantly reducing the image size.

Runtime Extensions:

FROM php:8.3-fpm-alpine AS app
RUN apk add --no-cache \
    libzip-dev \
    libpng-dev \
    libjpeg-turbo-dev \
    freetype-dev \
    openssl-dev \
    libzip \
    libwebp-dev \
    libzip-dev \
    oniguruma-dev \
    icu-dev \
    && docker-php-ext-configure gd --with-freetype --with-jpeg --with-webp \
    && docker-php-ext-install -j$(nproc) gd \
    && docker-php-ext-install pdo pdo_mysql zip bcmath opcache sockets intl \
    && apk del --no-cache freetype-dev libjpeg-turbo-dev libpng-dev libwebp-dev oniguruma-dev icu-dev

While Alpine images are small, they often require installing build dependencies (`-dev` packages) to compile extensions. We install the necessary runtime extensions, including `intl` for internationalization, which is common in Laravel applications. The `apk del` command cleans up build-time dependencies after extensions are compiled.

Copying Artifacts:

COPY --from=builder /var/www/html /var/www/html

This is the core of the multi-stage benefit: we only copy the compiled application code and the `vendor` directory (containing production Composer dependencies) from the `builder` stage. All build tools, development dependencies, and intermediate build artifacts are left behind.

Security and Cleanup:

RUN rm -rf /var/www/html/vendor/phpunit \
    && rm -rf /var/www/html/vendor/laravel/sail \
    && rm -rf /var/www/html/node_modules

Explicitly removing any remaining development-specific directories (like `phpunit` or `laravel/sail`) further hardens the image and reduces its size. Removing `node_modules` is also a good practice if they were not fully excluded by `npm run build` or if they contain development-specific tools.

User and Permissions:

RUN chown -R www-data:www-data /var/www/html \
    && chmod -R 755 /var/www/html

Setting the correct ownership and permissions for the application directory is crucial for PHP-FPM to operate correctly. `www-data` is the standard user for web servers in Debian/Ubuntu-based images, and `nginx` in Alpine-based images.

Nginx Webserver Stage: Serving the Application

A separate `webserver` stage is defined for Nginx. This promotes separation of concerns and allows for independent scaling and configuration of the web server and the PHP application.

FROM nginx:alpine AS webserver
COPY --from=app /var/www/html /var/www/html
COPY docker/nginx/default.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

This stage copies the entire application from the `app` stage, including the compiled PHP code and assets. It then overlays a custom Nginx configuration (`docker/nginx/default.conf`) which is essential for routing requests correctly. The `nginx:alpine` image is minimal and efficient.

Nginx Configuration for Laravel

A typical Nginx configuration for a Laravel application served via PHP-FPM would look like this:

server {
    listen 80;
    server_name localhost;
    root /var/www/html/public;

    index index.php index.html index.htm;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_pass php-fpm:9000; # Assuming PHP-FPM is running on a service named 'php-fpm'
        fastcgi_index index.php;
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
    }

    location ~ /\.ht {
        deny all;
    }

    # Serve static assets directly
    location ~* \.(css|js|jpg|jpeg|gif|png|svg|ico|webp)$ {
        expires 1y;
        add_header Cache-Control "public";
    }
}

This configuration:

  • Sets the document root to `/var/www/html/public`.
  • Uses `try_files` to handle routing for the Laravel framework.
  • Configures FastCGI to pass PHP requests to the PHP-FPM service (which would be running in a separate container, typically linked via Docker Compose). The `fastcgi_pass php-fpm:9000;` directive assumes a service named `php-fpm` is available.
  • Denies access to `.htaccess` files.
  • Optimizes serving of static assets by setting cache headers.

Preparing for PHP 9 and Beyond

As PHP evolves, new versions introduce changes that might require adjustments to your build process and runtime environment. Multi-stage builds provide a robust framework for managing these transitions:

  • Version Pinning: The `Dockerfile` explicitly uses `php:8.3-fpm-deps` and `php:8.3-fpm-alpine`. When PHP 9 is released, you would update these tags to `php:9.0-fpm-deps` and `php:9.0-fpm-alpine` (or their respective versions).
  • Extension Compatibility: New PHP versions might deprecate or change extensions. The `RUN` commands for installing and configuring extensions will need to be reviewed and updated. For example, if a new extension is required or an existing one is replaced, the `apt-get install` or `apk add` commands and `docker-php-ext-install` calls will need modification.
  • Dependency Updates: Composer and npm dependencies might need updates to be compatible with newer PHP versions. The `composer install` and `npm install` steps will naturally pick up these updated dependencies if your `composer.json` and `package.json` are configured correctly.
  • Build Tools: If PHP 9 requires newer compilers or build tools, the `apt-get install` or `apk add` commands in the `builder` stage will need to be updated to include these new requirements.
  • Testing: A critical part of migrating to a new PHP version is thorough testing. Ensure your CI/CD pipeline, which would likely build these Docker images, includes comprehensive test suites that run against the new PHP version before deploying to production.

By abstracting the build environment from the runtime environment, multi-stage builds make it significantly easier to manage these version upgrades. You can test the new PHP version in a dedicated build stage without affecting your existing production image, and then seamlessly switch to the new version once validated.

Building and Running the Docker Images

To build these images, you would typically use the following command from the root of your project:

docker build -t my-laravel-app:latest .

This command builds the entire multi-stage `Dockerfile` and tags the final `webserver` stage as `my-laravel-app:latest`. The intermediate stages (`builder` and `app`) are used during the build process but are not directly accessible as tagged images unless explicitly specified.

For a typical Laravel deployment, you would use Docker Compose to manage the multiple services (Nginx, PHP-FPM, and potentially a database like MySQL or PostgreSQL). A simplified `docker-compose.yml` might look like this:

version: '3.8'

services:
  nginx:
    build:
      context: .
      dockerfile: Dockerfile
      target: webserver # Specify the target stage
    ports:
      - "80:80"
    volumes:
      - .:/var/www/html # Mount for development, remove for production builds
    depends_on:
      - php-fpm
    networks:
      - app-network

  php-fpm:
    build:
      context: .
      dockerfile: Dockerfile
      target: app # Specify the target stage
    volumes:
      - .:/var/www/html # Mount for development, remove for production builds
    expose:
      - "9000"
    networks:
      - app-network

  # Example database service (optional)
  # db:
  #   image: mysql:8.0
  #   volumes:
  #     - db_data:/var/lib/mysql
  #   environment:
  #     MYSQL_ROOT_PASSWORD: rootpassword
  #     MYSQL_DATABASE: laravel
  #   networks:
  #     - app-network

networks:
  app-network:
    driver: bridge

# volumes:
#   db_data:

In this `docker-compose.yml`:

  • We specify the `target` for each service to build only the necessary stage from the `Dockerfile`. This is crucial for efficiency.
  • The `nginx` service depends on `php-fpm`.
  • Volumes are mounted for development convenience. For production, you would typically build the image once and deploy it without host volume mounts for the application code.
  • A network (`app-network`) is defined to allow services to communicate.

To run this setup:

docker-compose up --build

This command will build the images (if not already built) and start the containers. The application will be accessible at `http://localhost`.

Conclusion

Mastering Docker multi-stage builds is a significant step towards creating efficient, secure, and maintainable containerized applications. For Laravel projects, this technique drastically reduces image size, speeds up build times, and simplifies the management of dependencies and build artifacts. Furthermore, it provides a robust and adaptable foundation for future upgrades, including readiness for new PHP versions like PHP 9, ensuring your deployment pipeline remains agile and resilient.

Recent Posts

Top Categories

Our Products

Our Services