Instalación de Docker y configuración del entorno para Laravel

Introducción

En este tutorial aprenderás a instalar Docker en tu sistema y a configurar un entorno completo para ejecutar aplicaciones Laravel con Docker Compose. Usaremos contenedores para PHP-FPM, Nginx (servidor web) y MySQL (base de datos), siguiendo las mejores prácticas documentadas por Docker .

---

Requisitos previos

Sistemas operativos compatibles

Sistema	Requisitos
Windows	Windows 10/11 64-bit (Pro/Enterprise/Education) con WSL2 habilitado
macOS	Intel o Apple Silicon
Linux	Ubuntu 20.04+, Debian 11+, Fedora, Arch

---

Parte 1: Instalación de Docker

En Windows (recomendado: Docker Desktop)

1. Habilitar WSL2 (abre PowerShell como administrador):

powershell

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Reinicia tu PC .

2. Descargar e instalar Docker Desktop desde docker.com. Durante la instalación, marca la opción "Use WSL 2 instead of Hyper-V" .

3. Verificar instalación:

bash

docker --version
docker compose version

En Linux (Ubuntu/Debian)

1. Agregar el repositorio oficial de Docker :

bash

sudo apt update
sudo apt install -y ca-certificates curl

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

2. Agregar el repositorio:

bash

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

3. Instalar Docker:

bash

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

4. Permitir ejecutar Docker sin sudo :

bash

sudo usermod -aG docker $USER
# Cierra sesión y vuelve a iniciarla para que el cambio surta efecto

---

Parte 2: Estructura del proyecto

Crea la siguiente estructura de carpetas para tu proyecto Laravel:

text

mi-proyecto-laravel/
├── Dockerfile
├── docker-compose.yml
├── nginx/
│   └── default.conf
├── php/
│   └── php.ini
└── src/               # ← Aquí irá tu código Laravel

Nota: Puedes usar una estructura alternativa donde src contiene el código y los archivos de configuración están en carpetas como docker/ . Elige la que prefieras.

---

Parte 3: Crear el Dockerfile

Crea un archivo Dockerfile en la raíz del proyecto con el siguiente contenido :

dockerfile

FROM php:8.2-fpm

