Con esta guía aprenderás a hacer Deploy de Tu Proyecto Laravel en un hosting compartido por Primera Vez.

• Todos los ejemplos en interfaz web de esta guía se basan en el administrador de hosting cPanel.

• De igual manera es posible realizar procedimientos similares en otros administradores, ante la duda puedes consultarlo con tu proveedor generando un nuevo Ticket.

• Esta guía aplica SOLO a proyectos listos para producción.

Ninguna de las optimizaciones realizadas aquí debe ser aplicada durante la etapa de desarrollo.

Si detectas algún error, comenta en la sección "issues" del proyecto en git.

• Requisitos previos 📋️
  • Dependencias
  • Terminal
  • No tengo terminal ¿qué hago?
• Comenzando 🚀️
• Comprimiendo 📦️
  • No necesitamos
  • Necesitamos
• Cargando los archivos 🗃️
• Gestionando los archivos 🗂️
  • Cambiar los permisos
  • Re-ubicando public
  • Modificando index.php
• Conexion a base de datos 💾️
  • Configurando desde 0
  • Permisos de usuario
• Ajustando variables de entorno 🔧️
  • Variables APP_
  • Variables DB_
  • Variables MAIL_
  • Otras variables
• Cargando la base 🔋️
  • Cargar por terminal web
  • Cargar de forma manual
  • phpMyAdmin
• Optimizar Laravel 🚀️
  • Comandos
  • Generar nuevo cache en el servidor
  • Por qué gestionar el cache
• Puesta en marcha 🛰️
• Gestión de registros 📑️
• Solución de problemas 🛠️
  • Modo mantenimiento
  • Activando modo debug
• Problemas generales 📜️
  • Permisos de archivos
  • Base de datos
  • Configuración antigua
  • Versión php
  • Correos
  • Otros errores
• Verificando los cambios 🏷️
• Activar la web 💡️
• Extras
  • Sugerencias
  • Autor

A continuación veremos todo lo que necesitamos para cargar nuestro proyecto a un hosting compartido.

Se asume desde ya que tu proyecto se encuentra listo para ser cargado, también que tienes instalado y conoces los manejadores Composer y NPM.

Para completar al 100% esta guía es necesario tener acceso a la Terminal Web en tu hosting, en ella podrás gestionar algunos de los comandos artisan que veremos más adelante.

En cPanel puedes acceder en Avanzado -> Terminal.

En muchos casos la terminal web no está habilitada por defecto, por lo que debes pedir a tu proveedor de servicio que la habilite. Lo más sencillo es enviar un correo o abrir un nuevo Ticket de consulta.

Una vez habilitada se verá similar a esto:

Una vez terminado el desarrollo, nos vamos a la raíz de nuestro proyecto e ingresamos los siguientes comandos en una terminal local:

Para optimizar JS y CSS

npm run production

Se debe activar si trabajas con Frameworks JS y/o CSS tales como:

• JS - React, Vue, Angular, Alpine.Js, etc
• CSS - Bootstrap, Tailwind, etc.

Para optimizar paquetes en laravel

composer install --optimize-autoloader --no-dev

Este comando de Composer permite optimizar toda la carga de clases y paquetes dentro de tu aplicación.

❗️ Se debe ejecutar cuando se hayan modificado los paquetes o dependencias ❗️

Para limpiar todo el cache local

php artisan route:clear && php artisan config:clear && php artisan cache:clear

Procedemos a crear el comprimido que contendrá todas los archivos necesarios del programa, veremos que hace falta y que no.

No es necesario comprimir ni subir algunos archivos, podemos eliminarlos en el gestor de archivos o antes de generar el comprimido.

Con esto puedes optimizar espacio y capacidad de archivos en tu hosting.

/.git - Contiene la información relacionado a la gestión de GIT.

/storage/logs/xxx.log (contenido de la carpeta logs)

Los archivos existentes en la carpeta Logs se generaron durante el desarrollo, debemos borrarlos para que existan solo los nuevos generados en producción.

Nota: En algunos sistemas es posible eliminar estas carpetas del comprimido sin necesidad de re-comprimir.

Comprima la carpeta raíz de su proyecto, incluyendo vendor y node_modules (contienen las dependencias php y js).

