🚀 Guía de Instalación, Configuración y Despliegue de Laravel con Breeze

Este documento contiene el tutorial completo para configurar el entorno de desarrollo y crear un proyecto desde cero, así como los pasos para clonar e instalar un proyecto existente desde GitHub.

---

📋 Tabla de Contenidos

• 1. Crear el proyecto desde 0
  • 1.1 Requisitos e Instalación del Entorno (Linux)
  • 1.2 Configuración de php.ini
  • 1.3 Creación del Proyecto Laravel
  • 1.4 Instalación de Laravel Breeze
  • 1.5 Solución de Inconvenientes Comunes
  • 1.6 Migraciones y Compilación de Assets
  • 1.7 Ejecución de la Aplicación Web
• 2. Clonar el proyecto desde GitHub
  • Paso 1: Clonar el Repositorio e Ingresar a la Carpeta
  • Paso 2: Instalar las Dependencias del Proyecto
  • Paso 3: Configurar el Archivo de Entorno (.env)
  • Paso 4: Generar la Clave de Encriptación (APP_KEY)
  • Paso 5: Ejecutar las Migraciones de la Base de Datos
  • Paso 6: Compilar Assets e Iniciar el Servidor de Desarrollo

---

1. Crear el proyecto desde 0

Para ejecutar Laravel 11/12 se requiere PHP 8.2+, Composer, Node.js y un gestor de paquetes de frontend como pnpm.

1.1. Requisitos e Instalación del Entorno (Linux)

A. Instalar PHP y Extensiones Requeridas

En sistemas basados en Ubuntu/Debian, ejecuta:

sudo apt update
sudo apt install php php-cli php-common php-readline \
                 php-mbstring php-xml php-curl php-mysql php-sqlite3 php-zip

B. Instalar Composer (Gestor de Paquetes de PHP)

curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

Verifica la instalación con:

composer -v

C. Instalar Node.js, npm y pnpm

sudo apt install nodejs npm
sudo npm install -g pnpm

Verifica las versiones con:

node -v
pnpm -v

D. Instalar el CLI Global de Laravel (Opcional)

composer global require laravel/installer

---

1.2. Configuración de php.ini (Linux vs. Windows / XAMPP)

En Linux (Ubuntu / Debian):

PHP carga su configuración desde /etc/php/8.5/cli/php.ini (o la versión correspondiente) y los archivos en /etc/php/8.5/cli/conf.d/. Las extensiones se habilitan automáticamente al instalar los paquetes php-<extension>.

En Windows con XAMPP (Opcional / Referencia):

Si trabajas en Windows con XAMPP:

1. Localiza tu archivo php.ini en C:\xampp\php\php.ini.
2. Ábrelo con un editor de texto.
3. Busca y descomenta (quítale el punto y coma ; inicial) a las siguientes extensiones:

   extension=curl
   extension=fileinfo
   extension=mbstring
   extension=openssl
   extension=pdo_mysql
   extension=pdo_sqlite
   extension=sqlite3
   extension=zip

4. Guarda el archivo y reinicia los servicios de Apache / MySQL en el Panel de Control de XAMPP.

---

1.3. Creación del Proyecto Laravel

Para crear un nuevo proyecto en tu directorio de trabajo (por ejemplo Backend 1):

cd ~/Backend\ 1/
laravel new app01

Nota: Durante el asistente interactivo de laravel new, puedes seleccionar usar o no un Starter Kit.

---

1.4. Instalación de Laravel Breeze (Autenticación y Dashboard)

Laravel Breeze proporciona una implementación simple de todas las funciones de autenticación de Laravel (Login, Registro, Verificación de Email, Reseteo de Contraseña y Dashboard).

Paso 1: Requerir Breeze con Composer

cd app01
composer require laravel/breeze --dev

Paso 2: Ejecutar el Instalador de Breeze

php artisan breeze:install blade --pest

Pilas disponibles: blade, livewire, react, vue o api.

---

1.5. Solución de Inconvenientes Comunes

A. Error de Script laravel/boost en Composer

En versiones recientes de Laravel, el paquete laravel/boost puede interrumpir la ejecución de Composer si no ha sido inicializado (boost:update).

Solución:

1. Desinstalar el paquete bloqueante:

   composer remove laravel/boost --dev

2. Si el script persiste en composer.json, remueve la línea "@php artisan boost:update --ansi" dentro de "post-update-cmd".

B. Error Can't resolve 'tailwindcss' en Vite

Este error ocurre cuando las dependencias del frontend no se han descargado o breeze:install se interrumpió.

Solución: Reinstala las dependencias con pnpm:

pnpm install

---

1.6. Migraciones y Compilación de Assets con pnpm

A. Ejecutar Migraciones de Base de Datos

Crea las tablas de usuarios y sesiones en SQLite/MySQL:

php artisan migrate

B. Instalar y Compilar Assets de Frontend

pnpm install
pnpm dev

---

1.7. Ejecución de la Aplicación Web

Opción A: Servidores por Separado

En una terminal ejecuta el servidor de PHP:

php artisan serve

Y en otra terminal ejecuta el servidor de Vite:

pnpm dev

Opción B: Ejecutar Ambos a la Vez en una Sola Terminal (Linux)

php artisan serve & pnpm dev

O usando Composer:

composer run dev

🌐 Acceso a la Aplicación

Abre tu navegador web e ingresa a:

👉 http://127.0.0.1:8000

Podrás navegar a las rutas de /register y /login con todo el Dashboard y los estilos de Tailwind CSS funcionando correctamente.

---

2. Clonar el proyecto desde GitHub

Si clonas este repositorio en una nueva máquina o entorno de desarrollo, sigue estos pasos ordenados para ponerlo en marcha correctamente:

Paso 1: Clonar el Repositorio e Ingresar a la Carpeta

git clone <URL_DEL_REPOSITORIO>
cd resgistro-unsj

Paso 2: Instalar las Dependencias del Proyecto

Debes instalar tanto las dependencias del Backend (PHP con Composer) como las del Frontend (JavaScript con pnpm o npm):

# Instalar dependencias de PHP (Backend)
composer install

# Instalar dependencias de JavaScript/Tailwind (Frontend)
pnpm install

Nota: Si prefieres no usar pnpm, puedes utilizar npm install.

Paso 3: Configurar el Archivo de Entorno (.env)

Laravel necesita el archivo .env para gestionar variables de entorno locales como la conexión a la base de datos, URLs y claves del sistema.

1. Copia el archivo de plantilla .env.example para generar tu propio .env:

   cp .env.example .env

   (En Windows CMD puedes ejecutar copy .env.example .env)

   💡 ¿Por qué el archivo .env aparece gris en el editor y no está en Git?
   El archivo .env está incluido en el .gitignore porque almacena contraseñas, claves privadas y configuraciones específicas de tu entorno local. Por seguridad, nunca debe subirse al repositorio remoto.

2. (Opcional) Si la configuración en .env usa SQLite (predeterminada en .env.example), puedes asegurarte de crear el archivo de base de datos antes de migrar:

   touch database/database.sqlite

Paso 4: Generar la Clave de Encriptación (APP_KEY)

Genera la clave única de encriptación de la aplicación en el archivo .env:

php artisan key:generate

💡 ¿Qué hace key:generate y para qué sirve el APP_KEY?
Genera una clave aleatoria de 32 caracteres que se escribe automáticamente en la variable APP_KEY de tu archivo .env. Laravel utiliza esta clave para cifrar las cookies de usuario, tokens de sesión y datos encriptados.

Paso 5: Ejecutar las Migraciones de la Base de Datos

Crea las tablas correspondientes en la base de datos:

php artisan migrate

(Si el proyecto incluye datos de prueba iniciales o seeders, puedes ejecutar php artisan migrate --seed).

Paso 6: Compilar Assets e Iniciar el Servidor de Desarrollo

Para arrancar tanto el servidor Backend de Laravel como el servidor Frontend de Vite/Tailwind:

# Opción rápida: Iniciar ambos servicios simultáneamente con Composer
composer run dev

O en terminales independientes:

# Terminal 1 - Servidor Laravel PHP
php artisan serve

# Terminal 2 - Servidor de Vite Frontend
pnpm dev

👉 Abre tu navegador en http://127.0.0.1:8000.