مرکز آموزش

En WizHosting podés correr aplicaciones Laravel sin necesidad de acceso root, usando tu cuenta compartida con cPanel + CloudLinux.

En esta guía vas a ver:

1. Requisitos y conceptos básicos.

2. Dónde ubicar los archivos de Laravel.

3. Cómo crear la base de datos y usuario en cPanel.

4. Cómo configurar el archivo .env.

5. Cómo instalar dependencias con Composer.

6. Qué hacer con la carpeta public/ y public_html.

7. Permisos recomendados y optimización.

8. Errores frecuentes y cómo resolverlos.

Nota: los pasos son compatibles con la forma recomendada en la documentación oficial de Laravel para despliegue en producción y con las guías de instalación en cPanel usando Composer como usuario de cuenta compartida.

1. Requisitos y conceptos básicos

Antes de empezar, necesitás:

1. Un plan de hosting con soporte para PHP y Composer (los servicios de WizHosting lo tienen).

2. Acceso a tu cPanel (usuario y contraseña).

3. Un proyecto Laravel ya creado:

   • Puede haber sido generado en tu PC (laravel new, composer create-project) o directamente en el servidor via Composer.

Laravel recomienda en producción:

• APP_ENV=production

• APP_DEBUG=false

• Permisos de escritura solo en storage/ y bootstrap/cache/.

2. Estructura de carpetas recomendada en el hosting

La estructura típica en una cuenta de hosting es:

La idea es:

• Dejar todo el código de Laravel fuera de public_html (por ejemplo, en /home/usuario/laravel).

• Que solo lo que hay en public/ sea accesible desde la web (ya sea apuntando el docroot a esa carpeta o copiando su contenido a public_html).

Como en cPanel, el document root suele ser public_html, hay dos enfoques:

1. Apuntar el document root del dominio a laravel/public (si el panel lo permite).

2. Mantener el document root en public_html y mover el contenido de public/ a public_html, ajustando rutas en index.php.

En cuentas compartidas, lo más habitual (y fácil de explicar al cliente final) es la opción 2.

3. Crear el proyecto Laravel (dos escenarios)

3.1. Crear el proyecto directamente en el servidor

1. Entrá a cPanel.

2. Abrí Terminal (si está disponible) o conectate por SSH con el usuario de cPanel.

3. Movete a tu home:

    

   cd ~

4. Creá el proyecto con Composer (ejemplo):

    

   composer create-project laravel/laravel laravel

Esto va a generar una carpeta /home/usuario/laravel con toda la estructura de Laravel.

cPanel documenta explícitamente este tipo de flujo usando Composer desde la cuenta del usuario, sin permisos de root.

3.2. Subir un proyecto Laravel que ya tenés en tu PC

1. En tu PC, ubicá la carpeta raíz del proyecto (la que contiene artisan, app/, routes/, etc.).

2. NO hace falta subir vendor/ ni node_modules (los podemos regenerar luego).

3. Comprimí el proyecto (sin vendor/ ni node_modules) en un ZIP (ej: mi-laravel.zip).

4. En cPanel → File Manager:

   • Creá la carpeta laravel en tu home.

   • Entrá a /home/usuario/laravel.

   • Subí el ZIP y usá Extract / Extraer.

Al final deberías tener:

4. Crear la base de datos en cPanel

Laravel usa una base de datos (MySQL/MariaDB) para la mayoría de proyectos.

1. En cPanel, entrá a MySQL® Databases.

2. Creá una nueva base de datos, por ejemplo:

   • usuario_miaplicacion

3. Creá un usuario MySQL, por ejemplo:

   • usuario_miaplicacion_u con contraseña segura.

4. En el bloque Add User To Database, asigná ese usuario a la base de datos nueva con ALL PRIVILEGES.

Anotá:

• Nombre de la base de datos.

• Usuario.

• Contraseña.

Los vas a usar en el .env.

5. Configurar el archivo .env

En /home/usuario/laravel, buscá el archivo .env. Si no existe, copiá el ejemplo:

Y editá .env (podés usar el editor de archivos del cPanel o nano/vim por SSH):

5.1. Generar la APP_KEY

Desde el Terminal o SSH:

Esto completa APP_KEY en .env, como recomienda la documentación oficial de Laravel para producción.

6. Instalar dependencias PHP (Composer)

Si subiste el proyecto sin vendor/, o si lo creaste desde composer create-project, asegurate de tener todas las dependencias:

Laravel recomienda en producción usar:

• --no-dev para evitar paquetes de desarrollo.

• --optimize-autoloader para mejorar el rendimiento.

Si ya tenías vendor/ subido, este paso igual es útil para actualizar dependencias si cambió composer.json.

7. Exponer la carpeta public/ (public_html)

Acá viene el punto crítico: Laravel espera que el “document root” apunte a su carpeta public/.

Como en cPanel el document root del dominio principal suele ser public_html, hay dos formas:

Opción A – Cambiar el document root del dominio (más “limpia”)

Si tu panel lo permite (por ejemplo, agregando un dominio nuevo o editando el existente), podés hacer que el docroot sea:

