Desarrollo y bases de datos

Desplegar WordPress y Laravel en cPanel con Deployer

Revisado el 14 min de lectura despliegues Git

Si prefieres no mantener tu propio proceso de despliegue, Deploy+ se integra con tu repositorio de GitHub y lo hace desde el área de clientes: Deploy+, despliegue automático desde GitHub.

Deployer es una herramienta escrita en PHP que publica tu aplicación en el servidor por SSH con un solo comando. Cada despliegue se prepara en una carpeta nueva y, cuando está listo, se activa cambiando un enlace simbólico. Así:

  • La web sigue funcionando mientras se prepara la nueva versión.
  • Puedes volver a la versión anterior al instante con dep rollback.
  • El proceso es siempre el mismo, sin pasos manuales que olvidar.

Todos nuestros planes de hosting son compatibles con Deployer. En esta guía verás dos ejemplos completos: WordPress y Laravel.

1. Preparar el acceso SSH

Deployer trabaja por SSH, así que necesitas:

  1. Activar el acceso SSH en tu hosting.
  2. Conectar con clave SSH desde tu ordenador. Con contraseña también funciona, pero te la pediría continuamente.

Comprueba que conectas sin problema (nuestro puerto SSH es el 93):

ssh -p 93 usuario_cpanel@tudominio.com

Si tu repositorio es privado, el servidor también tiene que poder descargarlo de GitHub: sigue clonar un repositorio privado de GitHub para crear su clave y añadirla como deploy key.

2. Instalar Deployer en tu ordenador

Deployer se instala y se ejecuta en tu ordenador, no en el hosting. La versión actual es la 8 y necesita PHP 8.3 o superior en tu equipo. Lo más cómodo es añadirlo al proyecto:

composer require --dev deployer/deployer:^8
vendor/bin/dep --version

También puedes instalarlo de forma global con composer global require deployer/deployer y usar el comando dep directamente. En los ejemplos usamos vendor/bin/dep.

3. Elegir dónde se despliega

Deployer crea esta estructura dentro de la ruta de despliegue (deploy_path):

/home/usuario_cpanel/apps/miapp/      ← deploy_path
├── releases/
│   ├── 1/
│   ├── 2/
│   └── 3/                            ← última versión
├── shared/                           ← lo que se conserva entre versiones
│   ├── .env                          (Laravel)
│   ├── storage/                      (Laravel)
│   ├── wp-config.php                 (WordPress)
│   └── wp-content/uploads/           (WordPress)
├── current -> releases/3             ← versión publicada
└── .dep/

En los ficheros de Deployer esa ruta se escribe {{deploy_path}}, así que la versión publicada es {{deploy_path}}/current.

Usa una carpeta fuera de public_html, por ejemplo /home/usuario_cpanel/apps/miapp. La web tiene que servirse desde:

  • WordPress: /home/usuario_cpanel/apps/miapp/current
  • Laravel: /home/usuario_cpanel/apps/miapp/current/public

Cómo se consigue depende del dominio:

  • Dominio adicional o subdominio: en cPanel, entra en Dominios, pulsa Administrar en el dominio y cambia su raíz de documentos a esa ruta. Tienes los pasos en cambiar la ruta de un dominio adicional.
  • Dominio principal: siempre usa public_html y su ruta no se puede cambiar. Se resuelve convirtiendo public_html en un enlace simbólico, como verás en el paso 7.

Si es tu primera vez con Deployer, empieza con un subdominio de pruebas, por ejemplo pruebas.tudominio.com.

4. Ejemplo para WordPress

Este ejemplo supone que el repositorio contiene un WordPress normal con sus plugins y tema. Crea deploy.php en la raíz del proyecto:

<?php
namespace Deployer;

require 'recipe/wordpress.php';

set('repository', 'git@github.com:tu_usuario/tu_repo_wordpress.git');
set('branch', 'main');
set('keep_releases', 3);

// Se conservan entre versiones
set('shared_files', ['wp-config.php']);
set('shared_dirs', ['wp-content/uploads']);
set('writable_dirs', ['wp-content/uploads']);
set('writable_mode', 'chmod');
set('writable_chmod_mode', '0755');

