5.3 Instalación y puesta en marcha de Laravel

5.3.1 Introducción

En este apartado vamos a instalar Laravel dentro del entorno de desarrollo que hemos preparado previamente. Utilizaremos Composer para crear un nuevo proyecto Laravel y realizaremos las configuraciones necesarias en el servidor Nginx para que nuestra aplicación funcione correctamente.

El objetivo es tener un proyecto de Laravel completamente operativo y accesible desde el navegador.

Preparación del proyecto base antes de instalar Laravel

Antes de proceder a instalar Laravel, asegúrate de tener el proyecto base correctamente descargado y configurado en tu ordenador. Sino lo tienes, puedes clonar el repositorio inicial que hemos preparado.

Clonar el repositorio inicial

Si todavía no has clonado el proyecto, abre una terminal y ejecuta:

git clone https://github.com/jbeteta-ies/laravelinit.git

Accede a la carpeta del proyecto:

cd laravelinit

Cambiar a la rama correcta

Una vez clonado el repositorio, es necesario cambiar a la rama 5.3-inicio, que es el punto de partida para esta sección del curso.

Ejecuta:

git checkout 5.3-inicio

Esto situará tu proyecto en el estado inicial adecuado para comenzar la instalación de Laravel.

Recordatorio importante

Importante

Si has seguido el tema 5.2, ya deberías tener el entorno Docker configurado. Y la estructura de carpetas y ficheros básicos creados. Sino puedes utilizar puees utilizar git para clonar el repositorio del tema 5.2, tal y como se explica en el apartado 5.2.1.

5.3.2 Preparar la carpeta de trabajo

Antes de instalar Laravel, es importante preparar correctamente la carpeta donde se va a ubicar el proyecto.

  • Dirígete a la carpeta src/ del proyecto clonado.
cd src
  • Si existe un archivo index.php de prueba (utilizado previamente para verificar PHP), elimínalo:
rm index.php

Esto nos asegura que la carpeta src/ esté vacía y lista para recibir el proyecto Laravel.

Importante

Laravel necesita que la carpeta de instalación esté vacía para crear correctamente su estructura de archivos.

5.3.3 Crear el proyecto Laravel

Acceder al contenedor PHP

Para instalar Laravel correctamente, es necesario ejecutar Composer desde dentro del contenedor de PHP.

  1. Abre una terminal en Visual Studio Code. (O utilza Docker Desktop si lo prefieres).
  2. Ejecuta el siguiente comando para acceder al contenedor dk_php:
docker exec -it dk_php bash

Esto abrirá una consola dentro del contenedor.

Comprobar que Composer está instalado

Antes de continuar, vamos a asegurarnos de que Composer está correctamente instalado dentro del contenedor.

Escribe:

composer --version

Deberías ver algo parecido a:

Composer version 2.x.x 2025-XX-XX

Problema común

Si no ves la versión de Composer, o recibes un error, revisa que tu contenedor PHP haya sido construido correctamente a partir del Dockerfile que instala Composer.

Ir a la carpeta de trabajo src/

Una vez dentro del contenedor, asegúrate de estar en la carpeta correcta (/var/www/html): Puedes utilizar el comando pwd para saber en qué carpeta te encuentras.:

pwd
Si no estás en la carpeta correcta: 

cd /var/www/html

Esta carpeta es donde se montó tu proyecto (src/) desde tu máquina local.

Instalar Laravel

Ahora sí, desde dentro de /var/www/html, ejecuta el siguiente comando para instalar Laravel:

composer create-project laravel/laravel .

Importante

El punto (.) al final del comando indica que Laravel debe instalarse en la carpeta actual (/var/www/html).

Composer descargará todo el framework, instalará las dependencias necesarias, y configurará el proyecto inicial. Puede tardar un poco, ten paciencia.

Mini resumen operativo

Acción Comando
Entrar al contenedor PHP docker exec -it docker_php bash
Comprobar Composer composer --version
Ir a la carpeta de trabajo cd /var/www/html
Instalar Laravel composer create-project laravel/laravel .

Al finalizar el proceso, la carpeta src/ tendrá la siguiente estructura principal:

src/
├── app/
├── bootstrap/
├── config/
├── database/
├── public/
├── resources/
├── routes/
├── storage/
├── tests/
├── .env
├── artisan
└── composer.json

Tiempo de instalación

Dependiendo de tu conexión a internet y de la velocidad de tu equipo, la instalación puede tardar varios minutos.

5.3.4 Configurar Nginx para Laravel

Laravel está diseñado para servir su aplicación a través de la carpeta public/. Por lo tanto, es necesario ajustar la configuración de Nginx para apuntar correctamente a esta carpeta.

Edita el archivo nginx/default.conf y modifica la directiva root:

Antes:

root /var/www/html;

Después:

root /var/www/html/public;

Además, asegúrate de que la regla de try_files esté configurada de esta forma:

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

location ~ \.php$ {
        include fastcgi_params;
        fastcgi_pass php:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }

Importante

Fijaté porque la línea fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; ha cambiaro y es crucial para el funcionamiento de Laravel. Si no la modificas, nginx no podrá encontrar los archivos PHP correctamente y devolverá un error 404.

Esta configuración permite que Laravel maneje las rutas dinámicas correctamente.

Seguridad

No debes servir directamente el contenido fuera de la carpeta public/ de Laravel. Es una mala práctica de seguridad.

5.3.5 Levantar de nuevo los servicios Docker

Después de modificar la configuración de Nginx, es necesario reiniciar los contenedores Docker para aplicar los cambios.

Ejecuta los siguientes comandos desde la raíz del proyecto:

docker-compose down
docker-compose up -d
  • docker-compose down detiene y elimina los contenedores actuales.
  • docker-compose up -d vuelve a levantar los servicios en segundo plano.

5.3.6 Verificar instalación de Laravel

Una vez que los servicios estén arriba, abre tu navegador y accede a la siguiente URL:

http://localhost:8080

Problemas de permisos

Si ves un error relacionado con permisos, asegúrate de que los permisos de las carpetas storage/ y bootstrap/cache/ sean correctos. Puedes ajustar los permisos ejecutando:

docker exec -it dk_php bash
chown -R www-data:www-data /var/www/html
exit

Deberías ver la pantalla de bienvenida de Laravel:

"Laravel" con el mensaje de "Let's get started" o similar.

Imagen de bienvenida de Laravel

Esto indica que Laravel está instalado correctamente y que la configuración del entorno es funcional.

¡Listo para empezar!

Ahora que Laravel está instalado, el siguiente paso será aprender a trabajar con rutas, controladores y modelos dentro del framework.