11-Verificación y Prueba del Entorno Docker para Laravel

 

Verificación y Prueba del Entorno Docker para Laravel

 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.

Introducción

En este tutorial verificaremos que nuestra configuración de Docker funciona correctamente, crearemos un proyecto Laravel dentro del contenedor y prepararemos el entorno para los siguientes pasos.

---

Paso 1: Construir y Levantar los Contenedores

1.1 Comando actualizado (Docker Compose V2)

bash

# Comando moderno (recomendado)
docker compose up -d

# Si usas versión antigua (obsoleta)
# docker-compose up -d

Explicación de la bandera -d:

• -d o --detach: Ejecuta los contenedores en segundo plano (modo "detached")

• Sin -d, verías todos los logs en tiempo real

1.2 Esperar la descarga de imágenes

El proceso descargará:

• Imagen base de PHP 7.4/8.2 FPM

• Dependencias del sistema

• Extensiones de PHP

• Composer

• Capas de la imagen personalizada

---

Paso 2: Solución de Problemas Comunes

⚠️ Problema: Descarga Detenida/Atascada

Si la descarga se detiene sin avanzar:

bash

# 1. Detener con Ctrl+C
# 2. Reintentar el comando
docker compose up -d

Causas posibles:

• Problemas de red/local

• Timeout en la descarga de capas

• Cache de Docker corrupta

Solución alternativa:

bash

# Limpiar cache y reintentar
docker system prune -f
docker compose build --no-cache
docker compose up -d

🔧 Solución para descargas lentas

Configurar mirrors para acelerar descargas:

bash

# Configurar mirror de Docker en China (si aplica)
sudo nano /etc/docker/daemon.json

json

{
  "registry-mirrors": ["https://mirror.ccs.tencentyun.com"]
}

bash

sudo systemctl restart docker

---

Paso 3: Verificar Contenedores Activos

3.1 Listar contenedores en ejecución

bash

docker ps

Salida esperada:

text

CONTAINER ID   IMAGE          COMMAND                  CREATED         STATUS         PORTS     NAMES
abc123def456   laravel-app    "docker-php-entrypoi…"   2 minutes ago   Up 2 minutes             laravel_app_1

3.2 Ver logs del contenedor

bash

docker compose logs app

---

Paso 4: Acceder al Contenedor

4.1 Entrar al contenedor con shell interactivo

bash

# Usando el nombre del servicio
docker compose exec app bash

# O usando el ID del contenedor (alternativa)
# docker exec -it <container_id> bash

4.2 Verificar archivos dentro del contenedor

bash

# Dentro del contenedor
ls -la

Archivos visibles:

• Dockerfile

• docker-compose.yml

• .env (si existe)

• Archivos del proyecto (sincronizados por volumen)

---

Paso 5: Crear Proyecto Laravel

5.1 Usar Composer para crear el proyecto

bash

# Dentro del contenedor
composer create-project laravel/laravel application --prefer-dist

Explicación de banderas:

• create-project: Crea nuevo proyecto

• laravel/laravel: Framework Laravel

• application: Nombre de la carpeta destino

• --prefer-dist: Descarga versión empaquetada (más rápida)

5.2 Comando actualizado para Laravel 11+

Para Laravel 11 (más reciente), el comando es similar:

bash

composer create-project laravel/laravel application

Nota: Laravel 11 usa PHP 8.2+ como requisito mínimo.

---

Paso 6: Verificar la Instalación de Laravel

6.1 Ver archivo .env generado

bash

# Dentro del contenedor
cat application/.env

6.2 Versiones de Laravel según año

Año	Versión Laravel	PHP Requerido
2024	Laravel 11	PHP 8.2+
2025	Laravel 12	PHP 8.3+ (estimado)
2026	Laravel 13	PHP 8.4+ (estimado)

---

Paso 7: Sincronizar Archivos con el Host

7.1 Salir del contenedor

bash

exit

7.2 Copiar archivos al directorio raíz

bash

# Copiar todo desde application/ al directorio actual
cp -r application/* .
cp -r application/.[!.]* . 2>/dev/null || true

7.3 Eliminar la carpeta application

bash

rm -rf application

7.4 Verificar estructura final

bash

ls -la

Estructura esperada:

text

laravel/
├── Dockerfile
├── docker-compose.yml
├── .env
├── .gitignore
├── app/
├── bootstrap/
├── config/
├── database/
├── public/
├── resources/
├── routes/
├── storage/
├── tests/
├── vendor/
├── composer.json
└── composer.lock

---

Paso 8: Comandos Útiles Actualizados

8.1 Gestión de contenedores (Docker Compose V2)

bash

# Levantar contenedores
docker compose up -d

# Ver logs en tiempo real
docker compose logs -f

# Detener contenedores
docker compose down

# Detener y eliminar volúmenes
docker compose down -v

# Reconstruir sin cache
docker compose build --no-cache

# Ver estado de servicios
docker compose ps

8.2 Ejecutar comandos en el contenedor

bash

# Instalar dependencias
docker compose exec app composer install

# Generar key de Laravel
docker compose exec app php artisan key:generate

# Ejecutar migraciones
docker compose exec app php artisan migrate

# Ejecutar tests
docker compose exec app php artisan test

---

Paso 9: Buenas Prácticas y Optimizaciones

✅ Usar variables de entorno para configuración

Crear archivo .env en la raíz:

env

# Docker
COMPOSE_PROJECT_NAME=laravel
UID=1000
USER=laravel

# Laravel
APP_NAME=Laravel
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost

✅ Configurar docker-compose.override.yml

Para personalizaciones específicas de entorno:

yaml

services:
  app:
    environment:
      - XDEBUG_MODE=debug
      - XDEBUG_CONFIG=client_host=host.docker.internal
    extra_hosts:
      - "host.docker.internal:host-gateway"

✅ Usar perfiles para desarrollo vs producción

yaml

services:
  node:
    image: node:18
    profiles: ["dev"]
    volumes:
      - ./:/var/www/html
    working_dir: /var/www/html

bash

# Levantar con perfil dev
docker compose --profile dev up -d

---

Solución de Problemas Comunes

Problema	Síntoma	Solución
Permisos	Permission denied	sudo chown -R $USER:$USER .
Puerto ocupado	port already allocated	Cambiar puerto en docker-compose.yml
Sin acceso a Composer	composer: command not found	Verificar instalación en Dockerfile
Variables de entorno	Key not generated	Ejecutar php artisan key:generate
Error de red entre contenedores	Connection refused	Verificar networks: en YAML