Checklist para desplegar Laravel en Namecheap: de local a producción

Introducción

Desarrollar una aplicación con Laravel en nuestro equipo local es una cosa; publicarla en un hosting y conseguir que funcione correctamente es otra.

Durante el despliegue pueden aparecer problemas con las dependencias de PHP, las variables de entorno, los permisos de las carpetas, las imágenes almacenadas o los archivos CSS y JavaScript generados por Vite.

En este artículo compartiré una checklist práctica para desplegar aplicaciones Laravel en un hosting compartido de Namecheap, utilizando cPanel, SSH y las herramientas habituales del ecosistema Laravel.

El objetivo es tener una guía que podamos reutilizar cada vez que publiquemos una nueva versión de nuestros proyectos.

1. Preparar el proyecto local

Antes de subir los archivos al servidor, debemos verificar que nuestra aplicación funciona correctamente en el entorno de desarrollo.

Revisar los archivos importantes

Comprueba que el proyecto incluye los siguientes elementos:

composer.json y composer.lock
package.json y su archivo de bloqueo correspondiente
El archivo .env.example
Las carpetas app, bootstrap, config, database, resources y routes
La carpeta public con el punto de entrada de la aplicación

No debemos subir el archivo .env local con sus credenciales de desarrollo ni incluir contraseñas, claves privadas o archivos de configuración sensibles en un repositorio público.

Verificar las versiones

Antes de desplegar, comprueba que la versión de PHP y las extensiones requeridas por tu versión de Laravel están disponibles en Namecheap.

También conviene verificar que las dependencias de Composer sean compatibles con el servidor.

Documentación oficial:
https://laravel.com/docs/deployment

2. Configurar el hosting en Namecheap

Ingresa a cPanel y verifica los siguientes puntos:

El dominio apunta al hosting correcto.
El certificado SSL está activo.
La versión de PHP seleccionada es compatible con el proyecto.
La base de datos MySQL está creada.
El usuario de la base de datos tiene los permisos necesarios.
Tienes acceso al administrador de archivos o a SSH.

Si necesitas ejecutar comandos directamente en el servidor, habilita SSH desde las opciones disponibles para tu cuenta.

La conexión generalmente utiliza un comando similar a este:

ssh USUARIO@SERVIDOR -p 21098

Sustituye los valores por los datos de conexión de tu cuenta. El puerto puede variar según el tipo de hosting.

Guía oficial de Namecheap:
https://www.namecheap.com/support/knowledgebase/article.aspx/1016/89/how-to-access-a-hosting-account-via-ssh/

3. Organizar los archivos del proyecto

Este es uno de los puntos más importantes del despliegue.

Laravel tiene una carpeta public que contiene el punto de entrada web de la aplicación. Los archivos internos del proyecto, como .env, vendor y las carpetas de configuración, no deben quedar accesibles directamente desde Internet.

La estructura recomendada es mantener el proyecto fuera del directorio público y configurar el document root del dominio para que apunte a la carpeta public de Laravel.

Por ejemplo:

/home/USUARIO/
├── mi-proyecto/
│   ├── app/
│   ├── bootstrap/
│   ├── config/
│   ├── storage/
│   ├── vendor/
│   ├── .env
│   └── public/
│       ├── index.php
│       ├── .htaccess
│       ├── build/
│       └── storage -> enlace simbólico
└── public_html/

La estructura real dependerá de cómo esté configurado tu dominio en cPanel. Si no puedes cambiar el document root, tendrás que adaptar el despliegue con cuidado para que únicamente los archivos públicos sean accesibles.

Importante: no copies toda la aplicación Laravel dentro de public_html dejando sus archivos sensibles expuestos.

4. Instalar las dependencias de PHP

Si Composer está disponible en el servidor y el proyecto incluye composer.lock, accede a la carpeta de la aplicación y ejecuta:

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

Esto instala las dependencias necesarias para producción y optimiza el autoloader.

Si Composer no está disponible globalmente, consulta las instrucciones de Namecheap para instalarlo o ejecutarlo desde tu cuenta.

