Instalar o Laravel num alojamento com cPanel (Laravel 13 e 12)

Pode instalar o Laravel num alojamento com cPanel utilizando o Composer e o acesso SSH. Neste guia, vamos criar um projeto novo, preparar a sua base de dados, configurar o domínio para que publique apenas a pasta public e deixar prontas as peças de que uma aplicação em produção costuma precisar: scheduler, filas, sessões, cache e, se for preciso, Horizon e WebSockets.

Se já tem uma aplicação num repositório, não precisa de criar outra: ligue o repositório ao Deploy+ e siga este guia a partir da secção da base de dados.

1. Escolha a versão do PHP e verifique a do terminal

O Laravel 13 precisa do PHP 8.3 ou superior, e o Laravel 12 do PHP 8.2 ou superior, sempre dentro do que as suas dependências suportarem. A versão do site escolhe-se no seletor de PHP; num site publicado com o Deploy+, fixa-se no .htaccess do seu repositório, como explicamos em versão do PHP com o Deploy+.

Abra o SSH ou o terminal do cPanel e verifique que versão os comandos executam:

php -v
composer --version

O php do terminal nem sempre é a versão do seu site: já vimos contas em que respondia o PHP 8.1 com o seletor em 8.4. Se não coincidir, chame o binário da sua versão pelo seu caminho completo, por exemplo /opt/alt/php84/usr/bin/php artisan migrate, e execute o Composer com ele:

/opt/alt/php84/usr/bin/php "$(command -v composer)" install

No resto do guia escrevemos php para abreviar: substitua-o pelo caminho completo se o seu terminal der outra versão. No cron e nos processos persistentes, utilize sempre o caminho completo.

Os requisitos do Laravel incluem Ctype, cURL, DOM, Fileinfo, Filter, Hash, Mbstring, OpenSSL, PCRE, PDO, Session, Tokenizer e XML; a base de dados escolhida exige também o seu controlador PHP. As extensões ativam-se por versão: se o Composer indicar ext-fileinfo is missing, ative-a na versão que executa o comando. Não ignore as verificações com --ignore-platform-reqs: instalar dependências incompatíveis não fará a aplicação funcionar.

Os valores de cada versão, como memory_limit, max_execution_time, upload_max_filesize ou max_input_vars, também se ajustam ao que a sua aplicação precisar: no separador Limites da ficha do site na área de cliente ou em Options no seletor do cPanel, como explica PHP, selecionar versão, módulos e configuração. max_execution_time só limita os pedidos web: o Artisan, o scheduler e os workers não têm esse tempo máximo.

2. Crie o projeto fora do diretório público

A partir da raiz da sua conta, crie uma pasta nova que ainda não exista:

cd ~
composer create-project laravel/laravel mi-proyecto "^13.0"
cd mi-proyecto
php artisan --version
composer check-platform-reqs

A verificação do Artisan deve identificar o Laravel 13; a do Composer, confirmar os requisitos do ambiente. Não execute create-project sobre um site existente.

Se a aplicação ou uma integração exigir o Laravel 12, utilize outra pasta nova com composer create-project laravel/laravel mi-proyecto-12 "^12.0". O seu calendário oficial mantém as correções de segurança até 24 de fevereiro de 2027; consulte a política de suporte do Laravel ao escolher a versão. Para um projeto que já existe, utilize o seu composer.lock com composer install; não o substitua por uma instalação nova nem mude de versão principal sem rever a atualização.

Se preferir um starter kit (React, Vue, Svelte ou Livewire), instale o instalador oficial com composer global require laravel/installer, adicione ao PATH o caminho devolvido por composer global config bin-dir --absolute e utilize laravel new otro-proyecto numa pasta nova. Consulte laravel new --help antes de automatizar opções.

3. Configure a base de dados

Uma instalação nova pode começar com SQLite, se o PHP tiver o respetivo controlador. Para utilizar MySQL, crie a base de dados e o seu utilizador no assistente de bases de dados do cPanel. Se implementar com o Deploy+, este pode criar a base de dados e escrever a ligação no .env ao ligar o repositório.

Edite o .env dentro do projeto com os dados reais dessa base de dados:

DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=miusuario_proyecto
DB_USERNAME=miusuario_app
DB_PASSWORD="sustituye_por_la_clave_de_la_base"

Utilize os nomes completos que o cPanel mostra, incluindo o prefixo. Não publique o .env nem o envie para o repositório. No projeto novo, execute:

php artisan config:clear
php artisan migrate

Se estiver a implementar uma aplicação com dados existentes, reveja as migrações e guarde uma cópia antes de as aplicar. Não utilize migrate:fresh: elimina as tabelas.