El resultado final será un comprimido (.zip, .tar, etc.) que contiene todas las carpetas y archivos: app, database, vendor, artisan, webpack, etc.

❗️ Atención: En algunos casos los archivos dot (.) no se incluyen durante la compresión, por ejemplo .htaccess en /public o .env en /raíz. De ser así no se preocupe, los podremos generar manualmente más adelante.

Veamos los procedimientos que debemos seguir para cargar nuestro proyecto en el servidor.

Este ejemplo está basado en interfaz de cPanel, el proceso no suele variar mucho entre distintos hostings:

• Ir a Archivos
• Sección de carga de archivos
• Cargar comprimido en directorio raíz
• Descomprimir

El resultado será parecido a este:

🏠️ /home/tu-usuario/tu-proyecto-laravel

Felicidades tu aplicación ya está cargada! 🏆️🎉️

Ahora es necesario realizar algunos ajustes antes de pasar a configuraciones más profundas. Revisaremos la seguridad general.

Es común que desarrollemos el proyecto como administradores, con permiso 777 o sudo en linux, si no cambiamos esto en producción los archivos pueden ser modificados por terceros.

🛡️ Por defecto Laravel/Symphony notifica que los archivos tienen permiso 777 y por ende personas no deseadas pueden modificarlos, veamos como evitar esta vulnerabilidad:

Para no extender de más la guía incluiré en esta sección a un tutorial que te enseña Como Gestionar y Cambiar los Permisos en tu Proyecto Laravel 🌐️.

Todos los créditos a sus respectivos creadores

Una vez completado el tutorial nuestra aplicación se encuentra segura frente a escrituras y ejecuciones maliciosas.

Como buena practica separaremos el proyecto en dos secciones, la carpeta "public" y el resto. Hacemos esto ya que no es necesario tener todo el contenido del programa en la carpeta public_html de nuestro hosting, con solo algunos archivos allí Laravel hará funcionar la aplicación.

Moveremos el contenido la carpeta "public" /home/tu-usuario/tu-proyecto-laravel/public hacia /home/public_html, esta ruta es donde accede el usuario cuando visita la página. La carpeta public_html será similar a esta:

Las carpetas y archivos varían según cada proyecto pero la estructura es similar.

Queda a criterio de cada uno si eliminar o no la carpeta /tu-proyecto-laravel/public.

Este archivo se encarga de hacer funcionar nuestra aplicación, si lo examinamos vemos que invoca archivos de dos carpetas, entre otras varias cosas. Las archivos son /vendor/autoload.php y /bootstrap/app.php.

La primera inclusión es: __DIR__.'/../vendor/autoload.php

La segunda inclusión es: __DIR__.'/../bootstrap/app.php

Si lo analizamos, las inclusiones buscan las carpetas /vendor y /bootstrap que se encuentren en esa ruta, pero estos no existen allí porque los separamos de public en el paso anterior!.

Para logar acceder a estos archivos debemos modificar los "require".

Como el contenido de public ahora está en public_html y vendor/bootstrap en la carpeta /home/tu-usuario/tu-proyecto-laravel debemos indicar la búsqueda de los archivos en una ruta anterior, para ello cambiamos los "require":

La nueva primera inclusión: __DIR__.'/../tu-proyecto-laravel/vendor/autoload.php

La nueva segunda inclusión: __DIR__.'/../tu-proyecto-laravel/bootstrap/app.php

❗️ Importante: Evite modificar el archivo index.php al cargar nuevas versiones. De ser así, actualice las inclusiones de inmediato❗️

De esta forma, nuestro proyecto ya puede cargar todo lo necesario! 🏆️

Realizaremos la conexión completa con la base de datos de producción.

❗️ Los siguientes ejemplos se basan en cPanel, los procesos no suelen variar mucho entre los distintos proveedores.

Recuerda copiar los datos que generaremos ahora: usuario, contraseña y base de datos.

Crearemos todo mediante la interfaz web.

Databases -> MySQL Databases Aquí podremos crear una nueva base para nuestro proyecto.

Creamos el usuario que utilizará la base de datos.

Agregamos el usuario a la base de datos para que la pueda manipular.

Si tenemos acceso a un gestor de BD podemos comprobar que la base se haya configurado de manera correcta.

Evitemos errores y revisemos que los permisos del usuario sean correctos para esa base.

