💻 **Instalación de Laravel:** Usando Sail y preparando el entorno PHP

💻 Instalación de Laravel: Usando Sail y Preparando el Entorno PHP

Introducción: Preparando el Entorno para Laravel con Sail y Docker

Antes de comenzar a desarrollar cualquier aplicación en Laravel, es fundamental tener la base correcta. En esta guía, te enseñaremos cómo preparar el entorno de desarrollo ideal para Laravel utilizando **Laravel Sail**, la solución oficial basada en **Docker**. Sail proporciona un entorno aislado y consistente, lo que facilita la gestión de servicios como PHP y MySQL sin la necesidad de herramientas adicionales como XAMPP.

A través de esta serie de pasos, aprenderás a instalar Docker Desktop, configurar Composer y, finalmente, poner en marcha tu proyecto Laravel. Este proceso es esencial para establecer una base sólida para tu desarrollo, asegurando que trabajes con las herramientas más modernas y eficientes.

🔧 Índice de Pasos:

Paso 1: Preparar Docker Desktop
Paso 2: Verificar y Configurar Composer
Paso 3: Instalar Ubuntu (WSL2) en Windows
Paso 4: Verificar y Configurar PHP en Ubuntu
Paso 5: Crear y Ubicar el Proyecto
Paso 6: Instalación de Laravel con Sail
Paso 7: Arrancar el Servidor de Desarrollo
Paso 8: Verificación del Proyecto en el Navegador
Paso 9: Resolución de Problemas Comunes
Paso 10: Mantenimiento y Actualización de tu Entorno

1. 🛠️ Preparar Docker Desktop

Docker Desktop es una herramienta esencial para ejecutar Laravel Sail de manera correcta. Antes de comenzar con la instalación de Laravel, debemos asegurarnos de que Docker esté instalado y en funcionamiento. Si ya tienes Docker Desktop instalado, podemos pasar al siguiente paso, pero si no es así, deberemos instalarlo.

Verificación de Docker: ¿Está instalado?

Lo primero que debes hacer es verificar si Docker ya está instalado en tu máquina. Para ello, abre tu terminal o PowerShell y ejecuta el siguiente comando:

docker --version

Si Docker está instalado, verás algo similar a lo siguiente:

Docker version 20.10.7, build f0df350

Si ves este resultado, ¡Docker está listo para usar! Puedes continuar con el siguiente paso.

¿No tienes Docker instalado? Instálalo siguiendo estos pasos:

Si recibes un error que dice algo como "docker: command not found" o "docker: no se reconoce como nombre de un cmdlet...", significa que Docker no está instalado o no está configurado correctamente en tu sistema. A continuación, te explicamos cómo instalar Docker Desktop.

Pasos para instalar Docker Desktop

Descargar Docker Desktop:
- Visita el sitio web oficial de Docker en docker.com.
- Descarga la versión compatible con tu sistema operativo (Windows o macOS).
Instalar Docker:
- Ejecuta el instalador descargado y sigue las instrucciones en pantalla.
- En Windows, es posible que necesites habilitar características de virtualización como WSL 2 o Hyper-V durante la instalación. El instalador te guiará a través de estas opciones.
Iniciar Docker Desktop:
- Una vez instalado, busca y abre Docker Desktop desde el menú de inicio o aplicaciones de tu sistema.
- Espera a que Docker se inicie completamente (el ícono de la ballena 🐳 debe volverse sólido).
Verificación Final:
- Cierra y vuelve a abrir tu terminal o PowerShell.
- Vuelve a ejecutar el comando docker --version. Si ves un número de versión, Docker se ha instalado correctamente y está listo para usar.

Errores comunes durante la instalación de Docker Desktop

A continuación, te mencionamos algunos de los errores más comunes que podrías encontrar durante la instalación de Docker Desktop y sus posibles soluciones:

Error 1: "Docker no se reconoce como un comando" o "docker: command not found"

Esto significa que Docker no está instalado correctamente o que no está en el PATH de tu sistema.

Solución:

Verifica que Docker se haya instalado correctamente siguiendo los pasos de instalación.
Si instalaste Docker en Windows, asegúrate de haber habilitado WSL 2 y de que Hyper-V esté activado.
Reinicia tu máquina después de la instalación para asegurarte de que todos los cambios se apliquen correctamente.

Error 2: "Docker Desktop no puede iniciarse" o "Docker no responde"

Esto puede ocurrir si hay problemas con los servicios de Docker o si no se han configurado correctamente.

Solución:

Asegúrate de que tu sistema cumpla con los requisitos mínimos para ejecutar Docker Desktop, como tener la virtualización activada en la BIOS.
Reinicia el servicio de Docker desde la interfaz de Docker Desktop o reinicia tu máquina.
Consulta el archivo de log de Docker para obtener más detalles sobre el error.

Error 3: "Falta la característica de virtualización" o "WSL no está habilitado"

Este error ocurre principalmente en sistemas Windows si no has habilitado características de virtualización como WSL 2 o Hyper-V.

Solución:

Activa la virtualización en la BIOS de tu máquina.
Habilita WSL 2 y Hyper-V siguiendo las instrucciones que Docker te proporciona durante la instalación o consulta la documentación oficial de Docker.

2. 📦 Verificar y Configurar Composer

**Composer** es una herramienta crucial para gestionar las dependencias de tu proyecto Laravel. Laravel Sail utiliza Composer internamente, pero es importante asegurarse de que esté correctamente instalado y configurado en tu sistema. En este paso, verificaremos si Composer está instalado, y si no lo está, procederemos a instalarlo. También abordaremos los errores comunes durante la instalación y cómo solucionarlos.

Verificación de Composer: ¿Está instalado?

El primer paso es verificar si Composer está instalado en tu sistema. Para ello, abre tu terminal o PowerShell y ejecuta el siguiente comando:

composer -V

Si Composer está instalado correctamente, verás algo similar a lo siguiente:

Composer version 2.7.6 2021-09-29 16:51:03

Si ves este resultado, ¡Composer está listo para usar! Puedes continuar con el siguiente paso. Si en lugar de esto ves un error, sigue las instrucciones a continuación para instalar Composer.

¿No tienes Composer instalado? Instálalo siguiendo estos pasos:

Si el comando anterior te da un error como "composer: command not found", significa que Composer no está instalado. A continuación, te mostramos cómo instalarlo.

Pasos para instalar Composer

Descargar Composer:
- Visita el sitio oficial de Composer en getcomposer.org.
- En la página principal, encontrarás el instalador para tu sistema operativo.
Instalar Composer en Windows (Usando el instalador):
- Descarga el archivo Composer-Setup.exe desde el sitio oficial de Composer.
- Ejecuta el archivo descargado y sigue las instrucciones del instalador.
- El instalador configurará automáticamente Composer en tu sistema y añadirá Composer al PATH para que pueda ejecutarse desde cualquier terminal.
Instalar Composer en Linux o macOS:
- Abre tu terminal y ejecuta los siguientes comandos:
- Esto descargará Composer y lo moverá a una ubicación accesible globalmente, de modo que puedas ejecutar el comando composer desde cualquier directorio.
Verificación Final:
- Cierra y vuelve a abrir tu terminal o PowerShell.
- Ejecuta nuevamente el comando composer -V para verificar que Composer esté correctamente instalado.

Errores comunes durante la instalación de Composer

Durante la instalación de Composer, es posible que encuentres algunos errores comunes. A continuación, te explicamos cómo solucionarlos.

Error 1: "composer: command not found" en Linux o macOS

Este error ocurre si Composer no se ha instalado correctamente o no se ha añadido al PATH de tu sistema.

Solución:

Asegúrate de haber ejecutado el comando sudo mv composer.phar /usr/local/bin/composer para mover Composer a una ubicación accesible globalmente.
Verifica que Composer esté en tu PATH ejecutando echo $PATH y asegurándote de que la ruta de Composer esté incluida.

Error 2: "Error al ejecutar curl" o problemas de conexión en Windows

Este error puede ocurrir si tu máquina tiene configuraciones de proxy o firewall que impiden la descarga de Composer.

Solución:

Verifica tu configuración de red y asegúrate de que no haya ningún proxy o firewall que bloquee la conexión.
Si estás detrás de un proxy, configura Composer para usarlo mediante el siguiente comando:
```
composer config -g http-proxy http://your.proxy:port
```

Error 3: "Permission denied" al intentar mover Composer a una carpeta global (Linux/macOS)

Este error ocurre cuando el sistema no tiene permisos suficientes para mover Composer a la ubicación global.

Solución:

Usa el comando sudo para ejecutar la operación con permisos elevados.
Si persisten los problemas de permisos, verifica los permisos de la carpeta con ls -l y ajusta los permisos según sea necesario.

3. 🐧 Instalar Ubuntu (WSL2) en Windows

Para trabajar con Docker y Laravel Sail en Windows, necesitamos instalar una distribución de Linux, y la mejor opción es **Ubuntu**. Utilizaremos **WSL2 (Windows Subsystem for Linux)** para correr Ubuntu de manera eficiente dentro de Windows. En este paso, vamos a verificar si ya tienes Ubuntu instalado, y si no es así, te explicaremos cómo instalarlo.

