Desplegar WordPress y Laravel en cPanel con Deployer

Deployer automatiza despliegues por SSH mediante una receta PHP que guardas junto al proyecto. Cada publicación puede preparar una carpeta nueva y activar esa versión al terminar. Es una alternativa para quien quiere mantener su propio proceso de despliegue; si prefieres configurarlo desde el área de clientes, consulta Deploy+.

Esta guía utiliza Deployer 8 y propone empezar con un subdominio de pruebas. Separar versiones reduce el tiempo del cambio de código, pero la continuidad del servicio también depende de las migraciones, los archivos compartidos, las cachés y los procesos de la aplicación.

Preparar el entorno

Necesitas acceso SSH al hosting, un repositorio Git accesible desde el servidor y espacio para el código, las dependencias, los archivos compartidos y varias versiones. Configura una clave de lectura para el repositorio privado si corresponde.

En tu equipo o entorno de integración, comprueba los requisitos de la instalación de Deployer 8. Esa versión requiere PHP 8.3 o posterior para ejecutar la herramienta. Instálala como dependencia de desarrollo del proyecto y guarda el archivo de bloqueo:

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

El PHP que ejecuta Deployer en tu equipo y el PHP que ejecutará la aplicación en el hosting son entornos distintos. Comprueba la versión y las extensiones de ambos, además de Composer, Git y las herramientas que necesite tu compilación.

Elegir la ubicación y la raíz pública

En las recetas, {{deploy_path}}/current representa el enlace a la versión publicada dentro de la ruta de despliegue. Deployer sustituye {{deploy_path}} por el valor que configures; no es una ruta que debas copiar literalmente en cPanel.

Usaremos /home/usuario_cpanel/apps/miapp como directorio privado de despliegue. Sustituye el usuario, el servidor, el puerto SSH y el repositorio de los ejemplos por los datos reales.

La estructura será:

miapp/
  releases/   versiones de código
  shared/     archivos que persisten
  current     enlace a la versión publicada

La raíz del dominio de pruebas debe servir current/public para Laravel o current para un WordPress tradicional. Confirma que la configuración de tu dominio permite esa ruta y los enlaces simbólicos antes del primer despliegue. Las restricciones de cPanel pueden impedir una raíz fuera de public_html; el dominio principal tampoco se configura siempre como un dominio adicional.

No muevas ni borres public_html para probar esta estructura: podría contener otras webs. Si el dominio no admite la ruta prevista, acuerda una configuración compatible con soporte o utiliza Deploy+. No publiques la carpeta completa de Laravel, que contiene archivos privados.

Ejemplo para WordPress

Este ejemplo presupone que el repositorio incluye el código de un WordPress tradicional, sus plugins y su tema. Si utilizas Bedrock u otra estructura, adapta la receta y la raíz pública.

Crea deploy.php en el proyecto:

<?php
namespace Deployer;

require 'recipe/wordpress.php';

set('repository', 'git@github.com:organizacion/wordpress.git');
set('branch', 'main');
set('keep_releases', 3);
set('shared_files', ['wp-config.php']);
set('shared_dirs', ['wp-content/uploads']);
set('writable_mode', 'chmod');
set('writable_chmod_mode', '0755');
set('writable_dirs', ['wp-content/uploads']);

host('pruebas')
    ->setHostname('servidor.example.com')
    ->setRemoteUser('usuario_cpanel')
    ->setPort(93)
    ->set('deploy_path', '/home/usuario_cpanel/apps/miapp');

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

Prepara previamente shared/wp-config.php con la configuración completa del WordPress de pruebas: base de datos, prefijo de tablas, claves y demás ajustes del sitio. Conserva esos valores al trasladar una instalación existente y revisa cualquier ruta absoluta heredada. No subas las credenciales al repositorio.

Copia las imágenes existentes a shared/wp-content/uploads y comprueba sus permisos con el usuario del hosting. La carpeta compartida debe contener los datos correctos antes de publicar; no esperes que el despliegue importe por sí solo los archivos de otra instalación.

Los plugins y temas de este ejemplo se publican desde Git. Una actualización hecha únicamente desde el administrador de WordPress puede desaparecer con la siguiente versión. Decide un flujo de actualización que mantenga el repositorio al día. Compartir todo wp-content tampoco es una solución automática: impediría versionar de forma fiable ese código.

Ejemplo para Laravel