host('produccion')
    ->setHostname('tudominio.com')
    ->setRemoteUser('usuario_cpanel')
    ->setPort(93)
    ->setIdentityFile('~/.ssh/id_ed25519')
    ->set('deploy_path', '/home/usuario_cpanel/apps/miapp');

after('deploy:failed', 'deploy:unlock');

Antes del primer despliegue, prepara en el servidor la carpeta shared:

  1. Crea la base de datos y su usuario en Bases de datos MySQL de cPanel.

  2. Por SSH, crea las carpetas:

    mkdir -p /home/usuario_cpanel/apps/miapp/shared/wp-content/uploads
    
  3. Crea /home/usuario_cpanel/apps/miapp/shared/wp-config.php a partir de wp-config-sample.php, con los datos de la base de datos y unas claves nuevas generadas en api.wordpress.org/secret-key/1.1/salt. Si trasladas una web existente, copia su wp-config.php tal cual, con el mismo prefijo de tablas.

  4. Si la web ya tiene imágenes, cópialas a shared/wp-content/uploads.

No subas wp-config.php ni uploads al repositorio.

Ten en cuenta que los plugins y el tema se publican desde Git: si los actualizas desde el escritorio de WordPress, el siguiente despliegue los devolverá a la versión del repositorio. Actualízalos en tu copia local, haz commit y despliega.

5. Ejemplo para Laravel

<?php
namespace Deployer;

require 'recipe/laravel.php';

set('repository', 'git@github.com:tu_usuario/tu_repo_laravel.git');
set('branch', 'main');
set('keep_releases', 3);
set('writable_mode', 'chmod');
set('writable_chmod_mode', '0755');

// PHP del hosting con el que se ejecutan Composer y artisan
set('bin/php', '/opt/alt/php83/usr/bin/php');

host('produccion')
    ->setHostname('tudominio.com')
    ->setRemoteUser('usuario_cpanel')
    ->setPort(93)
    ->setIdentityFile('~/.ssh/id_ed25519')
    ->set('deploy_path', '/home/usuario_cpanel/apps/miapp');

task('deploy', [
    'deploy:prepare',
    'deploy:vendors',
    'artisan:storage:link',
    'artisan:config:cache',
    'artisan:route:cache',
    'artisan:view:cache',
    'artisan:migrate',
    'deploy:publish',
]);

after('deploy:failed', 'deploy:unlock');

La receta de Laravel ya comparte .env y storage entre versiones. Cambia php83 por la versión que necesite tu proyecto (la misma que tenga el dominio en cPanel): las rutas disponibles son /opt/alt/php81/usr/bin/php, /opt/alt/php82/usr/bin/php, etc. Si no quieres que las migraciones se ejecuten solas, quita la línea artisan:migrate.

Antes del primer despliegue, crea la base de datos en cPanel y, por SSH, el fichero .env compartido:

mkdir -p /home/usuario_cpanel/apps/miapp/shared
nano /home/usuario_cpanel/apps/miapp/shared/.env

Con un contenido como este:

APP_NAME="Mi aplicación"
APP_ENV=production
APP_KEY=base64:...
APP_DEBUG=false
APP_URL=https://tudominio.com

LOG_LEVEL=error

DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=usuario_cpanel_basedatos
DB_USERNAME=usuario_cpanel_usuario
DB_PASSWORD=la_contraseña

CACHE_STORE=file
SESSION_DRIVER=file
QUEUE_CONNECTION=database

Para APP_KEY: si la aplicación ya está en producción, copia la que tiene (si la cambias se cierran las sesiones y no podrás leer los datos cifrados). Si es nueva, genérala en tu ordenador con php artisan key:generate --show y pégala.

Si el proyecto necesita compilar CSS y JS (Vite, Mix…), compílalos y súbelos en el repositorio, o añade una tarea que ejecute npm run build antes de deploy:publish. Tienes cómo usar Node en el hosting en instalar Node.js y compilar assets.

6. Desplegar

