9-Configuración del Entorno para Laravel con Docker

 

Configuración del Entorno para Laravel con Docker

Este archivo construye la imagen del contenedor PHP-FPM que usará tu servicio app en docker-compose.yml. Paso a paso:

• FROM php:8.3-fpm
  Toma como base la imagen oficial de PHP 8.3 con FPM (servidor de aplicaciones PHP).

• ARG user y ARG uid
  Define dos variables que se pasarán al construir (para crear un usuario con el mismo UID que el host y evitar problemas de permisos).

• Instalación de dependencias del sistema (apt-get)
  Instala paquetes necesarios para extensiones PHP (git, curl, librerías de imagen, compresión, etc.).

• Instalación de extensiones PHP (docker-php-ext-install)
  Habilita las extensiones que Laravel 12 requiere: pdo_mysql, mbstring, bcmath, gd, zip, pcntl (para colas) y otras.

• COPY --from=composer:latest ...
  Copia el binario de Composer desde la imagen oficial de Composer, para que puedas instalar dependencias PHP dentro del contenedor.

• Creación de usuario (useradd, mkdir, chown)
  Crea el usuario no root (con el nombre y UID que pasaste al construir) y le da permisos sobre su home y el directorio .composer.

• WORKDIR /var/www
  Establece el directorio de trabajo dentro del contenedor (donde estará el código de Laravel).

• USER $user
  Cambia al usuario creado para que todos los procesos posteriores (PHP, Composer) no se ejecuten como root (más seguro).

---

En resumen

Este Dockerfile prepara un entorno completo para ejecutar Laravel 12 con PHP 8.3, incluyendo todas las extensiones, Composer, y un usuario personalizado. Al hacer docker compose up, este archivo se usa para construir la imagen que levantará el contenedor app de tu proyecto

Introducción

En este tutorial configuraremos el entorno de desarrollo para un proyecto Laravel usando Docker. Crearemos la estructura de directorios, el Dockerfile para PHP y prepararemos todo para la integración con Docker Compose.

---

Paso 1: Crear la Estructura de Directorios

1.1 Verificar la ubicación actual

bash

pwd

1.2 Crear el directorio del proyecto

bash

mkdir laravel
cd laravel

---

Paso 2: Crear el Dockerfile para PHP

2.1 Crear y editar el archivo

bash

nano Dockerfile

2.2 Contenido del Dockerfile

El siguiente es un Dockerfile modernizado con las mejores prácticas actuales :

dockerfile

# --- Etapa de construcción para dependencias ---
FROM composer:2 AS vendor
WORKDIR /app
COPY composer.json composer.lock ./
RUN composer install --no-dev --no-scripts --optimize-autoloader

# --- Etapa de ejecución ---
FROM php:8.2-fpm

# Argumentos para el usuario
ARG USERNAME=laravel
ARG USERID=1000

# Instalar dependencias del sistema
RUN apt-get update && apt-get install -y \
    curl \
    git \
    libpng-dev \
    libonig-dev \
    libxml2-dev \
    zip \
    unzip \
    libzip-dev \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

# Instalar extensiones de PHP
RUN docker-php-ext-install -j$(nproc) \
    pdo_mysql \
    mbstring \
    exif \
    pcntl \
    bcmath \
    gd \
    zip

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

# Crear usuario no-root (buena práctica de seguridad)
RUN groupadd -g ${USERID} ${USERNAME} \
    && useradd -u ${USERID} -g ${USERNAME} -m ${USERNAME}

# Establecer directorio de trabajo
WORKDIR /var/www/html

# Cambiar al usuario no-root
USER ${USERNAME}

---

 Versión con PHP 8.3 (Recomendado para Laravel 12)

dockerfile

FROM php:8.3-fpm

ARG user
ARG uid