No es recomendable ejecutar composer update durante un despliegue rutinario, porque podría modificar las versiones de las dependencias respecto de las que probaste localmente.

Guía de Composer para hosting compartido:
https://www.namecheap.com/support/knowledgebase/article.aspx/9977/29/how-to-install-composer-on-shared-servers/

5. Configurar el archivo .env

En el servidor, configura las variables de entorno correspondientes a producción.

Por ejemplo:

APP_ENV=production
APP_DEBUG=false
APP_URL=https://tudominio.com

Configura también la conexión a la base de datos:

DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=nombre_base
DB_USERNAME=usuario_base
DB_PASSWORD=contraseña_segura

Los valores son ejemplos: utiliza los datos reales que aparecen en cPanel y las credenciales de tu aplicación.

Si tu proyecto utiliza correo electrónico, servicios externos, almacenamiento u otras integraciones, revisa también sus variables de entorno.

No publiques el archivo .env ni compartas capturas que muestren credenciales.

6. Preparar la base de datos

Verifica que la base de datos de producción esté creada y que el usuario tenga permisos suficientes.

Antes de ejecutar migraciones, realiza una copia de seguridad si la base de datos contiene información importante.

Después, si corresponde a tu proyecto, ejecuta:

php artisan migrate --force

La opción --force permite ejecutar las migraciones en producción sin la confirmación interactiva habitual.

No ejecutes este comando a ciegas: revisa las migraciones y confirma que no eliminarán ni modificarán datos de manera inesperada.

7. Compilar los recursos de Vite

Uno de los errores más comunes después de subir una aplicación Laravel es que no carguen correctamente los estilos CSS o los archivos JavaScript.

Cuando utilizamos Vite, debemos generar los archivos optimizados para producción.

En nuestro equipo local, dentro del proyecto, ejecutamos:

npm install
npm run build

Después, verifica que se haya generado la carpeta:

public/build/
├── manifest.json
└── assets/

Sube los archivos generados al servidor, respetando la estructura que utiliza el proyecto.

Si utilizas un flujo de despliegue que compila los recursos en el propio servidor, asegúrate de tener una versión compatible de Node.js y npm.

¿Qué ocurre si aparece localhost:5173?

Si al abrir la página encuentras referencias a localhost:5173, es posible que Laravel esté intentando utilizar el servidor de desarrollo de Vite.

Revisa si existe el archivo:

public/hot

Este archivo se utiliza para indicar que el servidor de desarrollo de Vite está activo. En producción, normalmente no debe existir.

Si quedó accidentalmente en el servidor, elimínalo después de confirmar que corresponde a un archivo residual del entorno de desarrollo. Luego verifica que public/build/manifest.json y los recursos compilados estén presentes.

8. Configurar el almacenamiento de imágenes

Este paso merece especial atención cuando trabajamos con imágenes cargadas desde formularios, categorías, productos o perfiles.

Laravel utiliza normalmente:

storage/app/public/

para guardar archivos destinados a ser accesibles públicamente.

Por ejemplo:

storage/app/public/categories/icons/
storage/app/public/appearances/logos/

Para servir estos archivos mediante las URL de la aplicación, Laravel utiliza el enlace simbólico public/storage.

Desde la raíz del proyecto, ejecuta:

php artisan storage:link

Si el enlace ya existe y está mal configurado, primero comprueba su destino y revisa si es un enlace simbólico o un directorio real. No borres una carpeta que contenga archivos sin verificar su contenido.

Cuando corresponda, corrige el enlace y vuelve a ejecutar el comando. En versiones que admitan el comando storage:unlink, también puede utilizarse para retirar el enlace anterior.

¿Cómo comprobar que funciona?

En SSH puedes revisar el enlace y los archivos:

ls -la public/storage
ls -la storage/app/public

Si guardaste imágenes en appearances/logos, también puedes comprobar esa carpeta:

ls -la storage/app/public/appearances/logos/

Finalmente, abre una imagen desde el navegador.