Esto permite que el usuario pueda ejecutar las sentencias SELECT, INSERT, UPDATE, DELETE, etc. de SQL.

Ahora trabajaremos con el archivo .env de tu proyecto.

Nos aseguramos que .env se haya respaldado en el comprimido, de no ser así, creamos un nuevo .env en la raíz de nuestro proyecto /tu-proyecto-laravel/.env y copiamos dentro todos los datos del archivo local.

Cambio de variables: Revisaremos 3 secciones de nuestro .env

Los datos pueden variar según cada proyecto.

• ENV = local por production

Con esto Laravel sabe que el entorno ahora es de Producción.

• KEY = base64:xxx... por key:generate

Key es un atributo de seguridad, para actualizarlo en producción crearemos una nueva clave en la terminal local.

Ingresamos comando: php artisan key:generate

Nos creará una nueva key en .env local la cual copiamos y pegamos en el .env de producción.

• DEBUG = true por false

Debug define si mostrar errores estando en Producción, es importante establecerlo FALSE para que el usuario no vea información sensible en caso de error.

• URL = http://localhost por https://mi-dominio.com

Cambiamos la URL local por nuestro dominio.

❗️ Es aquí cuando utilizamos los datos usuario, contraseña y base de datos que habíamos guardado antes.

• DATABASE = tu-base-local por tu-base-web

La base local será remplazada por la base web.

• USERNAME = user-local por user-web

Ingresamos el usuario con acceso a la DB de nuestro hosting.

• PASSWORD = pass-local por pass-web

Cambiamos por la contraseña de ese usuario.

❗️ Esta configuración no es necesaria si no pensamos utilizar los servicios de correo de nuestro dominio o de terceros.

En este ejemplo se ve el uso de Mailtrap para la prueba de correos durante desarrollo, vamos a cambiar esto.

Necesitamos contactar con nuestro proveedor para obtener algunos datos: MAILER, PORT nos lo brinda nuestro proveedor.

• HOST = smtp.mailtrap.io por tu-dominio.com

Cambiamos el host de prueba (si existe) por nuestro dominio web.

📨️ Para estos datos debemos de tener un correo existente bajo nuestro dominio.

• USERNAME = test-user por real-mail-user

Ingresamos el correo completo example@tu-dominio.

• PASSWORD = test-pass por real-mail-pass

La contraseña de ese correo.

• FROM_ADDRESS = [email protected]

Recuerda además cambiar todas las variables que hayas modificado en tu proyecto.

Ya realizadas las modificaciones ingresamos en la Terminal Web el comando: php artisan config:cache para almacenar las nuevas configuraciones.

En caso de no tener Acceso a la Terminal Web, procederemos a borrar el cache de nuestro navegador para que se descargue el nuevo archivo de configuración al recargar.

Nuestro .env ya está configurado y listo para funcionar! 🎉️

Veremos dos formas de cargar la base de datos en nuestro servidor, utilizando la Terminal Web o cargando la BD manualmente.

❗️ Si tienes la Terminal Web habilitada.

Ingresamos a la terminal y nos situamos en el directorio raíz de nuestro proyecto con este comando: cd /home/usuario/ruta/a/tu/proyecto.

Estando allí ingresamos el comando:

php artisan migrate

Con este comando quedará generada nuestra base de datos sin ningún registro, completamente limpia y lista para usar!

Para los que no tienen acceso a la Terminal Web, ingresaremos un comando que nos permite generar una nueva BD limpia y lista para cargar:

1. Respaldar la BD de desarrollo Local (Si es necesario)
2. En la raíz de nuestro proyecto Local ingresamos

php artisan migrate:fresh

Este comando limpiará nuestra BD Local. Una vez terminadas las migraciones accederemos a la interfaz de phpMyAdmin en nuestro entorno Local. Generalmente la URL es: http://localhost/phpmyadmin.

Estando en la interfaz iremos a nuestra BD limpia y en la barra superior seleccionaremos "exportar", se generará un .sql que contiene la BD sin registros.

Con este archivo nos iremos a nuestro gestor phpMyAdmin Web o al gestor de BD que nos ofrezca nuestro hosting e importamos nuestro .sql en la base de datos que creamos antes.

Finalizada la importación comprobaremos que nuestra nueva base de datos se haya cargado correctamente.

