Implementar o WordPress e o Laravel no cPanel com o Deployer

O Deployer automatiza implementações por SSH através de uma receita PHP que guarda junto ao projeto. Cada publicação pode preparar uma pasta nova e ativar essa versão no fim. É uma alternativa para quem quer manter o seu próprio processo de implementação; se preferir configurá-lo a partir da área de cliente, consulte o Deploy+.

Este guia utiliza o Deployer 8 e propõe começar com um subdomínio de testes. Separar versões reduz o tempo da mudança de código, mas a continuidade do serviço depende também das migrações, dos ficheiros partilhados, das caches e dos processos da aplicação.

Preparar o ambiente

Precisa de acesso SSH ao alojamento, de um repositório Git acessível a partir do servidor e de espaço para o código, as dependências, os ficheiros partilhados e várias versões. Configure uma chave de leitura para o repositório privado, se for o caso.

No seu computador ou ambiente de integração, verifique os requisitos da instalação do Deployer 8. Essa versão exige PHP 8.3 ou posterior para executar a ferramenta. Instale-a como dependência de desenvolvimento do projeto e guarde o ficheiro de bloqueio:

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

O PHP que executa o Deployer no seu computador e o PHP que executará a aplicação no alojamento são ambientes distintos. Verifique a versão e as extensões de ambos, bem como o Composer, o Git e as ferramentas de que a sua compilação precise.

Escolher a localização e a raiz pública

Nas receitas, {{deploy_path}}/current representa a ligação para a versão publicada dentro do caminho de implementação. O Deployer substitui {{deploy_path}} pelo valor que configurar; não é um caminho que deva copiar literalmente no cPanel.

Usaremos /home/usuario_cpanel/apps/miapp como diretório privado de implementação. Substitua o utilizador, o servidor, a porta SSH e o repositório dos exemplos pelos dados reais.

A estrutura será:

miapp/
  releases/   versões do código
  shared/     ficheiros que persistem
  current     ligação à versão publicada

A raiz do domínio de testes deve servir current/public para o Laravel ou current para um WordPress tradicional. Confirme que a configuração do seu domínio permite esse caminho e as ligações simbólicas antes da primeira implementação. As restrições do cPanel podem impedir uma raiz fora de public_html; o domínio principal também nem sempre se configura como um domínio adicional.

Não mova nem apague public_html para testar esta estrutura: poderia conter outros sites. Se o domínio não admitir o caminho previsto, combine uma configuração compatível com o suporte ou utilize o Deploy+. Não publique a pasta completa do Laravel, que contém ficheiros privados.

Exemplo para WordPress

Este exemplo pressupõe que o repositório inclui o código de um WordPress tradicional, os seus plugins e o seu tema. Se utilizar o Bedrock ou outra estrutura, adapte a receita e a raiz pública.

Crie deploy.php no projeto:

<?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');

Prepare previamente shared/wp-config.php com a configuração completa do WordPress de testes: base de dados, prefixo das tabelas, chaves e restantes definições do site. Mantenha esses valores ao transferir uma instalação existente e reveja qualquer caminho absoluto herdado. Não envie as credenciais para o repositório.

Copie as imagens existentes para shared/wp-content/uploads e verifique as suas permissões com o utilizador do alojamento. A pasta partilhada tem de conter os dados corretos antes de publicar; não espere que a implementação importe por si só os ficheiros de outra instalação.

Os plugins e temas deste exemplo são publicados a partir do Git. Uma atualização feita apenas a partir do administrador do WordPress pode desaparecer com a versão seguinte. Defina um fluxo de atualização que mantenha o repositório em dia. Partilhar todo o wp-content também não é uma solução automática: impediria versionar esse código de forma fiável.

Exemplo para Laravel

A receita oficial do Laravel inclui tarefas de migração e de recarga de serviços. Antes de a adotar, reveja quais delas a sua aplicação precisa e permite. O exemplo seguinte define um fluxo explícito sem migrações nem reinício de processos, para preparar primeiro a publicação em testes:

<?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');

O caminho do PHP 8.3 é um exemplo: verifique que existe e que satisfaz o composer.lock. Configure outra versão disponível se o projeto o exigir. Valide também como a receita executa o Composer nesse servidor.

Antes da primeira implementação, prepare shared/.env fora da raiz pública e com permissões restritas ao utilizador da conta. Utilize a base de dados de testes, desative a depuração pública e mantenha a APP_KEY de uma aplicação existente: regenerá-la pode impedir a decifração de dados e terminar sessões. Gere uma chave apenas para uma instalação nova que ainda não a tenha.

Prepare as pastas que a aplicação usa dentro de shared/storage, incluindo os diretórios de sessões, vistas e cache, se for o caso. bootstrap/cache pertence a cada release; não é uma subpasta de storage. Verifique que o utilizador que executa o PHP consegue escrever onde precisa, sem permissões 777.

Se o projeto precisar de assets compilados, incorpore o resultado no artefacto ou acrescente uma tarefa de compilação antes de publicar. As tarefas apresentadas não executam o npm. Se uma cache não for compatível com a sua aplicação, corrija a sua configuração ou adapte a tarefa depois de a testar.

Rever e executar a implementação

A partir do computador onde instalou o Deployer:

vendor/bin/dep deploy --plan pruebas

Reveja a ordem das tarefas e os hooks da versão instalada. O plano ajuda a detetar operações inesperadas, mas não verifica que o servidor ou a aplicação funcionam.

Quando o ambiente de testes estiver preparado:

vendor/bin/dep deploy pruebas

Verifique o resultado na saída e abra o site. Teste o acesso, uma página interna, os formulários, o carregamento de imagens e as operações com a base de dados. No Laravel, verifique também as tarefas agendadas e os processos em segundo plano que realmente utilize.

Se uma execução falhar, reveja a primeira tarefa com erro. Não desbloqueie a implementação enquanto outro processo continuar a trabalhar nem apague versões para libertar espaço sem identificar antes qual está ativa.

Migrações e passagem para produção

Uma nova versão pode exigir alterações de esquema. Planeie migrações compatíveis com o código que continua a atender pedidos durante a mudança. Se isso não for possível, utilize uma janela de manutenção e um procedimento de recuperação testado.

Não basta ordenar «primeiro o código e depois a base de dados»: depende da alteração. Também não deve acrescentar migrate:fresh, que elimina tabelas, à implementação de uma instalação com dados.

Antes de passar para produção, guarde uma cópia recuperável dos ficheiros e da base de dados, teste a receita e prepare a mudança da raiz do domínio. A primeira publicação não tem uma release anterior para a qual voltar.

Voltar a uma versão anterior

Se mantiver uma versão anterior compatível, pode ativar o rollback:

vendor/bin/dep rollback pruebas

Verifique depois o site e as suas operações principais. O rollback muda o código publicado; não recupera a base de dados nem devolve os ficheiros partilhados ao seu estado anterior. Uma migração ou um script que os tenha alterado exige o seu próprio procedimento de recuperação.

As releases guardadas consomem espaço e não substituem as cópias de segurança. Ajuste a sua retenção ao tamanho do projeto e à margem disponível para construir a versão seguinte.

Para aprofundar as tarefas disponíveis, consulte a receita do WordPress e a receita do Laravel correspondentes à versão que instalou. Num alojamento partilhado, utilize tarefas de implementação com o seu utilizador; as receitas para aprovisionar servidores exigem privilégios que essa conta não tem.