Si recibes un error 403, comprueba:

Que el enlace simbólico apunta a la carpeta correcta.
Que el archivo existe realmente.
Que el servidor puede acceder a las carpetas superiores.
Que los permisos permiten leer el archivo.
Que las reglas del servidor no bloquean la solicitud.

En mi experiencia, crear manualmente una carpeta public/storage puede ocasionar problemas cuando debería ser un enlace simbólico. Es preferible verificar la estructura y utilizar el mecanismo de Laravel.

9. Revisar permisos y cachés

Laravel necesita escribir en determinadas carpetas durante su funcionamiento.

Las dos ubicaciones principales que debemos revisar son:

storage/
bootstrap/cache/

En un hosting compartido, los permisos y el propietario de los archivos deben ser compatibles con la configuración del servidor.

No establezcas permisos globales de escritura para todos los usuarios. Si encuentras errores de permisos, corrige únicamente las carpetas necesarias y utiliza los permisos recomendados por tu proveedor.

Después de modificar la configuración, puedes limpiar las cachés con:

php artisan optimize:clear

Una vez que hayas comprobado que todo funciona, puedes aplicar las optimizaciones adecuadas para producción:

php artisan optimize

Ten presente que los comandos de caché deben ejecutarse con las variables de entorno correctas y que los cambios de configuración pueden requerir regenerar las cachés.

10. Verificar el archivo .htaccess

Si la página principal carga, pero las rutas internas muestran errores 404 o 500, revisa la configuración del servidor web y las reglas de reescritura.

En instalaciones Apache, Laravel suele incluir un archivo .htaccess dentro de public.

Comprueba que esté presente en el directorio público real del dominio y que el servidor permita las reglas necesarias.

No reemplaces el archivo de configuración sin entender cómo está organizada tu instalación, especialmente si utilizas un public_html separado de la carpeta principal del proyecto.

11. Realizar pruebas antes de dar por terminado el despliegue

Que la página principal cargue no significa que toda la aplicación funcione correctamente.

Utiliza esta checklist después de cada publicación:

La página principal carga mediante HTTPS.
Los estilos y scripts de Vite se muestran correctamente.
El inicio de sesión funciona.
Los formularios validan los datos.
Las operaciones CRUD funcionan correctamente.
Las imágenes existentes se muestran.
Se pueden cargar nuevas imágenes.
Las rutas internas funcionan al recargar la página.
Los correos y servicios externos funcionan, si aplica.
No aparecen errores inesperados en los registros de Laravel.

Si algo falla, revisa los registros de:

storage/logs/

También puedes utilizar los registros de errores de cPanel para detectar problemas del servidor.

12. Checklist final reutilizable

Antes de finalizar cualquier despliegue, confirma los siguientes puntos:

Versión de PHP y extensiones compatibles.
Dependencias de Composer instaladas.
Archivo .env configurado para producción.
APP_DEBUG=false.
Base de datos y credenciales verificadas.
Migraciones revisadas y ejecutadas cuando corresponde.
Recursos de Vite compilados y subidos.
Archivo public/hot residual eliminado, si existía.
Enlace public/storage comprobado.
Permisos de storage y bootstrap/cache revisados.
Cachés actualizadas.
Dominio, HTTPS y rutas probados.
Copia de seguridad disponible cuando corresponda.

Conclusión

Desplegar Laravel en Namecheap no tiene por qué convertirse en una tarea complicada si seguimos un proceso ordenado y verificamos cada componente.

Los problemas con Vite, el enlace de almacenamiento, los permisos y las variables de entorno son relativamente habituales, pero una checklist ayuda a detectarlos antes de que afecten a los usuarios.

Mi recomendación es guardar esta guía y adaptarla a cada proyecto, porque no todas las aplicaciones tienen las mismas dependencias ni todos los planes de hosting permiten la misma configuración.

Un buen despliegue no termina cuando subimos los archivos: termina cuando comprobamos que la aplicación funciona correctamente en producción.

Buscar este blog

Ejemplos de Programacion