Desarrollo y bases de datos
Desplegar WordPress y Laravel en cPanel con Deployer
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:
- Activar el acceso SSH en tu hosting.
- 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_htmly su ruta no se puede cambiar. Se resuelve convirtiendopublic_htmlen 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:
-
Crea la base de datos y su usuario en Bases de datos MySQL de cPanel.
-
Por SSH, crea las carpetas:
mkdir -p /home/usuario_cpanel/apps/miapp/shared/wp-content/uploads -
Crea
/home/usuario_cpanel/apps/miapp/shared/wp-config.phpa partir dewp-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 suwp-config.phptal cual, con el mismo prefijo de tablas. -
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_ed25519en el hosting) debe estar en GitHub como deploy key. Pruébalo por SSH en el hosting conssh -T git@github.com. - Alternativa: añade
->setForwardAgent(true)al host para que use la clave de tu ordenador, cargada conssh-add.
Falla deploy:vendors (Composer)
- El PHP de
bin/phpno cumple los requisitos decomposer.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 -lque la raíz del dominio opublic_htmlapunta acurrent/public(Laravel) ocurrent(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
- Automatizar el deploy en cPanel con el fichero .cpanel.yml Cómo escribir el fichero .cpanel.yml con las tareas de cada despliegue en Git de cPanel, cuándo se e...
- Clonado y deploy desde repositorio remoto privado Autoriza una clave SSH del hosting en GitHub, clona un repositorio privado, verifica la conexión y a...
- Deploy automático desde GitHub, GitLab o Bitbucket con rollback instantáneo Conecta un repositorio Git al hosting, ejecuta scripts por versión con variables del despliegue y de...
- Alojar React, Vue y webs estáticas conectadas a APIs externas Comprueba si tu frontend JavaScript cabe en un hosting compartido, conéctalo a Supabase, Firebase u...
¿Algo no cuadra o ha cambiado? Cuéntanoslo y lo revisamos.