How I built a 120MB production Laravel Docker image (and why yours is probably 800MB)

Akandwanaho Alvin — Wed, 03 Jun 2026 07:04:59 +0000

Most Laravel Docker tutorials give you a Dockerfile that produces an 800MB image. Mine is 120MB. Here is exactly how — and why it matters.

The problem with a single-stage Dockerfile

When you install Composer, Node.js, npm, and all your dev dependencies in one layer, every single one of those tools ends up in your production image. Your image carries gigabytes of software that has zero business being on a production server.

The solution: multi-stage builds

Docker lets you define multiple stages in one Dockerfile. Stage 1 does all the heavy lifting — installing Composer, running npm, compiling your Vite assets. Stage 2 starts completely fresh, copies only the compiled output, and ships nothing else.

# Stage 1: builder — installs everything, compiles assets
FROM php:8.3-cli AS builder
RUN apt-get update && apt-get install -y git nodejs npm \
    && curl -sS https://getcomposer.org/installer | php \
    && mv composer.phar /usr/local/bin/composer

WORKDIR /app
COPY composer.json composer.lock ./
RUN composer install --no-dev --optimize-autoloader

COPY package.json package-lock.json ./
RUN npm ci && npm run build

COPY . .

# Stage 2: production — starts clean, copies compiled output only
FROM php:8.3-fpm-alpine AS production

RUN apk add --no-cache nginx supervisor
COPY --from=builder /app /var/www/html
EXPOSE 80
CMD ["/usr/bin/supervisord", "-c", "/etc/supervisord.conf"]

The result

	Single-stage	Multi-stage
Image size	~800MB	~120MB
Build tools in prod	Yes (security risk)	No
Deploy speed	Slow	Fast

What goes in each stage

Stage 1 needs: Composer, Node.js, npm, git, dev headers for PHP extensions.
Stage 2 needs: PHP-FPM, Nginx, Supervisor, and the compiled app. Nothing else.

The order of COPY matters for caching

Copy composer.json BEFORE the rest of your code. Docker caches each layer — if your PHP files change but composer.json didn't, Docker skips reinstalling all your packages. This alone saves 2–3 minutes per build.

COPY composer.json composer.lock ./   # cached unless deps change
RUN composer install --no-dev
COPY . .                              # only this layer re-runs on code changes

Try it yourself

Build once with a naive Dockerfile, then build with the multi-stage version. Run docker images and compare the sizes. The difference will change how you think about Docker forever.

I wrote a full 50-page guide covering this entire stack — Docker, GitHub Actions CI/CD, Kubernetes, and SQLite as the production database. Link in my profile if you want the complete setup.

Deploying Laravel with Docker, GitHub Actions, and Kubernetes

Akandwanaho Alvin — Tue, 02 Jun 2026 22:49:36 +0000

Chapter 3: The Dockerfile — Multi-Stage Build
3.1 Why Multi-Stage Builds?
A naive Dockerfile installs everything (Composer, Node.js, npm, dev dependencies) in a single layer. The resulting image is hundreds of megabytes larger than it needs to be and may contain security vulnerabilities from build tools that have no business being in production.
Multi-stage builds solve this by separating the build environment from the runtime environment:
• Stage 1 (builder): Has Composer, Node.js, npm, and all dev tooling installed. Installs production PHP dependencies and compiles JavaScript assets.
• Stage 2 (production): Starts from a clean Alpine Linux base. Copies only the compiled output from Stage 1. Contains nothing that is not needed at runtime.

Metric Single-Stage vs Multi-Stage
Image size ~800MB vs ~120MB
Attack surface High (build tools, dev deps) vs Low (runtime only)
Build caching Poor vs Excellent (stages cache independently)
Security scanning Many CVEs from build tools vs Minimal

3.2 The Complete Dockerfile
docker/Dockerfile

# ─────────────────────────────────────────────────────────────────────────
# Stage 1: builder
# Installs all dependencies and compiles assets.
# This stage is NEVER shipped to production.
# ─────────────────────────────────────────────────────────────────────────
FROM php:8.3-cli AS builder

# Install system dependencies needed during the build phase:
#   git      - Composer needs this to clone packages from GitHub
#   zip/unzip - needed for PHP archive operations
#   libpng-dev, libonig-dev, libxml2-dev - headers for PHP extensions
#   nodejs, npm - for compiling JS assets with Vite
RUN apt-get update && apt-get install -y \
    git curl zip unzip \
    libpng-dev libonig-dev libxml2-dev \
    nodejs npm \
    && docker-php-ext-install pdo pdo_sqlite mbstring exif pcntl bcmath gd \
    && curl -sS https://getcomposer.org/installer | php \
    && mv composer.phar /usr/local/bin/composer \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app

# Copy composer files first to leverage Docker layer caching.
# If composer.json and composer.lock have not changed, Docker reuses
# the cached layer even if application code has changed.
COPY composer.json composer.lock ./
RUN composer install \
    --no-dev \
    --optimize-autoloader \
    --no-interaction \
    --no-scripts

# Copy package.json for the same caching benefit
COPY package.json package-lock.json ./
RUN npm ci

# Now copy the rest of the application code
COPY . .

# Run Composer scripts now that the full codebase is present
RUN composer run-script post-autoload-dump --no-interaction 2>/dev/null || true

