Ao rodar aplicaƧƵes Laravel em containers Docker, o gerenciamento de processos em segundo plano, como filas e cron jobs, exige uma ferramenta robusta. O Supervisor Ć© a soluĆ§Ć£o ideal, mas sua configuraĆ§Ć£o no ambiente Docker requer atenĆ§Ć£o especial Ć s permissƵes e caminhos.

Este artigo apresenta um modelo de Dockerfile e arquivos de configuraĆ§Ć£o para instalar e configurar o Supervisor em uma imagem base RHEL/CentOS/Rocky Linux, garantindo que seus workers do Laravel sejam gerenciados corretamente.

1ļøāƒ£ Estrutura de Arquivos Link para o cabeƧalho

Para este setup, vocĆŖ precisarĆ” dos seguintes arquivos no diretĆ³rio raiz do seu projeto antes de construir a imagem:

  • Dockerfile
  • supervisord.conf (ConfiguraĆ§Ć£o principal do Supervisor)
  • laravel-worker.conf (ConfiguraĆ§Ć£o do grupo de workers do Laravel)

2ļøāƒ£ O Dockerfile: InstalaĆ§Ć£o e ConfiguraĆ§Ć£o Link para o cabeƧalho

O Dockerfile Ć© o coraĆ§Ć£o da nossa imagem. Ele Ć© responsĆ”vel por instalar o Supervisor e definir os usuĆ”rios e permissƵes corretas.

# Usa uma imagem base RHEL 8 ou similar
# Exemplo: rockylinux:8, centos:8, ou uma base slim
FROM rockylinux:8 as base


# Define variƔveis de ambiente
ENV APP_PATH=/app


# -----------------------------------------------------------
# InstalaĆ§Ć£o de DependĆŖncias
# -----------------------------------------------------------
RUN dnf update -y && \
    # Instala o EPEL (geralmente necessƔrio para o Supervisor)
    dnf install epel-release -y && \
    # Instala o Supervisor
    dnf install supervisor -y && \
    # Limpa o cache para reduzir o tamanho da imagem
    dnf clean all


# -----------------------------------------------------------
# ConfiguraĆ§Ć£o de UsuĆ”rio e DiretĆ³rios
# -----------------------------------------------------------


# Cria o usuĆ”rio 'nginx' (ou 'www-data', dependendo da sua base) que o PHP-FPM e os workers usarĆ£o
# Ɖ crucial que o usuĆ”rio que executa o 'artisan' tenha as permissƵes corretas.
RUN groupadd -g 1000 nginx && \
    useradd -u 1000 -ms /bin/bash -g nginx nginx


# Cria diretĆ³rios necessĆ”rios para logs e configuraƧƵes do Supervisor
RUN mkdir -p /var/log/supervisor /etc/supervisord.d


# Define o diretĆ³rio de trabalho da aplicaĆ§Ć£o
WORKDIR ${APP_PATH}


# Copia a aplicaĆ§Ć£o Laravel
COPY . ${APP_PATH}


# -----------------------------------------------------------
# PermissƵes e InclusĆ£o de Configs
# -----------------------------------------------------------


# Copia os arquivos de configuraĆ§Ć£o do Supervisor para os locais esperados
COPY supervisord.conf /etc/supervisord.conf
COPY laravel-worker.conf /etc/supervisord.d/


# Define a propriedade da aplicaĆ§Ć£o e dos logs para o usuĆ”rio nĆ£o-root
RUN chown -R nginx:nginx ${APP_PATH} \
    && chown -R nginx:nginx /var/log/supervisor \
    && chmod -R 775 /var/log/supervisor


# Define o usuƔrio que executarƔ a maioria dos comandos (workers PHP)
USER nginx


# -----------------------------------------------------------
# Comando de InicializaĆ§Ć£o
# -----------------------------------------------------------


# O comando principal que inicia o Supervisor em modo non-daemon (-n)
# O Supervisor irƔ gerenciar o PHP-FPM e os workers definidos nas configuraƧƵes.
CMD ["/usr/bin/supervisord", "-c", "/etc/supervisord.conf", "-n"]

3ļøāƒ£ Arquivos de ConfiguraĆ§Ć£o do Supervisor Link para o cabeƧalho

3.1 supervisord.conf (ConfiguraĆ§Ć£o Principal) Link para o cabeƧalho

Este arquivo Ʃ responsƔvel por iniciar o Supervisor e incluir as configuraƧƵes especƭficas dos seus programas.

[supervisord]
; O daemon principal roda como 'root' para ter controle total sobre o gerenciamento de processos.
user=root
logfile=/var/log/supervisor/supervisord.log 
pidfile=/var/run/supervisord.pid


; Inclui todas as configuraƧƵes dos workers do Laravel
[include]
files = /etc/supervisord.d/*.conf

3.2 laravel-worker.conf (DefiniĆ§Ć£o do Programa) Link para o cabeƧalho

Aqui definimos o seu worker de fila, garantindo que ele rode sob o usuĆ”rio nĆ£o-root (nginx) e que o Supervisor gerencie seus restarts.

[program:laravel_worker_group_name]
; % (process_num)02d garante que cada worker tenha um nome Ćŗnico (ex: group_name_00, group_name_01)
process_name=%(program_name)s_%(process_num)02d
; Substitua 'kafka:consume --queue=cfm_kafka' pelo comando real do seu worker
command=php /app/artisan queue:work --tries=3 --timeout=3600
numprocs=2                                ; Quantidade de processos a manter rodando
autostart=true
autorestart=true
user=nginx                                ; ā¬…ļø IMPORTANTE: Define o usuĆ”rio que executa o processo PHP
redirect_stderr=true
stdout_logfile=/app/storage/logs/supervisor_worker.log

4ļøāƒ£ Comandos Essenciais para Gerenciamento Docker šŸš€ Link para o cabeƧalho

Para construir, subir e gerenciar seu container, utilize os seguintes comandos no seu terminal (na pasta onde reside o Dockerfile):

AĆ§Ć£o Comando Docker (Usando php74 como nome da imagem) ObservaƧƵes
1. Construir/Reconstruir a Imagem docker build -t php74 . O -t php74 define o nome da sua imagem. O . indica que o Dockerfile estĆ” no diretĆ³rio atual. Essencial apĆ³s qualquer ajuste no Dockerfile ou na configuraĆ§Ć£o do Supervisor.
2. Subir o Container docker run -d --name php74 -p 9000:9000 php74 O -d roda em modo detached (segundo plano). O --name php74 define o nome do container (usado no docker exec).
3. Parar o Container docker stop php74 Para o container de forma segura.
4. Iniciar o Container Parado docker start php74 Inicia um container que foi parado anteriormente.
5. Destruir/Remover o Container docker rm php74 Remove o container. Use apĆ³s o stop. NecessĆ”rio antes de subir um novo com o mesmo nome.

5ļøāƒ£ ConsideraƧƵes Finais sobre PermissƵes Link para o cabeƧalho

Com esta configuraĆ§Ć£o, o seu comando Artisan personalizado (php artisan supervisor:restart nome_do_grupo) executado via docker exec poderĆ” interagir diretamente com o supervisorctl para gerenciar seus workers de forma eficaz, pois o usuĆ”rio que executa o docker exec (geralmente root) tem controle sobre o processo Supervisor.