Verificación de Ubuntu: ¿Está instalado?

Lo primero que debes hacer es verificar si **Ubuntu** ya está instalado en tu máquina a través de **WSL2**. Para hacerlo, abre PowerShell y ejecuta el siguiente comando:

wsl --list --verbose

Este comando mostrará todas las distribuciones de Linux que tienes instaladas en **WSL2**. Si ves algo como esto:

  NAME      STATE           VERSION
* Ubuntu    Running         2

Esto indica que **Ubuntu** ya está instalado y en ejecución en tu máquina. Si en lugar de esto ves algo como "Ubuntu: No se encuentra" o no ves la distribución en la lista, significa que Ubuntu no está instalado y deberás proceder con la instalación.

Instalación de Ubuntu (Si no está instalado)

Si no tienes Ubuntu instalado, sigue estos pasos para instalarlo y configurarlo en **WSL2**.

Pasos para instalar Ubuntu en WSL2

Verificar que WSL está habilitado:
- Abre PowerShell como administrador y ejecuta el siguiente comando para habilitar WSL:
- Esto instalará WSL y configurará automáticamente WSL2 como la versión predeterminada.
Instalar Ubuntu:
- Abre la tienda de Microsoft en tu PC y busca **Ubuntu**.
- Selecciona la versión de Ubuntu que desees instalar (por ejemplo, Ubuntu 20.04 LTS) y haz clic en "Instalar".
- Alternativamente, puedes usar el siguiente comando en PowerShell para instalar Ubuntu desde la línea de comandos:
- Una vez que la instalación se haya completado, Ubuntu estará disponible en tu sistema.
Configurar Ubuntu:
- Cuando abras Ubuntu por primera vez, se te pedirá que crees un usuario y una contraseña de Linux. Esto solo es necesario la primera vez.
- Una vez configurado, puedes acceder a Ubuntu a través de PowerShell o terminal ejecutando wsl o directamente desde el menú de inicio de Windows.
Verificación Final:
- Para asegurarte de que todo esté funcionando correctamente, ejecuta el siguiente comando:
- Deberías ver Ubuntu en la lista de distribuciones, y el estado debería ser "Running" con la versión WSL2 activa.

Errores comunes durante la instalación de Ubuntu

Durante la instalación o configuración de Ubuntu en **WSL2**, es posible que te enfrentes a algunos errores. A continuación, te mostramos los problemas más comunes y sus soluciones.

Error 1: "WSL no está habilitado" o "No se encuentra la versión WSL2"

Este error ocurre si no has habilitado **WSL** en tu máquina o no has configurado **WSL2** como la versión predeterminada.

Solución:

Abre PowerShell como administrador y ejecuta el siguiente comando para habilitar **WSL** y configurarlo a la versión 2:

wsl --set-default-version 2

Luego reinicia tu PC para que los cambios se apliquen correctamente.

Error 2: "Problemas al instalar Ubuntu desde la tienda de Microsoft"

Si tienes problemas para descargar o instalar Ubuntu desde la tienda de Microsoft, podría ser un problema de conectividad o de configuración de la tienda.

Solución:

Verifica tu conexión a Internet y asegúrate de que la tienda de Microsoft esté funcionando correctamente.
Si el problema persiste, intenta reiniciar tu computadora y volver a intentarlo.

Error 3: "Ubuntu no arranca" o "Ubuntu está atascado en la pantalla de inicio"

Este error puede ocurrir si hay un problema con el sistema de archivos o la configuración de WSL.

Solución:

Abre PowerShell y ejecuta el siguiente comando para restablecer Ubuntu:

wsl --unregister Ubuntu

Luego vuelve a instalar Ubuntu desde la tienda de Microsoft o utilizando el comando de instalación desde PowerShell.

4. 🧩 Verificar y Configurar PHP en Ubuntu (WSL2)

Antes de poder instalar Laravel o usar Composer correctamente, debemos asegurarnos de que PHP esté instalado dentro de Ubuntu (WSL2), no en Windows. Este paso es muy importante porque Laravel Sail y Docker funcionan en un entorno Linux, y el PHP de Windows no se utiliza en este caso.

Paso previo: entrar a Ubuntu (WSL2)

Si actualmente estás en PowerShell (verás algo como PS C:\>), primero debes entrar en el entorno de Ubuntu. Para hacerlo, abre tu terminal de PowerShell y escribe:

wsl