Desde la carpeta del proyecto en tu ordenador, comprueba primero qué tareas se van a ejecutar:

vendor/bin/dep deploy --plan produccion

Y despliega:

vendor/bin/dep deploy produccion

Deployer clona el repositorio en una nueva carpeta de releases, instala las dependencias, enlaza los ficheros compartidos y, al final, apunta current a la nueva versión. Abre la web y comprueba que funciona.

Para volver a la versión anterior:

vendor/bin/dep rollback produccion

El rollback cambia el código publicado, pero no deshace cambios en la base de datos ni en los ficheros compartidos. Si una migración ha modificado tablas, tendrás que revertirla aparte.

7. Dominio principal: enlazar public_html

El dominio principal siempre se sirve desde public_html. La solución es sustituir esa carpeta por un enlace simbólico que apunte a la versión publicada. Hazlo una sola vez, después del primer despliegue (cuando ya existe current):

cd /home/usuario_cpanel
mv public_html public_html.antiguo

# Laravel
ln -s /home/usuario_cpanel/apps/miapp/current/public public_html

# WordPress
ln -s /home/usuario_cpanel/apps/miapp/current public_html

Compruébalo con ls -l /home/usuario_cpanel: debe aparecer public_html -> /home/usuario_cpanel/apps/miapp/current/public (o .../current en WordPress). Como current cambia en cada despliegue, el enlace siempre lleva a la última versión, también tras un rollback.

Antes de hacerlo, revisa si dentro de public_html hay carpetas de otros dominios o subdominios: dejarían de funcionar. Muévelas antes a otra ruta y cambia la raíz de esos dominios. Cuando compruebes que todo va bien, puedes borrar public_html.antiguo.

Errores frecuentes

No conecta por SSH

  • Prueba la conexión a mano: ssh -p 93 -i ~/.ssh/id_ed25519 usuario_cpanel@tudominio.com.
  • La clave pública tiene que estar autorizada en cPanel, en Acceso SSH > Administrar claves SSH.
  • La clave privada de tu ordenador debe tener permisos restringidos: chmod 600 ~/.ssh/id_ed25519.
  • Si da problemas con la reutilización de conexiones, añade set('ssh_multiplexing', false);.

Falla al clonar el repositorio

  • Es el servidor el que clona: su clave (~/.ssh/id_ed25519 en el hosting) debe estar en GitHub como deploy key. Pruébalo por SSH en el hosting con ssh -T git@github.com.
  • Alternativa: añade ->setForwardAgent(true) al host para que use la clave de tu ordenador, cargada con ssh-add.

Falla deploy:vendors (Composer)

  • El PHP de bin/php no cumple los requisitos de composer.lock: ajusta la ruta a la versión correcta.
  • Si se queda sin memoria, mira errores de memoria de Composer.

Falla artisan:migrate

  • Revisa los datos de base de datos en shared/.env. En cPanel, la base de datos y el usuario llevan delante tu usuario de cPanel (usuario_cpanel_).
  • El usuario de la base de datos necesita todos los privilegios sobre ella.

La web da error 404 o 500, o muestra la versión antigua

  • Comprueba con ls -l que la raíz del dominio o public_html apunta a current/public (Laravel) o current (WordPress).
  • En Laravel, mira el error en /home/usuario_cpanel/apps/miapp/shared/storage/logs/laravel.log.
  • Si usas caché de LiteSpeed u OPcache y sigues viendo la versión anterior, vacía la caché.

Deployer dice que el despliegue está bloqueado

Un despliegue anterior se interrumpió. Si estás seguro de que no hay otro en marcha, ejecuta vendor/bin/dep deploy:unlock produccion.

La receta de cPanel de Deployer

Deployer incluye una receta contrib/cpanel.php que crea dominios y bases de datos de pruebas automáticamente. No sirve en un hosting compartido: necesita un token de WHM con acceso de administrador del servidor (usuario root, puerto 2087). Crea el subdominio y la base de datos de pruebas desde cPanel y despliega en ellos con la configuración de esta guía.

También te puede ayudar

¿Algo no cuadra o ha cambiado? Cuéntanoslo y lo revisamos.