App Laravel en servidor con Forge

Instalación de una app Laravel en un servidor existente gestionado con Forge.

Definir nombre de la app

Módulo fuente: Nomenclatura de aplicaciones

Nomenclatura de aplicaciones

🎯 Objetivo: Definir nombres consistentes para las aplicaciones.

Formato obligatorio

[cliente]-[app]-[ambiente]

Reglas

Todo en minúsculas.
Solo letras, números y guión medio (-).
Sin espacios, tildes, ñ, guión bajo (_) ni caracteres especiales.
cliente y app deben ser cortos y claros.
ambiente debe ser uno de: prod, staging, dev, test.
No repetir palabras entre cliente y app.

Ejemplos válidos

trantor-form990-prod
agrosuper-intranet-staging
tallerdigital-crm-prod
luksic-portal-dev

Ejemplos inválidos

Trantor-Form990-Prod (mayúsculas)
trantor_form990_prod (guión bajo)
trantor-form 990-prod (espacio)
trantor-form990-production (ambiente no estándar)
trantor--form990-prod (doble guión)

Crear sitio Laravel y base de datos

Módulo fuente: Crear sitio Laravel y base de datos en Forge

Crear sitio Laravel y base de datos en Forge

Objetivo: crear el sitio productivo con configuración base de runtime y DB.

Crear sitio

En Forge (Sites -> New Site) usar:

Project Type: Laravel
Web Directory: /public
Root Domain: <dominio>

Crear base de datos

En Forge (Database):

Crear base MySQL
Crear usuario
Asignar usuario a la base

Guardar credenciales en gestor de secretos.

Conectar repositorio y habilitar deploy

Módulo fuente: Conectar repositorio y habilitar deploy

Conectar repositorio y habilitar deploy

Objetivo: enlazar Git con el sitio y habilitar despliegue continuo desde Forge.

Conectar repositorio

En el sitio de Forge, configurar:

Proveedor Git (GitHub, GitLab o Bitbucket)
Repositorio
Rama (main o master)

Configurar deploy script

Definir script de despliegue del proyecto y guardar cambios.

Habilitar Quick Deploy

Activar Quick Deploy para que cada push a la rama de despliegue ejecute deploy automático.

Verificación

Realizar un commit de prueba y confirmar en Forge que el deploy termina en Successful.

Configurar variables .env

Módulo fuente: Configurar variables .env de Laravel

Configurar variables .env de Laravel

Objetivo: dejar ambiente de producción con variables de aplicación, base de datos, cache y cola correctamente definidas.

Variables clave

Editar .env desde Forge (Environment) y validar al menos:

APP_NAME="<nombre_app>"
APP_ENV=production
APP_KEY=base64:...
APP_DEBUG=false
APP_URL=https://<dominio>
LOG_CHANNEL=stack
LOG_LEVEL=error

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=<db_name>
DB_USERNAME=<db_user>
DB_PASSWORD=<db_pass>

CACHE_DRIVER=redis
QUEUE_CONNECTION=redis
SESSION_DRIVER=redis
SESSION_LIFETIME=120
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

Verificación

Comprobar que APP_KEY exista, que no queden credenciales placeholder y que la app use APP_ENV=production.

Configurar SSL

Módulo fuente: Configurar SSL en Forge (Let's Encrypt)

Configurar SSL en Forge (Let’s Encrypt)

Objetivo: habilitar HTTPS válido para el dominio del sitio.

Verificar DNS antes de emitir certificado

El dominio debe resolver a la IP del servidor.

dig <dominio> +short

Emitir certificado en Forge

En el sitio: SSL -> Let's Encrypt -> seleccionar dominios -> Obtain Certificate.

Verificación

curl -I https://<dominio>
openssl s_client -connect <dominio>:443 -servername <dominio> < /dev/null 2>/dev/null | grep "Verify return code"

Esperado: HTTP 200 y Verify return code: 0 (ok).

Configurar deploy script

Módulo fuente: Configurar deploy script para Laravel

Configurar deploy script para Laravel

Objetivo: estandarizar despliegues consistentes después de cada push.

Script recomendado

cd /home/forge/<dominio>
git pull origin $FORGE_SITE_BRANCH
composer install --no-interaction --prefer-dist --optimize-autoloader --no-dev
php artisan migrate --force
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan queue:restart

Verificación

Ejecutar Deploy Now y confirmar estado Successful.

Ejecutar migraciones

Módulo fuente: Ejecutar migraciones Laravel

Ejecutar migraciones Laravel

Objetivo: crear estructura de base de datos de la aplicación.

Ejecutar migrate

ssh forge@<ip_servidor>
cd /home/forge/<dominio>
php artisan migrate --force

Verificación

php artisan migrate:status

Esperado: migraciones aplicadas sin errores.

Configurar permisos de storage/cache

Módulo fuente: Configurar permisos de storage y cache

Configurar permisos de storage y cache

Objetivo: evitar errores 500 por permisos al escribir logs, cache, sesiones y vistas compiladas.

Ajustar permisos

ssh forge@<ip_servidor>
cd /home/forge/<dominio>
chmod -R 775 storage bootstrap/cache
chmod -R ug+rwx storage bootstrap/cache
chown -R forge:forge storage bootstrap/cache

Verificación

ls -la storage bootstrap/cache

Esperado: usuario/grupo forge con permisos de escritura.

Configurar queue worker (opcional)

Módulo fuente: Configurar queue worker (opcional)

Configurar queue worker (opcional)

Objetivo: procesar trabajos de cola en background cuando la app usa colas.

Crear daemon en Forge

En Daemons -> New Daemon:

Command: php artisan queue:work redis --sleep=3 --tries=3 --max-time=3600
User: forge
Directory: /home/forge/<dominio>
Processes: 1 (o más según carga)

Verificación

sudo supervisorctl status

Esperado: daemon en estado RUNNING.

Verificar scheduler (opcional)

Módulo fuente: Verificar scheduler (opcional)

Verificar scheduler (opcional)

Objetivo: asegurar ejecución periódica de tareas programadas de Laravel.

Revisar scheduler en Forge

En la sección Scheduler del sitio, confirmar que existe la tarea por minuto.

Verificación en servidor

ssh forge@<ip_servidor>
crontab -l

Esperado: entrada equivalente a php artisan schedule:run cada minuto.

Validación final

Módulo fuente: Validación final de Laravel en Forge

Validación final de Laravel en Forge

Objetivo: confirmar disponibilidad, SSL y salud básica del runtime.

Pruebas mínimas

curl -I https://<dominio>
openssl s_client -connect <dominio>:443 -servername <dominio> < /dev/null 2>/dev/null | grep "Verify return code"

ssh forge@<ip_servidor>
cd /home/forge/<dominio>
php artisan migrate:status
ls -la bootstrap/cache/
tail -50 storage/logs/laravel.log

Esperado: sitio accesible, SSL válido, migraciones aplicadas y sin errores críticos en logs.