Cuando pulses Enter, tu línea de comandos cambiará a algo como esto:

tuusuario@DESKTOP-XYZ:~$

✅ Esto significa que ahora estás dentro de Ubuntu (WSL2) y todos los comandos siguientes deben ejecutarse aquí.

Verificar ubicación y carpeta del proyecto

Por defecto, Ubuntu te ubica en tu carpeta personal (/home/tuusuario). Si tu proyecto se encuentra en Windows, por ejemplo en C:\proyectos\tiendaonline, puedes acceder a él desde Ubuntu usando la siguiente ruta:

cd /mnt/c/proyectos/tiendaonline

Para confirmar tu ubicación actual, ejecuta:

pwd

Si ves una ruta similar a /mnt/c/proyectos/tiendaonline, estás en el lugar correcto para trabajar con Laravel dentro de WSL2.

Verificación de PHP en Ubuntu

Ahora que estás en Ubuntu, verifica si PHP ya está instalado con el siguiente comando:

php -v

Si PHP está instalado, deberías ver una salida similar a:

PHP 8.2.12 (cli) (built: Oct 27 2024 09:45:23) ( NTS )
Copyright (c) The PHP Group
Zend Engine v4.2.12, with Zend OPcache v8.2.12

Si en cambio obtienes el mensaje php: command not found, significa que PHP no está instalado y deberás hacerlo manualmente.

Instalación de PHP y extensiones necesarias

Actualizar el sistema y los repositorios:
```
sudo apt update && sudo apt upgrade -y
```

Instalar PHP con extensiones básicas:

sudo apt install php php-cli php-common php-mbstring php-xml php-curl php-zip php-mysql unzip -y

Verificar instalación:
```
php -v
```

Comprobación de la ruta PHP

Si el comando php -v sigue sin funcionar, verifica que PHP esté correctamente instalado con:

which php

Debería devolver algo como /usr/bin/php. Si no muestra nada, reinstala PHP:

sudo apt reinstall php

✅ Con esto, confirmas que estás trabajando dentro de Ubuntu (WSL2) y que PHP está correctamente instalado en el entorno que Laravel Sail usará.

5️⃣ Crear y Ubicar el Proyecto Laravel

Ahora que ya tienes PHP y Composer funcionando correctamente dentro de Ubuntu (WSL2), es el momento de crear y ubicar tu proyecto Laravel. Este paso es esencial para asegurarte de que todo el entorno esté correctamente configurado antes de comenzar a desarrollar tu aplicación.

Abrir Ubuntu desde Windows

Primero debemos abrir el terminal de Ubuntu (WSL2) desde Windows. Existen varias formas de hacerlo:

🔹 Presiona Inicio y escribe Ubuntu, luego presiona Enter.
🔹 O bien, abre PowerShell y escribe:
```
wsl
```
Esto te abrirá directamente la consola de Ubuntu dentro de Windows.

Verificar en qué carpeta estás

Una vez dentro de Ubuntu, debemos asegurarnos de que estamos ubicados correctamente dentro del proyecto. Para ver la ubicación actual en el sistema, ejecuta:

pwd

Si el resultado es algo como:

/mnt/c/proyectos/tiendaonline

✅ ¡Perfecto! Estás dentro de la carpeta correcta. Si no estás en esa ubicación, muévete con el siguiente comando:

cd /mnt/c/proyectos/tiendaonline

Crear un nuevo proyecto Laravel dentro de la carpeta

Laravel debe instalarse dentro de la carpeta del proyecto (en este caso tiendaonline), ya que todos sus archivos y dependencias se crearán ahí. Si la carpeta está vacía, puedes instalar Laravel con:

composer create-project laravel/laravel .

🔸 El punto (.) al final indica que Laravel se instalará directamente en la carpeta actual. Si deseas crear un nuevo subproyecto con otro nombre, por ejemplo blog, puedes escribir:

composer create-project laravel/laravel blog

Verificar instalación de Laravel

Una vez finalizada la instalación, asegúrate de que Laravel se ha instalado correctamente ejecutando:

php artisan --version

Si Laravel está correctamente instalado, verás una salida similar a esta:

Laravel Framework 11.9.0

✅ Eso confirma que Laravel está correctamente configurado dentro de tu entorno de Ubuntu (WSL2).

Estructura esperada del proyecto

Si todo ha ido bien, deberías ver una estructura de carpetas como la siguiente dentro de tu proyecto:

app/
bootstrap/
config/
database/
public/
resources/
routes/
storage/
vendor/
artisan
composer.json
.env

Solución de problemas comunes