# Compile JavaScript/CSS assets
RUN npm run build

# ─────────────────────────────────────────────────────────────────────────
# Stage 2: production
# Lean Alpine-based image. Only runtime dependencies.
# ─────────────────────────────────────────────────────────────────────────
FROM php:8.3-fpm-alpine AS production

# Install runtime system packages:
#   nginx      - HTTP server to accept incoming requests
#   supervisor - process manager to run both nginx and php-fpm
#   sqlite     - SQLite runtime libraries
RUN apk add --no-cache \
    nginx \
    supervisor \
    sqlite \
    && docker-php-ext-install pdo pdo_sqlite mbstring exif pcntl bcmath

WORKDIR /var/www/html

# Copy the compiled application from the builder stage.
# Crucially, we do NOT copy node_modules or dev dependencies.
COPY --from=builder /app /var/www/html

# Copy configuration files
COPY docker/nginx.conf      /etc/nginx/nginx.conf
COPY docker/php.ini         /usr/local/etc/php/conf.d/custom.ini
COPY docker/supervisord.conf /etc/supervisord.conf

# Create the SQLite database directory.
# The actual .sqlite file will come from a PersistentVolumeClaim in k8s.
# Locally it will be mounted via Docker volume.
RUN mkdir -p /var/www/html/database

# Fix storage permissions.
# www-data is the nginx/php-fpm user.
RUN chown -R www-data:www-data \
      /var/www/html/storage \
      /var/www/html/bootstrap/cache \
      /var/www/html/database \
    && chmod -R 775 \
      /var/www/html/storage \
      /var/www/html/bootstrap/cache \
      /var/www/html/database

# Optimise Laravel for production
RUN php artisan config:cache \
    && php artisan route:cache \
    && php artisan view:cache

EXPOSE 80

# Supervisord starts both nginx and php-fpm
CMD ["/usr/bin/supervisord", "-c", "/etc/supervisord.conf"]

3.3 Nginx Configuration
Nginx acts as the front-facing HTTP server inside the container. It serves static assets (CSS, JS, images) directly from disk and proxies all PHP requests to PHP-FPM via FastCGI.

docker/nginx.conf
# We use the events block even though we are not customising it.
# Nginx requires it.
events {
    worker_connections 1024;
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    # Logging — output to stdout/stderr so kubectl logs works
    access_log  /dev/stdout;
    error_log   /dev/stderr warn;

    # Basic performance settings
    sendfile           on;
    keepalive_timeout  65;
    gzip               on;
    gzip_types         text/plain application/json application/javascript text/css;

    server {
        listen 80;
        server_name _;
        root /var/www/html/public;
        index index.php;

        # Laravel's try_files pattern:
        # 1. Try to serve the exact file ($uri)
        # 2. Try to serve as a directory ($uri/)
        # 3. Fall back to index.php with the query string
        location / {
            try_files $uri $uri/ /index.php?$query_string;
        }

        # Send all .php files to PHP-FPM running on port 9000
        location ~ \.php$ {
            fastcgi_pass  127.0.0.1:9000;
            fastcgi_index index.php;
            include       fastcgi_params;
            fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
            fastcgi_param PATH_INFO $fastcgi_path_info;
            fastcgi_read_timeout 300;
        }

        # Deny access to .htaccess and other hidden files
        location ~ /\.ht {
            deny all;
        }

        # Deny direct access to the SQLite database file
        location ~ \.sqlite$ {
            deny all;
        }
    }
}

3.4 PHP Configuration

docker/php.ini
; Production PHP settings for a Laravel API

; Memory limit — increase for large Eloquent operations
memory_limit = 256M

; Maximum execution time in seconds
max_execution_time = 60

; Maximum POST body size (for file uploads via API)
post_max_size = 20M
upload_max_filesize = 20M

; Hide PHP version from response headers (security)
expose_php = Off

; Disable error display in responses; log to stderr instead
display_errors = Off
log_errors = On
error_log = /dev/stderr


; OPcache — dramatically speeds up PHP by caching compiled bytecode
opcache.enable = 1
opcache.memory_consumption = 128
opcache.interned_strings_buffer = 8
opcache.max_accelerated_files = 10000
opcache.revalidate_freq = 0    ; never recheck files in production
opcache.validate_timestamps = 0

3.5 Supervisord Configuration
Kubernetes expects each container to run a single foreground process. Since we need both Nginx and PHP-FPM running, we use Supervisord as a process manager to start and monitor both.

docker/supervisord.conf
[supervisord]
; Run in the foreground so Docker can track the process
nodaemon=true
logfile=/dev/null
logfile_maxbytes=0

[program:php-fpm]
command=/usr/local/sbin/php-fpm --nodaemonize
autostart=true
autorestart=true
stdout_logfile=/dev/stdout
stdout_logfile_maxbytes=0
stderr_logfile=/dev/stderr
stderr_logfile_maxbytes=0

[program:nginx]
command=/usr/sbin/nginx -g "daemon off;"
autostart=true
autorestart=true
stdout_logfile=/dev/stdout
stdout_logfile_maxbytes=0
stderr_logfile=/dev/stderr
stderr_logfile_maxbytes=0

#laravel13 #DEVOPS #Kubernetes #laravelDeployment #fullstackdevelopment

DEV Community: Akandwanaho Alvin