# Instalar dependencias del sistema
RUN apt-get update -y && apt-get install -y \
    openssl \
    zip \
    unzip \
    git \
    curl \
    libpng-dev \
    libonig-dev \
    libxml2-dev \
    libzip-dev \
    && docker-php-ext-install pdo_mysql mbstring exif pcntl bcmath gd zip \
    && apt-get clean && rm -rf /var/lib/apt/lists/*

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

# Establecer directorio de trabajo
WORKDIR /var/www

# Copiar el código de la aplicación
COPY src/ /var/www

# Instalar dependencias de Laravel
RUN composer install --no-dev --optimize-autoloader --no-interaction

# Establecer permisos
RUN chown -R www-data:www-data /var/www \
    && chmod -R 755 /var/www/storage /var/www/bootstrap/cache

EXPOSE 9000
CMD ["php-fpm"]

Explicación del Dockerfile

Parte	Descripción
FROM php:8.2-fpm	Imagen base de PHP con FPM (procesa peticiones PHP)
apt-get install	Instala dependencias necesarias para Laravel y extensiones PHP
docker-php-ext-install	Instala extensiones PHP nativas (PDO MySQL, mbstring, etc.)
COPY --from=composer	Copia Composer desde su imagen oficial
WORKDIR /var/www	Directorio de trabajo dentro del contenedor
composer install	Instala las dependencias de Laravel

---

Parte 4: Configurar Nginx

Crea nginx/default.conf para el servidor web :

nginx

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

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

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_pass app:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        fastcgi_param PATH_INFO $fastcgi_path_info;
    }
}

---

Parte 5: Crear docker-compose.yml

El archivo docker-compose.yml orquesta todos los servicios :

yaml

version: '3.8'

services:
  # Servicio de PHP-FPM
  app:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: laravel_app
    restart: unless-stopped
    volumes:
      - ./src:/var/www
    networks:
      - laravel

  # Servidor web Nginx
  nginx:
    image: nginx:alpine
    container_name: laravel_nginx
    restart: unless-stopped
    ports:
      - "8000:80"
    volumes:
      - ./src:/var/www
      - ./nginx/default.conf:/etc/nginx/conf.d/default.conf
    depends_on:
      - app
    networks:
      - laravel

  # Base de datos MySQL
  db:
    image: mysql:8.0
    container_name: laravel_db
    restart: unless-stopped
    environment:
      MYSQL_DATABASE: laravel
      MYSQL_USER: laravel
      MYSQL_PASSWORD: secret
      MYSQL_ROOT_PASSWORD: rootsecret
    ports:
      - "3306:3306"
    volumes:
      - db_data:/var/lib/mysql
    networks:
      - laravel

# Red para comunicación entre contenedores
networks:
  laravel:
    driver: bridge

# Volumen persistente para la base de datos
volumes:
  db_data:

Servicios definidos

Servicio	Imagen	Puerto	Función
app	PHP 8.2-FPM	9000	Ejecuta el código PHP de Laravel
nginx	Nginx Alpine	8000:80	Servidor web que entrega la aplicación
db	MySQL 8.0	3306	Base de datos persistente

---

Parte 6: Instalar Laravel

6.1 Crear el proyecto Laravel

Desde la raíz del proyecto, ejecuta :

bash

docker compose run --rm app composer create-project laravel/laravel .

Explicación: El contenedor app ejecutará Composer para crear un nuevo proyecto Laravel dentro de la carpeta src/.

6.2 Verificar la instalación

bash

# Ver archivos creados en src/
ls -la src/

# Deberías ver: app/, bootstrap/, config/, public/, etc.

6.3 Configurar archivo .env

bash

cp src/.env.example src/.env

Ajusta las variables de base de datos en src/.env :

env

DB_CONNECTION=mysql
DB_HOST=db                # ← Usa "db" porque es el nombre del servicio
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=laravel
DB_PASSWORD=secret

---

Parte 7: Levantar el entorno

7.1 Construir y ejecutar los contenedores

bash

docker compose build   # Construye la imagen de la app
docker compose up -d   # Levanta todos los servicios en segundo plano

7.2 Verificar que todo está corriendo

bash

docker compose ps

Salida esperada:

text

NAME               IMAGE               COMMAND                  SERVICE   STATUS         PORTS
laravel_app        mi-proyecto-app     "docker-php-entrypoi…"   app       Up 2 minutes   9000/tcp
laravel_nginx      nginx:alpine        "/docker-entrypoint.…"   nginx     Up 2 minutes   0.0.0.0:8000->80/tcp
laravel_db         mysql:8.0           "docker-entrypoint.s…"   db        Up 2 minutes   0.0.0.0:3306->3306/tcp

7.3 Acceder a la aplicación

Abre tu navegador y visita:

text

http://localhost:8000

Deberías ver la página de bienvenida de Laravel 🎉

---

Parte 8: Comandos útiles

Ejecutar comandos de Laravel

bash

# Generar clave de aplicación
docker compose exec app php artisan key:generate

# Ejecutar migraciones
docker compose exec app php artisan migrate

# Ver rutas
docker compose exec app php artisan route:list

# Abrir shell interactiva
docker compose exec app bash

Comandos de administración

bash

# Ver logs de todos los servicios
docker compose logs -f

# Ver logs de un servicio específico
docker compose logs nginx

# Detener servicios
docker compose down

# Detener y eliminar volumen de DB (¡pierde los datos!)
docker compose down -v

# Reconstruir sin usar caché
docker compose build --no-cache

---

Solución de problemas comunes

⚠️ "Permission denied" al ejecutar Docker

Causa: El usuario no está en el grupo docker .

Solución:

bash

sudo usermod -aG docker $USER
# Cierra sesión y vuelve a iniciarla

⚠️ "Connection refused" al conectar a DB

Causa: DB_HOST incorrecto o DB no lista.

Solución: Asegúrate de que DB_HOST=db en .env (usa el nombre del servicio, no localhost) . Espera unos segundos a que MySQL esté listo.

⚠️ Composer no encuentra extensiones

Causa: BuildKit deshabilitado en Docker .

Solución:

bash

export DOCKER_BUILDKIT=1
export COMPOSE_DOCKER_CLI_BUILD=1
docker compose build

jj

Recursos adicionales

• Laravel Sail: Herramienta oficial de Laravel para Docker 

• Laradock: Proyecto comunitario para entornos Docker 

• Documentación oficial de Docker para Laravel: Docker Docs