En este punto tendremos nuestra Base de Datos pronta para usar 👏️

Ahora nos enfocaremos en optimizar la carga y velocidad de nuestra página aplicando algunos comandos artisan que Laravel tiene para ofrecernos.

Esta sección tiene 2 procesos:

• Limpiar el cache generado durante el desarrollo
• Generar nuevo cache estando en el servidor

🗳️ Recordemos que ya limpiamos el cache al inicio de la guía!

Es necesario haber limpiado el cache almacenado durante el desarrollo, ya que conservarlo puede generar errores.

Generaremos nuevo cache SOLO si tenemos acceso a la terminal web, esto agiliza los tiempos de carga y procesamiento.

❗️ Requiere el uso de la terminal web! Aplicaremos estos comandos SOLO si tenemos la terminal web.

Nos situamos en la raíz de nuestro proyecto. Por ejemplo en /home/tu-usuario/tu-proyecto-laravel/.

🧐️ Si no podemos utilizar los comandos quiere decir que estamos parados en la ruta incorrecta!

Limpiar el cache de las rutas

php artisan route:clear

Limpiar las configuraciones

php artisan config:clear

Limpieza de cache general

php artisan cache:clear

Esta linea realiza todo en una sola maniobra 📃️✂️

php artisan route:clear && php artisan config:clear && php artisan cache:clear

En este punto se habrá eliminado todo el cache generado durante el desarrollo local.

❗️ NO utilizar los siguientes comandos si no tenemos acceso a la Terminal Web ❗️

Optimiza los archivos de configuración

php artisan config:cache

Optimiza las carga de rutas

php artisan route:cache

Compila archivos blade para no hacerlo en demanda

php artisan view:cache

Esta linea realiza todo en una sola maniobra 📃️✂️

php artisan route:cache && php artisan config:cache && php artisan view:cache

En este punto se habrá generado nuevo cache con las directivas del servidor.

❗️ NO utilizar los comandos anteriores si no tenemos acceso a la Terminal Web ❗️

Al desarrollar de manera local las configuraciones y datos se almacenan con rutas similares a /var/www/html/tu-proyecto-laravel/, si no eliminamos el cache, el servidor buscará trabajar con esas rutas y esto generará errores.

Limpiar cache

La limpieza de cache debe ser ejecutada SI o SI ✔️

Generar nuevo cache

❗️ SOLO debemos generar nuevo cache si tenemos acceso a La Terminal Web ❗️

Llegó la hora de probar la web, prueba ingresar a tu dominio y admira tu aplicación Laravel.

La primera vez que ingreses a tu dominio, se generará en tu navegador cache perteneciente e este, debemos ser conscientes que cualquier configuración mal realizada YA ESTÁ almacenada.

¿Qué sucede si debemos cambiar cosas?

Es normal que ocurran errores cuando ingreses a tu web:

• Error de acceso
• Pantalla en blanco
• Las rutas no funcionan
• La API no responde
• Y un largo etc.

Para esto nos encargaremos de revisar algunos posibles errores y como solucionarlos.

❗️ Recomendación: Tener acceso a configuración para borrar cache en tu navegador, es posible que lo necesitemos hacerlo varias veces.

¿Algún error? Laravel cuenta con su propio sistema de registros integrado. Aquí vemos la importancia de limpiar la carpeta /storage/logs de tu proyecto.

Laravel / Symphony

El Framework nos provee un sistema de registros que indica errores dentro del sistema, aquí podemos ver que es lo que está fallando.

Logs del hosting

Nuestro hosting nos provee registros de errores que suceden más allá de lo que Laravel puede registrar, con esto nos referimos a errores de servidor, configuración general, entre varios otros.

En cPanel los podemos encontrar en Metrics -> Errors

Esta sección es la más amplia y compleja de la guía. Aquí se deja a libre criterio y capacidad de cada uno para resolver los distintos problemas que se puedan generar.

¿Errores?¿No sabes porque o de donde vienen? Probemos activando el modo Mantenimiento y cambiando configuraciones.

Es ideal para que nadie pueda acceder a tu web mientras tu haces las pruebas necesarias. Veremos como configurar para que puedas acceder solo tu.

El Modo Mantenimiento inhabilita el acceso a la web para que podamos trabajar los cambios necesarios sin que haya conflictos. Al intentar ingresar se mostrará el mensaje "503 servicio en mantenimiento".

