docker-patterns

Docker Patterns

Constraints

• Apply @rules/security/backend.md — never bake secrets into image layers, inject them at runtime; apply least privilege (non-root user, dropped capabilities, least-privileged DB user).
• Apply @rules/laravel/laravel.mdc — respect Laravel's directory layout, artisan commands, and config caching.
• Pin every base image to a specific tag (never :latest) for reproducible builds.
• One process per container: PHP-FPM, queue worker, and scheduler are separate containers sharing the same image.
• .env and secrets stay out of images and out of git.

Use when

• Writing or reviewing a Dockerfile / docker-compose.yml for a Laravel app.
• Setting up local dev (nginx + PHP-FPM + MySQL + Redis) or a build pipeline for a production image.
• Reviewing image size, layer caching, healthchecks, or secret handling.

Multi-Stage Dockerfile (PHP-FPM)

Separate Composer deps, the Vite/asset build, and the lean runtime so each layer caches independently and dev tooling never ships to production.

# syntax=docker/dockerfile:1

# --- Stage: composer deps (cached unless composer.* change) ---
FROM composer:2 AS vendor
WORKDIR /app
COPY composer.json composer.lock ./
RUN composer install --no-dev --no-scripts --prefer-dist \
    --optimize-autoloader --no-interaction

# --- Stage: node/vite asset build ---
FROM node:22-alpine AS assets
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY vite.config.js ./
COPY resources ./resources
RUN npm run build              # emits public/build via laravel-vite-plugin

# --- Stage: runtime (php-fpm, non-root, opcache) ---
FROM php:8.3-fpm-alpine AS runtime
RUN apk add --no-cache fcgi \
    && docker-php-ext-install pdo_mysql opcache bcmath pcntl \
    && addgroup -g 1000 -S app && adduser -S app -u 1000 -G app
COPY docker/php/opcache.ini /usr/local/etc/php/conf.d/opcache.ini
WORKDIR /var/www/html
COPY --chown=app:app . .
COPY --from=vendor --chown=app:app /app/vendor ./vendor
COPY --from=assets --chown=app:app /app/public/build ./public/build
USER app
HEALTHCHECK --interval=30s --timeout=3s --start-period=10s \
    CMD php-fpm-healthcheck || exit 1
EXPOSE 9000
CMD ["php-fpm"]