En ese caso:

• No usás public_html para la app Laravel.

• Todo lo que esté en public/ se sirve directamente.

(Depende de cómo está montado el panel; muchos usuarios de hosting compartido no tienen esta opción tan directa.)

Opción B – Copiar el contenido de public/ a public_html (la más común)

Es el enfoque más fácil de explicar y funciona perfecto en cuentas compartidas.

1. En el File Manager de cPanel:

   • Abrí /home/usuario/laravel/public.

   • Seleccioná TODO lo que hay dentro (archivos y carpetas), por ejemplo:

     • index.php

     • css/

     • js/

     • build/ (en versiones nuevas)

   • Usá la opción Copy / Copiar.

   • Elegí como destino /home/usuario/public_html.

2. Una vez copiado, en /home/usuario/public_html vas a tener un index.php y las carpetas públicas de Laravel.

3. Ahora hay que editar ese index.php para que apunte a la ubicación real del framework.

Por defecto, public/index.php de Laravel hace referencia a:

Pero como ahora el index.php está en public_html, y el proyecto en /home/usuario/laravel, tenés que ajustar esas rutas.

Por ejemplo:

La idea es que las rutas apunten a donde realmente están vendor/autoload.php y bootstrap/app.php dentro de tu cuenta.

Este patrón (copiar contenido de public/ a public_html y ajustar index.php) es muy usado en despliegues de Laravel sobre cPanel compartido.

Importante: No muevas toda la carpeta laravel a public_html. Lo seguro es dejar el framework fuera de la carpeta pública y solo exponer los archivos frontales.

8. Permisos de carpetas y archivos

Según las recomendaciones oficiales de Laravel, en producción las únicas carpetas que necesitan permiso de escritura por parte del servidor web son:

• storage/

• bootstrap/cache/

En la práctica en cPanel alcanza con:

En algunos casos se usa 775 según configuración del servidor, pero evitá 777, no es necesario y es inseguro.

9. Optimizar la app para producción (opcional, pero recomendable)

Laravel ofrece varios comandos para optimizar rendimiento en producción:

La propia documentación de Laravel recomienda hacer estas optimizaciones para entornos productivos.

Si hacés cambios en config, rutas o vistas, quizás debas limpiar y regenerar estos caches (php artisan config:clear, etc.).

10. Probar el sitio

Con todo configurado:

1. Abrí en tu navegador:
   https://tudominio.com

2. Si todo está correcto, deberías ver la página de inicio de tu app Laravel (o la pantalla por defecto si no la cambiaste).

3. Si aparece un error 500 o una pantalla en blanco:

   • Revisá el archivo storage/logs/laravel.log.

   • Verificá que el .env tenga bien los datos de la base.

   • Verificá que las rutas en public_html/index.php apunten bien a /home/usuario/laravel.

11. Errores frecuentes y cómo resolverlos

11.1. Error 500 / “Whoops, looks like something went wrong”

Causas típicas:

• APP_KEY vacío.

• .env mal configurado (DB o permisos).

• Rutas incorrectas en index.php.

Soluciones:

1. Verificar .env y correr php artisan key:generate.

2. Chequear storage/logs/laravel.log.

3. Revisar que las rutas en index.php apunten correctamente a /laravel/vendor y /laravel/bootstrap.

11.2. “No such file or directory” hacia vendor/autoload.php

Causa: el index.php busca vendor/autoload.php usando una ruta relativa que ya no coincide con la estructura del servidor.

Solución:

• Editar index.php en public_html y ajustarlo, por ejemplo:

(si tu carpeta del proyecto se llama laravel).

11.3. Migraciones o seeds no corren

Si al ejecutar migraciones (php artisan migrate) hay errores:

• Revisá la config de DB en .env.

• Verificá que el usuario de base de datos tenga privilegios sobre la base.

• Mirá los errores concretos que arroja el comando.

11.4. Cambié el código y no se ve el cambio

Si activaste caches (config, rutas, vistas):

1. Podés limpiar y regenerar:

    

   php artisan config:clear php artisan route:clear php artisan view:clear php artisan config:cache php artisan route:cache php artisan view:cache

2. Hacé un hard refresh en el navegador (Ctrl+F5 / Cmd+Shift+R).

12. Resumen rápido

1. Creá (o subí) tu proyecto Laravel a /home/usuario/laravel.

2. Creá la base de datos y usuario MySQL en cPanel, asignale todos los privilegios.

3. Configurá el .env con datos de base y APP_ENV=production, APP_DEBUG=false.

4. Ejecutá php artisan key:generate.

5. Corré composer install --no-dev --optimize-autoloader.

6. Copiá el contenido de laravel/public a public_html.

7. Ajustá las rutas de vendor/autoload.php y bootstrap/app.php en public_html/index.php.

8. Asegurate de que storage/ y bootstrap/cache/ sean escribibles.

9. Opcional: corré los comandos de optimización (config:cache, route:cache, etc.).

10. Probá tu dominio y revisá storage/logs/laravel.log ante cualquier error.