Te invito a ver luego:

Cambiar pantalla de mantenimiento "503" - Ver vídeo - Simply UY

❗️ Requiere uso de terminal web ❗️

La indicación --secret permite dar acceso a tu web solo a los usuario que tienen el token de seguridad, vamos a ver un ejemplo de como funciona esto.

Accedemos a la terminal web e ingresamos en el directorio raíz de nuestro proyecto:

php artisan down --secret="tu-token-secreto"

Se indicará modo mantenimiento activo.

En este punto, probamos acceder a nuestra URL y comprobamos el mensaje "503".

Ahora ingresamos de la siguiente forma para tener acceso a nuestra web:

En la URL del navegador ingresamos:

http://tu-dominio.com/tu-token-secreto

Enseguida estaremos dentro de nuestra web. Ahora podremos cambiar la configuración para mostrar errores.

Nuestro archivo .env tiene el modo debug desactivado porque así se lo indicamos, cambiaremos esto para que se indiquen los posibles errores.

En nuestro .env cambiamos:

• APP_DEBUG = false por true

¿Todavía no aparecen los errores? Intenta borrando el cache para que se cargue la nueva configuración o aplica php artisan config:cache.

Ahora seremos capaces de ver los errores que Laravel/Symphony tienen para mostrar.

Es imposible que esta guía resuelva todos los problemas que pueden surgir durante el deploy, de todas formas, haremos referencia a los más recurrentes y como solucionarlos.

❗️ No te quedes solo con esto, busca en internet otras posibles soluciones a los problemas que vayas encontrando ❗️

Es posible que el servidor (apache u otro) nos indique vulnerabilidades como ocurre cuando se detecta que los permisos de los archivos no son correctos. Esto sucede si no se agregaron algunos permisos necesarios o si por lo contrario, están todos los permisos dados.

Existe la posibilidad de que algunas configuraciones en .env sean incorrectas. Revisa los datos de conexión, también si el usuario del hosting tiene los permisos necesarios para modificar la base de datos.

De reportarse algún problema relacionado a configuración es recomendable limpiar el cache de la app como lo hicimos anteriormente.

Es posible que el servidor ejecute una versión antigua de php y que Laravel no soporte, puedes revisar esto en la sección "versión php" del hosting.

La configuración de correos es compleja y sensible, tu proveedor de servicio puede asesorarte en este tema. Asegúrate de ingresar las credenciales correctas en tu .env.

De encontrar errores relacionados al desarrollo e instrucciones de esta guía, por favor reportarlo como problema (issue).

Una vez realizados los cambios debemos comprobarlos, pero como mencionamos antes, el cache del navegador ya está guardado, debemos borrarlo.

Con cada cambio que realizamos en nuestro .env, debemos borrar el cache generado por nuestra web en el navegador y/o ejecutar php artisan config:cache.

De esta manera almacenamos las nuevas configuraciones.

Una vez comprobados los cambios y viendo que nuestra web funciona correctamente, es momento de revertir las últimas modificaciones.

Cambiando .env

• APP_DEBUG = true por false

En terminal web

php artisan config:clear && php artisan config:cache

Apagando Modo mantenimiento

php artisan up

Ahora cualquier usuario puede ingresar en nuestra web.

🎉️ Felicidades! Tu web ya está lista y en línea! 🎉️

Has llegado al final de esta guía! De verdad espero que te haya sido de utilidad y que hayas completado la carga de tu proyecto Laravel con éxito!

Siéntete libre de realizar cualquier sugerencia o comentario. Esta guía se realiza en base a experiencia y no es perfecta.

Todas las contribuciones serán tomadas en cuenta, experiencias, comentarios, agregados, etc.

No olvides compartir con tus compañeros desarrolladores 💬️

Realizado por Guillermo de León, desarrollador FullStack Laravel + Vue.js, con ganas de compartir conocimiento y experiencia.

Puedes encontrarme en

• Guilledll - GitHub
• Simply UY - Youtube
• Guillermo de León - LinkedIn

En youtube soy Simply UY, subo programación relacionada a Laravel y Vue.js, tecnología y cualquier cosa que valga la pena compartir.

Volver arriba

⌨️ con ❤️ por Guilledll