# Instalación de dependencias del sistema
RUN apt-get update && apt-get install -y \
    git \
    curl \
    libpng-dev \
    libonig-dev \
    libxml2-dev \
    zip \
    unzip \
    libzip-dev \
    libpq-dev \
    libcurl4-openssl-dev \
    libssl-dev \
    && apt-get clean && rm -rf /var/lib/apt/lists/*

# Instalación de extensiones PHP necesarias para Laravel 12
RUN docker-php-ext-install \
    pdo_mysql \
    mysqli \
    mbstring \
    exif \
    pcntl \
    bcmath \
    gd \
    zip \
    && docker-php-ext-enable pdo_mysql

# Instalación de Composer
COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

# Creación de usuario
RUN useradd -G www-data,root -u $uid -d /home/$user $user
RUN mkdir -p /home/$user/.composer && \
    chown -R $user:$user /home/$user

# Establecer directorio de trabajo
WORKDIR /var/www

USER $user

Paso 3: Explicación del Dockerfile

3.1 Versión de PHP

El tutorial original usa PHP 7.4 para Laravel 8. Sin embargo, es importante actualizar :

Laravel Version	PHP Requerido	Estado
Laravel 8.x	PHP 7.3 - 8.0	Obsoleto
Laravel 9.x	PHP 8.0+	Obsoleto
Laravel 10.x	PHP 8.1+	Soporte hasta 2025
Laravel 11.x	PHP 8.2+	Soporte activo

Recomendación: Usa PHP 8.2 o superior para proyectos nuevos .

3.2 Comandos de instalación de extensiones

Los scripts docker-php-ext-install y docker-php-ext-configure son comandos nativos de las imágenes oficiales de PHP :

• docker-php-ext-install: Compila e instala extensiones desde el código fuente

• docker-php-ext-configure: Configura una extensión antes de compilarla

• docker-php-ext-enable: Habilita extensiones ya instaladas

3.3 Buenas prácticas implementadas

• Usuario no-root: Ejecutar como usuario sin privilegios mejora la seguridad 

• Multietapa: Separación de dependencias de compilación

• Limpieza de caché: Eliminar paquetes temporales reduce el tamaño de la imagen

---

Paso 4: Actualizaciones Relevantes (2024-2026)

✅ Docker Compose V2

El comando docker-compose (con guión) está obsoleto. La versión actual es docker compose (con espacio) :

bash

# Antes (obsoleto)
docker-compose up

# Ahora (recomendado)
docker compose up

✅ Alpine vs Debian

La imagen oficial php:fpm tiene dos variantes principales :

Variante	Tamaño	Ventajas	Desventajas
php:8.2-fpm (Debian)	Mayor	Compatibilidad glibc	Mayor tamaño
php:8.2-fpm-alpine	Menor	Menor superficie de ataque	Posibles problemas DNS con musl

Elección: Para entornos de producción, usa Debian si tu aplicación usa resolución de nombres dinámica .

✅ Composer 2

El tutorial original instala una versión específica de Composer. Actualmente usa Composer 2.x:

dockerfile

COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

---

Paso 5: Archivo de Configuración para Desarrollo

Crear un archivo php.dev.ini para desarrollo:

bash

nano php.dev.ini

Contenido:

ini

display_errors = On
display_startup_errors = On
error_reporting = E_ALL
memory_limit = 256M
upload_max_filesize = 64M
post_max_size = 128M
date.timezone = UTC

---

Paso 6: Archivo de Configuración para Producción

Crear php.prod.ini:

ini

display_errors = Off
display_startup_errors = Off
error_reporting = E_ALL & ~E_DEPRECATED & ~E_STRICT
memory_limit = 256M
opcache.enable = 1
opcache.validate_timestamps = 0

Nota: opcache.validate_timestamps=0 mejora rendimiento y evita ejecución de archivos maliciosos inyectados .

---

Resumen de Cambios Recomendados

Aspecto	Original	Actualización
PHP	7.4	8.2+
Docker Compose	docker-compose	docker compose
Usuario	Root	Usuario dedicado
Composer	Instalación manual	Imagen oficial
Opcache	No configurado	Configurado en producción

---

¡Listo! Ahora tienes un Dockerfile moderno para tu proyecto Laravel. En el siguiente paso crearemos el archivo docker-compose.yml para orquestar todos los servicios.

 Dockerfile (la "receta")

• Sirve para construir una única imagen.

• Define qué lleva dentro un solo contenedor: sistema operativo, extensiones de PHP, Composer, usuario, etc.

• Es como los planos de una casa. Solo construyes un entorno (en tu caso, el contenedor PHP-FPM).

---

⚙️ docker-compose.yml (el "plano de obra completa")

• Sirve para orquestar y levantar múltiples contenedores a la vez.

• Define cómo se relacionan varios servicios: el contenedor PHP (hecho con tu Dockerfile), el servidor web (Nginx), la base de datos (MySQL) y Redis.

• Configura redes, volúmenes (para compartir archivos), puertos y orden de arranque.

---

▶️ Diferencia práctica:

• Dockerfile → haces docker build y obtienes 1 contenedor (PHP).

• docker-compose.yml → haces docker compose up y obtienes todo el ecosistema (PHP + Nginx + MySQL + Redis) funcionando al mismo tiempo, listo para ejecutar Laravel.

En resumen: el Dockerfile construye la pieza, y el docker-compose las une y las pone a funcionar en equipo.

Dockerfile