📝 Artisan: Reiniciando Workers do Supervisor no Laravel via docker

Este guia detalha a criação de um comando personalizado no Laravel, que permite reiniciar workers específicos do Supervisor de forma rápida e segura, mesmo quando a aplicação roda em um container Docker. Incluímos também dicas essenciais para diagnóstico de permissões.

1️⃣ Passo 1: Criação do Comando Artisan Link para o cabeçalho

Vamos criar um comando que servirá como um wrapper para o utilitário de sistema supervisorctl.

1.1 Gerando a Classe Link para o cabeçalho

Use o Artisan para gerar a estrutura inicial do comando:

php artisan make:command SupervisorRestart --command=supervisor:restart

1.2 Implementando a Lógica (Com Ajustes Docker) Link para o cabeçalho

Crie o arquivo app/Console/Commands/SupervisorRestart.php. A chave é usar shell_exec para interagir com o sistema operacional do container.

Devido ao ambiente Docker, onde o binário do supervisorctl pode não estar no PATH padrão e o sudo geralmente está ausente, usaremos o caminho absoluto para o supervisorctl (/usr/bin/supervisorctl) e adicionaremos um curinga (:*) por segurança, para cobrir grupos de processos.

<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;

class SupervisorRestart extends Command
{
    protected $signature = 'supervisor:restart {program : O nome do grupo de processos do Supervisor para reiniciar.}';
    protected $description = 'Reinicia um programa ou grupo de processos específico do Supervisor no container.';

    public function handle()
    {
        $program = $this->argument('program');

        // Adiciona ':*' ao nome do programa, caso não exista, para garantir que todos
        // os workers do grupo sejam reiniciados.
        if (!str_ends_with($program, ':*')) {
            $program .= ':*';
        }

        // Usamos o caminho absoluto e removemos 'sudo', pois a execução geralmente é feita por
        // um usuário com permissão direta (ex: root ou www-data) dentro do container.
        $command = "/usr/bin/supervisorctl restart " . escapeshellarg($program);

        $this->info("Tentando reiniciar o grupo Supervisor: {$program}...");
        
        $output = shell_exec($command);

        if (str_contains($output, 'ERROR') || is_null($output)) {
            $this->error("Falha ao reiniciar o programa '{$program}'. Verifique se o nome do grupo está correto.");
            $this->error($output ?? 'Nenhuma saída de erro do shell (possível falha de permissão/PATH).');
            return 1;
        }

        $this->info("Grupo '{$program}' do Supervisor reiniciado com sucesso.");
        $this->line(trim($output)); // O trim é usado para evitar erros de formatação (TypeError)
        
        return 0;
    }
}

2️⃣ Passo 2: Execução e Diagnóstico em Containers Docker Link para o cabeçalho

O comando agora pode ser executado diretamente da sua máquina host, sem precisar entrar no container.

2.1 Executando o Comando Link para o cabeçalho

Execute o comando usando o docker exec, substituindo php74 pelo nome do seu container e laravel_worker pelo nome do seu grupo de processos:

docker exec php74 php /app/artisan supervisor:restart laravel_worker

2.2 Dica de Diagnóstico: Qual Usuário Executa o PHP? 🛡️ Link para o cabeçalho

Erros de permissão (Permission denied ou command not found para o supervisorctl) geralmente indicam que o usuário que executa o php artisan não tem acesso.

Para checar qual usuário está executando o PHP dentro do container (o usuário responsável por rodar o artisan), utilize o docker exec para rodar o comando ps aux e filtre por php através do shell do próprio container:

docker exec php74 sh -c "ps aux | grep php"

• Se o usuário for root (como na linha do php artisan), as permissões geralmente não são um problema.

• Se o usuário for nginx ou www-data, certifique-se de que o supervisord também esteja rodando sob esse mesmo usuário ou que ele tenha as permissões de leitura/execução necessárias para o supervisorctl e seus arquivos de configuração.

3️⃣ Passo 3: Solução de Erro Comum (ERROR (no such process)) Link para o cabeçalho

Se, mesmo após usar o supervisor:restart laravel_worker, você ainda vir o erro ERROR (no such process) na saída, isso indica que o Supervisor não reconhece o nome do grupo.

Execute o seguinte comando para ver a lista exata de nomes de processos que o Supervisor está gerenciando:

docker exec php74 supervisorctl status

Ajuste o nome do programa no seu comando Artisan para corresponder exatamente ao que aparece no status do supervisorctl. Se o nome for, por exemplo, my_group:my_group_00, você deve usar my_group:* no seu comando Artisan.

Com este comando Artisan, você ganha uma maneira conveniente e padronizada de gerenciar seus workers do Laravel, simplificando o processo de deployment e manutenção em ambientes Docker.