La receta oficial de Laravel incluye tareas de migración y recarga de servicios. Antes de adoptarla, revisa cuáles necesita y permite tu aplicación. El siguiente ejemplo define un flujo explícito sin migraciones ni reinicio de procesos, para preparar primero la publicación en pruebas:

<?php
namespace Deployer;

require 'recipe/laravel.php';

set('repository', 'git@github.com:organizacion/laravel.git');
set('branch', 'main');
set('keep_releases', 3);
set('shared_files', ['.env']);
set('shared_dirs', ['storage']);
set('writable_mode', 'chmod');
set('writable_chmod_mode', '0755');
set('bin/php', '/opt/alt/php83/usr/bin/php');

host('pruebas')
    ->setHostname('servidor.example.com')
    ->setRemoteUser('usuario_cpanel')
    ->setPort(93)
    ->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',
    'deploy:publish',
]);

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

La ruta de PHP 8.3 es un ejemplo: verifica que existe y que satisface composer.lock. Configura otra versión disponible si el proyecto la requiere. Valida también cómo ejecuta Composer la receta en ese servidor.

Antes del primer despliegue, prepara shared/.env fuera de la raíz pública y con permisos restringidos al usuario de la cuenta. Utiliza la base de datos de pruebas, desactiva la depuración pública y conserva el APP_KEY de una aplicación existente: regenerarlo puede impedir descifrar datos y cerrar sesiones. Genera una clave solo para una instalación nueva que aún no la tenga.

Prepara las carpetas que la aplicación usa dentro de shared/storage, incluidos los directorios de sesiones, vistas y caché si corresponden. bootstrap/cache pertenece a cada release; no es una subcarpeta de storage. Comprueba que el usuario que ejecuta PHP pueda escribir donde lo necesita, sin permisos 777.

Si el proyecto necesita assets compilados, incorpora el resultado al artefacto o añade una tarea de compilación antes de publicar. Las tareas mostradas no ejecutan npm. Si una caché no es compatible con tu aplicación, corrige su configuración o adapta la tarea tras probarla.

Revisar y ejecutar el despliegue

Desde el equipo donde instalaste Deployer:

vendor/bin/dep deploy --plan pruebas

Revisa el orden de tareas y los hooks de la versión instalada. El plan ayuda a detectar operaciones inesperadas, pero no comprueba que el servidor o la aplicación funcionen.

Cuando el entorno de pruebas esté preparado:

vendor/bin/dep deploy pruebas

Comprueba el resultado en la salida y abre la web. Prueba acceso, una página interna, formularios, carga de imágenes y operaciones con la base de datos. En Laravel, verifica además las tareas programadas y los procesos en segundo plano que realmente utilices.

Si una ejecución falla, revisa la primera tarea con error. No desbloquees el despliegue mientras otro proceso siga trabajando ni borres versiones para liberar espacio sin identificar antes cuál está activa.

Migraciones y paso a producción

Una nueva versión puede requerir cambios de esquema. Planifica migraciones compatibles con el código que sigue atendiendo peticiones durante el cambio. Si eso no es posible, utiliza una ventana de mantenimiento y un procedimiento de recuperación comprobado.

No basta con ordenar «primero el código y luego la base de datos»: depende del cambio. Tampoco debes añadir migrate:fresh, que elimina tablas, a un despliegue de una instalación con datos.

Antes de pasar a producción, conserva una copia recuperable de archivos y base de datos, prueba la receta y prepara el cambio de raíz del dominio. La primera publicación no dispone de una release anterior a la que volver.

Volver a una versión anterior

Si conservas una versión anterior compatible, puedes activar el rollback:

vendor/bin/dep rollback pruebas

Comprueba después la web y sus operaciones principales. El rollback cambia el código publicado; no recupera la base de datos ni devuelve los archivos compartidos a su estado anterior. Una migración o un script que los haya modificado requiere su propio procedimiento de recuperación.

Las releases guardadas consumen espacio y no sustituyen a las copias de seguridad. Ajusta su retención al tamaño del proyecto y al margen disponible para construir la siguiente versión.

Para profundizar en las tareas disponibles, consulta la receta de WordPress y la receta de Laravel correspondientes a la versión que hayas instalado. En un hosting compartido utiliza tareas de despliegue con tu usuario; las recetas para aprovisionar servidores requieren privilegios que esa cuenta no tiene.