4. Publique só a pasta public

O domínio deve servir /home/tu_usuario/mi-proyecto/public, não /home/tu_usuario/mi-proyecto. Assim, os ficheiros de configuração e o código privado ficam fora da raiz web.

Para um domínio adicional ou subdomínio, reveja o seu diretório em cPanel > Domains > Manage e, se a configuração o permitir, selecione a pasta public do projeto. Não mova index.php para a raiz para evitar este passo.

No domínio principal, o cPanel normalmente utiliza public_html. Se precisar de substituir esse diretório por uma ligação para o public do Laravel, planeie antes o que contém, a sua cópia e o regresso atrás; não mude o nome nem apague public_html sem verificar se já aloja um site ou outros domínios. Com o Deploy+, o perfil Laravel publica a pasta public do repositório na pasta que escolher, que tem de estar vazia na primeira implementação.

5. Prepare e verifique a aplicação

No .env, configure o URL real e desative a depuração pública:

APP_ENV=production
APP_DEBUG=false
APP_URL=https://oseudominio.com

A instalação deve ter uma chave APP_KEY. Num projeto novo sem chave, gere uma com php artisan key:generate. Não a regenere numa aplicação existente: poderia deixar inacessíveis dados cifrados.

Se o seu projeto utilizar o Vite, compile os seus recursos com uma versão do Node.js compatível com o seu package.json: npm install e npm run build numa instalação nova; npm ci e npm run build em implementações com package-lock.json. O Node.js está no Gestor de pacotes e serve para compilar; consulte Node.js para compilar assets.

Verifique que storage e bootstrap/cache podem ser escritos pela aplicação, sem aplicar permissões 777 de forma geral, e execute php artisan optimize.

Abra o domínio por HTTPS e verifique a página inicial, as rotas interiores e as funções que consultam a base de dados. Verifique também que /.env não entrega o ficheiro. Se aparecer um erro 500, consulte storage/logs/laravel.log e os registos do alojamento; não ative a depuração pública para mostrar o erro a todos os visitantes.

6. Agende o scheduler

Se publicar o projeto com o Deploy+, o assistente faz isso por si: deixe marcado Agendar o scheduler do Laravel e a tarefa é adicionada no fim da primeira implementação, como explicamos em Deploy+. Verifique-a na mesma com php artisan schedule:list.

Caso contrário, em cPanel > Cron Jobs, adicione uma tarefa que seja executada a cada minuto com o PHP da sua aplicação:

* * * * * /opt/alt/php84/usr/bin/php /home/tu_usuario/mi-proyecto/artisan schedule:run > /dev/null 2>&1

Mude php84 para a sua versão e o caminho para o do seu projeto; com o Deploy+ é /home/tu_usuario/deploy/nombre-repo/current/artisan. Não utilize /usr/local/bin/php nem o php sem caminho: podem ser outra versão do PHP, com outras extensões, e o scheduler lança as tarefas agendadas com o mesmo PHP com que arranca.

Antes de a deixar ativa, execute esse mesmo comando à mão, sem descartar a saída, e reveja php artisan schedule:list. Tem mais detalhes sobre o cron em tarefas cron no cPanel.

7. Filas

Desde o Laravel 11, um projeto novo guarda os trabalhos na base de dados (QUEUE_CONNECTION=database). Num projeto anterior, crie primeiro a tabela com php artisan queue:table e migre. O que muda consoante o seu plano é quem os processa.

Com processos persistentes (Avanza, Max e Elastic)

Crie um Worker de filas em Ferramentas > Processos, com a pasta da aplicação e a sua versão do PHP. Fica em execução, processa cada trabalho assim que chega e volta a arrancar sozinho se cair. Ao publicar uma versão com o Deploy+, reinicia-se sozinho para apanhar o código novo. Todos os detalhes estão em processos persistentes.

Sem processos persistentes

Em qualquer plano, o scheduler pode lançar a cada minuto um worker que processa o que está pendente e termina. Em routes/console.php:

use Illuminate\Support\Facades\Schedule;

Schedule::command('queue:work --stop-when-empty --tries=3 --max-time=300')
    ->everyMinute()
    ->withoutOverlapping(10)
    ->runInBackground();

withoutOverlapping(10) evita que dois workers se juntem e liberta o bloqueio ao fim de 10 minutos se um for interrompido a meio; runInBackground() deixa que as restantes tarefas agendadas sejam executadas à sua hora. Um trabalho pode esperar até um minuto antes de ser processado.

Se preferir não depender do scheduler, uma tarefa cron com flock faz o mesmo sem sobreposições:

* * * * * cd /home/tu_usuario/mi-proyecto && /usr/bin/flock -n /home/tu_usuario/.cola-mi-proyecto.lock /opt/alt/php84/usr/bin/php artisan queue:work --stop-when-empty --max-time=300 > /dev/null 2>&1

Em ambos os casos, reveja os trabalhos falhados com php artisan queue:failed.

8. Sessões, cache e Redis

Onde guardar cada coisa:

• Sessões: na base de dados (SESSION_DRIVER=database) em qualquer plano; a partir do Avanza, também no Redis persistente (redis).
• Filas: na base de dados (QUEUE_CONNECTION=database) em qualquer plano; a partir do Avanza, também no Redis persistente (redis).
• Cache: na base de dados (CACHE_STORE=database) ou no Redis Cache, em qualquer plano.
• Horizon: só com o Redis persistente, a partir do Avanza.

Os dois Redis não servem para o mesmo:

• O Redis Cache, em todos os planos, é só cache: começa vazio ao reiniciar e descarta chaves quando fica cheio. Utilize-o para CACHE_STORE=redis e nunca para sessões nem filas. Configuração em Redis como cache de objetos.
• O Redis persistente, a partir do Avanza, guarda os seus dados em disco e não os descarta: é o sítio para filas, sessões e Horizon. Ativa-se no Gestor de pacotes e liga-se através de um socket da sua conta. Configuração em Redis persistente.

Pode utilizar os dois ao mesmo tempo: a cache no Redis Cache e as filas e sessões no Redis persistente. As sessões na base de dados são a opção predefinida desde o Laravel 11 e servem em qualquer plano; num projeto anterior, crie a sua tabela com php artisan session:table.

9. Horizon

O Horizon precisa de filas em Redis e de um processo em execução, por isso funciona a partir do plano Avanza: ative o Redis persistente, defina QUEUE_CONNECTION=redis, instale laravel/horizon e crie um processo persistente do tipo Horizon. Ajuste maxProcesses em config/horizon.php aos recursos do seu plano. Com o Deploy+, o Horizon reinicia-se sozinho depois de ativar cada versão; se publicar de outra forma, execute php artisan horizon:terminate quando o código novo já estiver no sítio. Os passos estão em Redis persistente para filas, sessões e Horizon.

O Horizon sobre o Redis Cache não é seguro: se essa cache for esvaziada ou ficar cheia, perdem-se trabalhos.

10. Broadcasting e WebSockets

Não oferecemos o Reverb no alojamento: é um servidor que escuta na sua própria porta, e não damos suporte a programas assim, como explicamos em processos persistentes. Para notificações e eventos em tempo real, ligue a sua aplicação a um serviço compatível com o protocolo do Pusher, como o Pusher Channels ou o Ably, que o Laravel suporta de origem. A sua aplicação só faz pedidos HTTPS de saída e os navegadores ligam-se ao serviço. Comparação e configuração em WebSockets no Laravel.

O que não se adequa ao alojamento

• Octane: aqui o PHP é servido pelo LiteSpeed, e o Octane precisa do seu próprio servidor de aplicação à frente (Swoole, RoadRunner ou FrankenPHP).
• Reverb ou outro servidor de WebSockets próprio: utilize um serviço compatível com Pusher.
• Node.js como servidor: o Node existe para compilar assets. O SSR do Inertia precisa de um servidor Node em execução; sem ele, o Inertia renderiza no navegador como sempre.
• Serviços do sistema ou acesso root. Se o seu projeto precisar deles, conte-nos o caso antes de contratar.

Livewire, Inertia, Filament, Sanctum, Socialite ou Scout funcionam sem nada de especial.

Publicar as alterações seguintes com o Deploy+

Quando o projeto estiver no Git, o Deploy+ publica cada versão na sua própria pasta, com ficheiros partilhados e versões para as quais pode voltar. Um script de implementação para Laravel:

composer install --no-dev --optimize-autoloader --no-interaction
php artisan migrate --force
php artisan optimize

Se compilar assets, adicione as linhas de npm indicadas no guia do Deploy+. Não é necessário queue:restart nem horizon:terminate: depois de ativar cada versão, e também ao voltar a uma anterior, o Deploy+ reinicia os processos persistentes da aplicação. Uma reversão de código não desfaz automaticamente as alterações à base de dados: desenhe as migrações tendo em conta essa diferença.

O script recomendado, os processos que o alojamento suporta e a comparação com um VPS estão resumidos em alojamento para Laravel com o Deploy+.

Referências: instalação do Laravel, filas e recomendações de implementação.