README

Executor de deploy simples para aplicações Laravel em servidores Linux.

Instalação

composer require dougkusanagi/laravel-deploy:^0.4
vendor/bin/deploy init

Se o pacote ainda não estiver disponível no Packagist, registre o repositório do GitHub antes de instalar:

composer config repositories.laravel-deploy vcs https://github.com/dougkusanagi/laravel-deploy.git
composer require dougkusanagi/laravel-deploy:^0.4

Edite deploy.config.sh e execute:

vendor/bin/deploy

Use vendor/bin/deploy --force para repetir todas as etapas mesmo quando o commit atual já tiver sido implantado com sucesso.

O pacote também aceita ./deploy.sh quando o projeto mantém um wrapper na raiz.

Configuração

deploy.config.sh é um arquivo Bash confiável carregado antes da atualização do Git. A configuração mínima é:

DEPLOY_BRANCH="${DEPLOY_BRANCH:-main}"
PHP_FPM_SERVICE="${PHP_FPM_SERVICE-php8.5-fpm}"
PHP_FPM_ACTION="${PHP_FPM_ACTION:-reload}"
WEB_SERVICE="${WEB_SERVICE-}"
HORIZON="${HORIZON:-false}"
QUEUE_RESTART="${QUEUE_RESTART:-false}"
STORAGE_LINK="${STORAGE_LINK:-true}"
ALLOW_DIRTY_WORKTREE="${ALLOW_DIRTY_WORKTREE:-false}"
FRONTEND_INSTALL=(npm ci)
FRONTEND_BUILD=(npm run build)

Defina os arrays de frontend como vazios para desativar essas etapas:

FRONTEND_INSTALL=()
FRONTEND_BUILD=()

PHP_FPM_SERVICE e WEB_SERVICE são opcionais. O executor não tenta detectar nem recarregar automaticamente Caddy ou Nginx. Quando PHP-FPM estiver configurado, PHP_FPM_ACTION aceita reload (padrão) ou restart.

Defina HORIZON=true em aplicações que usam Horizon. Isso executa horizon:terminate depois da reconstrução dos caches para que o gerenciador de processos inicie o Horizon com o código novo. A instalação e a publicação da configuração do Horizon devem ser feitas durante a preparação da aplicação, não em cada deploy.

Para workers Laravel comuns, defina QUEUE_RESTART=true. O executor chamará queue:restart no mesmo ponto. HORIZON e QUEUE_RESTART são mutuamente exclusivos e o padrão é não reiniciar nenhum worker. Em ambos os casos, os processos devem ser mantidos por Supervisor, systemd ou outro gerenciador.

Por segurança, alterações locais em arquivos rastreados bloqueiam o deploy. Arquivos não rastreados, como .env, continuam permitidos. Defina ALLOW_DIRTY_WORKTREE=true apenas quando esse comportamento for intencional.

Também é possível usar FORCE_DEPLOY=true em automações. DEPLOY_LOCK_FILE e DEPLOY_STATE_FILE permitem alterar os arquivos internos de lock e estado, armazenados dentro de .git por padrão.

Etapas

O executor impede dois deploys simultâneos, valida a árvore de trabalho, busca o remoto uma única vez e atualiza a branch apenas por fast-forward. Depois instala dependências PHP sem dev, executa as etapas de frontend, roda migrations isoladas, cria o link de storage, recria caches, atualiza os serviços configurados e verifica a inicialização do Laravel. HEALTHCHECK_URL adiciona uma verificação HTTP.

Ao final, o commit é registrado como implantado com sucesso. Execuções seguintes desse mesmo commit atualizam o Git, mas pulam Composer, frontend, migrations, caches e serviços. Se qualquer etapa falhar, o commit não é registrado e a próxima execução tenta completar o deploy novamente. Mudanças de configuração ou de ambiente sem um commit novo devem ser aplicadas com --force.

O commit implantado precisa existir em origin/DEPLOY_BRANCH. Commits criados somente no servidor bloqueiam o fluxo para evitar publicar código não revisado.

O deploy altera o diretório atual da aplicação. Falhas não desfazem arquivos ou migrations já aplicados, mas uma nova execução retoma as etapas para o mesmo commit.

Requisitos

• Linux com Bash e flock;
• Git e um remote chamado origin;
• PHP e Composer;
• Node/npm ou outra ferramenta configurada nos arrays de frontend;
• sudo e systemctl quando serviços forem configurados.