A continuación se muestran algunos errores comunes que puedes encontrar durante la creación o ubicación del proyecto, junto con sus soluciones:

Error 1: “Could not open input file: artisan”

Este error ocurre cuando ejecutas un comando de Laravel fuera del directorio del proyecto o Laravel no está instalado.

Solución:

cd /mnt/c/proyectos/tiendaonline
composer create-project laravel/laravel .

Error 2: “Permission denied”

Esto sucede si los archivos tienen permisos de Windows y no de Ubuntu.

Solución:

sudo chown -R $USER:$USER /mnt/c/proyectos/tiendaonline

Error 3: “composer: command not found”

Esto indica que Composer no está instalado dentro de Ubuntu.

Solución:

Revisa el Paso 2 del tutorial y asegúrate de instalarlo correctamente.

Probar el servidor de Laravel

Finalmente, para verificar que Laravel se ejecuta correctamente, inicia su servidor local con:

php artisan serve

Si todo está bien, verás un mensaje similar a:

Starting Laravel development server: http://127.0.0.1:8000

Ahora puedes abrir tu navegador y visitar: http://127.0.0.1:8000

🎯 Si ves la página de bienvenida de Laravel, significa que tu proyecto está correctamente instalado y funcionando dentro de Ubuntu (WSL2).

6️⃣ Instalación de Laravel con Sail

En este paso aprenderás a instalar y configurar Laravel Sail, el entorno de desarrollo oficial de Laravel basado en Docker. Sail te permite levantar fácilmente un entorno con PHP, MySQL, Redis, Mailpit y otros servicios, sin necesidad de instalarlos directamente en tu sistema.

¿Qué es Laravel Sail?

Laravel Sail es una interfaz de línea de comandos (CLI) que proporciona una forma sencilla de usar Docker para ejecutar aplicaciones Laravel. Es ideal para desarrolladores que usan WSL2 en Windows o Linux, ya que permite mantener un entorno idéntico al de producción sin conflictos locales.

Requisitos previos

Antes de continuar, asegúrate de tener lo siguiente configurado:

✅ Docker Desktop instalado y en ejecución en Windows.
✅ WSL2 configurado y funcionando correctamente.
✅ PHP y Composer instalados dentro de Ubuntu (ver pasos anteriores).

1️⃣ Instalar Laravel Sail

Si ya tienes tu proyecto Laravel creado (por ejemplo, /mnt/c/proyectos/tiendaonline), ingresa a esa carpeta desde Ubuntu:

cd /mnt/c/proyectos/tiendaonline
composer require laravel/sail --dev

Este comando instala Laravel Sail como dependencia de desarrollo en tu proyecto. Cuando termine, podrás inicializarlo con un conjunto de servicios predefinidos.

2️⃣ Inicializar Sail

Ahora vamos a inicializar Sail con los servicios que necesitemos. Por ejemplo, para incluir MySQL en tu entorno, ejecuta:

php artisan sail:install --with=mysql

Puedes reemplazar mysql por otros servicios si los necesitas, como:

--with=pgsql → PostgreSQL
--with=redis → Redis
--with=mailpit → Mailpit (para pruebas de correo)

Laravel creará un archivo docker-compose.yml con los servicios seleccionados.

3️⃣ Levantar los contenedores

Para iniciar tu entorno de desarrollo con Sail, ejecuta:

./vendor/bin/sail up

Esto descargará e iniciará los contenedores Docker necesarios (PHP, MySQL, etc.). Si deseas hacerlo en segundo plano (sin ocupar la terminal), añade el parámetro -d:

./vendor/bin/sail up -d

Cuando la instalación termine, Laravel estará accesible en: http://localhost

4️⃣ Ejecutar comandos con Sail

Una vez que Sail está activo, puedes ejecutar cualquier comando de Laravel usando Sail. Por ejemplo, en lugar de escribir php artisan, deberás anteponer sail:

./vendor/bin/sail artisan migrate
./vendor/bin/sail artisan serve
./vendor/bin/sail artisan tinker

O más sencillo, puedes definir un alias para no tener que escribir toda la ruta cada vez:

alias sail='bash vendor/bin/sail'

Luego podrás usar simplemente:

sail artisan migrate

5️⃣ Detener el entorno

Cuando termines de trabajar, puedes detener todos los contenedores con:

./vendor/bin/sail down

Esto apagará el entorno sin eliminar los datos de tus contenedores.

💡 Solución de problemas comunes

Error 1: “Docker Desktop no está corriendo”

Este error aparece si Docker no se ha iniciado antes de usar Sail.

Solución:

Abre Docker Desktop en Windows y espera a que muestre el estado “Running”. Luego ejecuta nuevamente:

./vendor/bin/sail up -d

Error 2: “permission denied: ./vendor/bin/sail”

Esto ocurre si el archivo sail no tiene permisos de ejecución.

Solución:

chmod +x vendor/bin/sail

Error 3: “Cannot connect to Docker daemon”

Este error indica que WSL2 no puede comunicarse con Docker.

Solución:

Asegúrate de que Docker esté habilitado para WSL2 en su configuración:
Abre Docker Desktop → Settings → Resources → WSL Integration y activa tu distribución Ubuntu.

✅ Confirmar que Sail funciona

Para comprobar que todo funciona correctamente, ejecuta:

./vendor/bin/sail ps

Si todo está correcto, verás una lista de contenedores activos como:

Name                  Command              State          Ports
--------------------------------------------------------------------------------
laravel.test          start-container       Up             0.0.0.0:80->80/tcp
laravel.mysql         docker-entrypoint...  Up             3306/tcp

🎯 ¡Listo! Ahora tienes Laravel funcionando con Sail y Docker dentro de Ubuntu (WSL2), un entorno profesional, limpio y totalmente reproducible.

7️⃣ Arrancar el Servidor de Desarrollo

Llegamos a uno de los pasos más gratificantes del proceso: ver Laravel en acción. Una vez que el framework esté instalado y todo esté configurado correctamente, podemos ejecutar el servidor de desarrollo que Laravel incluye por defecto. Este servidor te permitirá probar tu aplicación directamente desde el navegador.

📂 Verificar que estás dentro del proyecto

Antes de iniciar el servidor, asegúrate de que te encuentras dentro de la carpeta raíz del proyecto Laravel. En tu terminal de Ubuntu (WSL2), ejecuta:

pwd

El resultado debe ser algo como:

/mnt/c/proyectos/tiendaonline

Si no estás en esa ruta, muévete con:

cd /mnt/c/proyectos/tiendaonline

🚀 Iniciar el servidor de Laravel

Para iniciar el servidor integrado de Laravel, ejecuta el siguiente comando:

php artisan serve

Si todo está bien, Laravel iniciará su servidor local y te mostrará un mensaje similar a este:

Starting Laravel development server: http://127.0.0.1:8000
[Thu Nov  4 14:22:31 2025] PHP 8.2.12 Development Server (http://127.0.0.1:8000) started

✅ Esto significa que tu servidor está funcionando correctamente.

🌐 Acceder desde el navegador

Abre tu navegador en Windows (Edge, Chrome o Firefox) y entra a la siguiente dirección:

http://127.0.0.1:8000

Si todo está correctamente configurado, deberías ver la pantalla de bienvenida de Laravel con el mensaje:

Laravel 11 – You have arrived!

🛑 Detener el servidor

Mientras el servidor esté corriendo, la terminal permanecerá activa. Si quieres detenerlo, simplemente presiona:

CTRL + C

Esto cerrará el servidor y te devolverá al prompt normal del sistema.

⚠️ Errores comunes al iniciar el servidor

Error 1: “Could not open input file: artisan”

Esto ocurre cuando ejecutas el comando fuera del directorio del proyecto Laravel.

✅ Solución:

cd /mnt/c/proyectos/tiendaonline

Error 2: “Address already in use”

Este error aparece cuando el puerto 8000 ya está siendo usado por otro proceso.

✅ Solución:

php artisan serve --port=8080

Luego accede desde tu navegador a: http://127.0.0.1:8080

Error 3: “PHP not found” o “Command ‘php’ not recognized”

Este mensaje indica que el comando PHP no está disponible en tu entorno de Ubuntu o no fue correctamente instalado.

✅ Solución:

Verifica la instalación de PHP con:

php -v

Si no aparece la versión, revisa el Paso 4 de este tutorial para reinstalarlo.

🎉 Confirmación final

Si has llegado hasta aquí y puedes ver la página de Laravel en el navegador, ¡felicitaciones! Has completado con éxito el entorno de desarrollo básico de Laravel dentro de Ubuntu (WSL2).

8️⃣ Verificación del Proyecto en el Navegador

¡Excelente! Si has seguido todos los pasos anteriores, ya tienes tu entorno listo, el servidor en marcha y el proyecto Laravel funcionando. Ahora llega el momento de verificar que todo está correctamente configurado en el navegador.

Abrir Laravel en el navegador

Una vez que hayas ejecutado el comando:

php artisan serve

Verás un mensaje similar a este en la terminal:

INFO  Server running on [http://127.0.0.1:8000]
Press Ctrl+C to stop the server

Esto significa que el servidor de desarrollo de Laravel está en ejecución. Abre tu navegador (por ejemplo, Chrome o Firefox) y escribe la siguiente dirección en la barra:

http://127.0.0.1:8000

Si todo está correctamente configurado, deberías ver la pantalla de bienvenida de Laravel.

Posibles problemas al abrir la página

A veces, el servidor de Laravel se ejecuta, pero el navegador muestra un error. A continuación explicamos los más comunes y cómo resolverlos:

⚠️ Error 1: "php_network_getaddresses: getaddrinfo for mysql failed"

Esto ocurre cuando Laravel intenta conectarse a la base de datos MySQL pero no encuentra el servidor. En proyectos que usan Laravel Sail (con Docker), este error suele aparecer si los contenedores no están completamente levantados.

✅ Solución:

Detén el servidor con Ctrl + C.
Ejecuta en la terminal:
```
./vendor/bin/sail up -d
```
Una vez que todos los contenedores estén corriendo, vuelve a abrir el navegador.

⚠️ Error 2: “Base table or view not found”

Este error indica que Laravel sí logró conectarse a la base de datos, pero las tablas aún no han sido creadas. Es algo normal la primera vez que arrancas el proyecto.

✅ Solución:

En la terminal, asegúrate de estar en la carpeta del proyecto:
```
cd /mnt/c/proyectos/tiendaonline
```
Luego ejecuta el siguiente comando para crear todas las tablas iniciales:
```
php artisan migrate
```
Cuando el proceso termine correctamente, recarga la página en el navegador.

⚠️ Error 3: “Access denied for user 'root'@'localhost'”

Esto significa que los datos de conexión en el archivo .env no coinciden con los de tu contenedor MySQL.

✅ Solución:

Abre el archivo .env:
```
nano .env
```

Verifica que estas líneas sean correctas:

DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=sail
DB_PASSWORD=password

Guarda con Ctrl + O y sal con Ctrl + X.

Reinicia los contenedores con:

./vendor/bin/sail down && ./vendor/bin/sail up -d

Comprobación final

Una vez solucionados los posibles errores, actualiza tu navegador. Si todo está correcto, deberías ver la clásica pantalla con el logotipo de Laravel y la versión instalada.

🎉 ¡Felicidades! Has completado la configuración inicial y verificado que tu entorno Laravel funciona correctamente dentro de Ubuntu (WSL2) usando Docker y Sail.

A partir de este punto, ya puedes comenzar a desarrollar tu aplicación, crear rutas, controladores, vistas y migraciones sin problemas.

9️⃣ Resolución de Problemas Comunes

Aunque Laravel es un framework muy potente y flexible, su configuración inicial puede generar algunos inconvenientes, sobre todo al trabajar con Docker, Sail y WSL2. En este apartado veremos los errores más frecuentes y sus soluciones paso a paso.

🔹 Error 1: "php_network_getaddresses: getaddrinfo for mysql failed"

Este error aparece cuando Laravel intenta conectarse a la base de datos, pero el servicio de MySQL no está disponible o el nombre del host no es correcto.

✅ Solución:

Verifica que los contenedores estén ejecutándose:
```
./vendor/bin/sail ps
```
Si el servicio mysql no aparece como “healthy”, reinicia Sail:
```
./vendor/bin/sail down && ./vendor/bin/sail up -d
```

Comprueba que las variables del archivo .env estén configuradas correctamente:

DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=sail
DB_PASSWORD=password

🔹 Error 2: “Base table or view not found”

Esto ocurre cuando Laravel intenta acceder a una tabla que todavía no existe. Suele pasar al cargar la página principal si aún no ejecutaste las migraciones.

✅ Solución:

Asegúrate de estar dentro del proyecto:
```
cd /mnt/c/proyectos/tiendaonline
```
Ejecuta las migraciones:
```
php artisan migrate
```
Si no tienes tablas definidas, Laravel creará las básicas (users, migrations, password_resets, etc.).

🔹 Error 3: “Access denied for user 'root'@'localhost'”

Esto indica que las credenciales configuradas en el archivo .env no coinciden con las que usa el contenedor de MySQL.

✅ Solución:

Abre el archivo .env y revisa las líneas de conexión a base de datos:
```
nano .env
```

Corrige las variables para que queden así:

DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=sail
DB_PASSWORD=password

Guarda los cambios (Ctrl + O → Enter → Ctrl + X) y reinicia el entorno:
```
./vendor/bin/sail down && ./vendor/bin/sail up -d
```

🔹 Error 4: “Permission denied” o problemas de permisos en archivos

Puede aparecer si los archivos del proyecto se crearon con permisos de Windows y el sistema Ubuntu (WSL2) no puede escribir en ellos.

✅ Solución:

sudo chown -R $USER:$USER /mnt/c/proyectos/tiendaonline

🔹 Error 5: “composer: command not found”

Esto significa que Composer no está instalado dentro de Ubuntu (aunque lo esté en Windows).

✅ Solución:

Vuelve al Paso 2 del tutorial y asegúrate de instalar Composer dentro de Ubuntu con:

sudo apt install composer -y

🔹 Error 6: Laravel no carga en el navegador (pantalla en blanco o error 500)

Esto puede deberse a errores de caché o configuración previa.

✅ Solución:

Limpia la caché de configuración:
```
php artisan config:clear
```

Limpia las rutas y vistas:

php artisan route:clear
php artisan view:clear
php artisan cache:clear

Reinicia el servidor:
```
php artisan serve
```

🧭 Consejo Final

Si después de aplicar todas estas soluciones el problema persiste, puedes comprobar los errores directamente en el archivo de logs de Laravel:

cat storage/logs/laravel.log

Este archivo mostrará información detallada sobre los errores y te ayudará a identificar el origen exacto del problema.

✅ Con estos pasos podrás resolver el 95% de los errores comunes en la instalación y configuración de Laravel en tu entorno Docker/WSL2.

🔟 Mantenimiento y Actualización de tu Entorno

Una vez que tu entorno de desarrollo con Laravel, Sail, Docker y WSL2 esté funcionando correctamente, es importante mantenerlo actualizado para evitar errores, vulnerabilidades y problemas de compatibilidad. A continuación, te mostramos cómo hacerlo paso a paso de manera segura.

🔹 Actualizar los paquetes de Ubuntu (WSL2)

Comienza por actualizar el sistema Ubuntu dentro de WSL2 para tener las últimas versiones de sus librerías. Abre el terminal de Ubuntu y ejecuta:

sudo apt update && sudo apt upgrade -y
sudo apt autoremove -y

💡 Esto mantendrá tu sistema Linux limpio y actualizado, eliminando dependencias que ya no sean necesarias.

🔹 Actualizar Composer

Composer es una herramienta clave en Laravel. Para asegurarte de que estás usando la última versión, ejecuta:

composer self-update

Si Composer fue instalado globalmente con apt, también puedes actualizarlo así:

sudo apt install composer -y

🔹 Actualizar las dependencias del proyecto Laravel

Mantener tus paquetes actualizados es esencial para la seguridad y el rendimiento del proyecto. Desde la carpeta raíz del proyecto, ejecuta:

composer update

Esto descargará las versiones más recientes de todas las dependencias definidas en el archivo composer.json.

🔹 Actualizar Laravel Sail y los contenedores Docker

Dado que Sail funciona con imágenes Docker, conviene actualizarlas periódicamente. Para ello, ejecuta los siguientes comandos:

./vendor/bin/sail down
./vendor/bin/sail pull
./vendor/bin/sail up -d

🚀 Con esto descargarás las versiones más recientes de los contenedores (PHP, MySQL, Redis, etc.) y reiniciarás el entorno actualizado.

🔹 Verificar la versión actual de Laravel

Para confirmar qué versión de Laravel estás utilizando, ejecuta:

php artisan --version

🔹 Limpiar cachés y optimizar el proyecto

Con el tiempo, Laravel acumula archivos temporales y cachés. Puedes limpiarlos fácilmente con los siguientes comandos:

php artisan cache:clear
php artisan config:clear
php artisan route:clear
php artisan view:clear
php artisan optimize

🔹 Revisar el estado de los servicios Docker

Para verificar que todo funciona correctamente después de una actualización, usa:

./vendor/bin/sail ps

Si algún contenedor muestra errores, puedes reiniciarlo individualmente:

./vendor/bin/sail restart nombre_del_servicio

🧭 Buenas prácticas de mantenimiento

🔸 Actualiza tu entorno al menos una vez al mes.
🔸 Revisa el archivo .env antes de cualquier despliegue.
🔸 Realiza copias de seguridad de tu base de datos con regularidad.
🔸 Usa control de versiones (Git) para guardar cambios de forma segura.
🔸 Evita modificar directamente archivos dentro de vendor/.

✅ Siguiendo estas prácticas, tu entorno Laravel se mantendrá estable, actualizado y listo para el desarrollo diario sin interrupciones.

🏠 Volver al Índice Siguiente: Tema seguinte 🎉