Como automatizar o deploy de filas e Background Workers do Laravel no Locaweb Cloud usando scripts Userdata

O processamento assíncrono é um pilar fundamental em arquiteturas de software modernas. Tarefas pesadas, como envio de emails em massa, geração de relatórios complexos ou processamento de imagens, não devem bloquear a requisição HTTP do usuário final. No ecossistema Laravel, esse desafio é resolvido através da funcionalidade de Queues (Filas) e Background Workers.

1. Pré-requisitos

Para que a sua estrutura seja implementada com sucesso, valide os seguintes pré-requisitos antes de avançar para o painel:

• Conta ativa no painel de controle do Locaweb Cloud (Apache CloudStack).
• Chave privada SSH (.key ou .pem) salva na sua máquina local com permissões restritas.
• Par de chaves SSH cadastrado no painel da Locaweb para vinculação à nova instância.
• Repositório Git da sua aplicação Laravel acessível (público ou com chave de deploy configurada).

[Importante!] Uma VM focada exclusivamente em Background Workers não serve tráfego web público. O único acesso externo necessário será o SSH (porta 22). A porta do seu banco de dados (MySQL, porta 3306) nunca deve ser exposta na internet; ela será acessada estritamente dentro da nossa rede privada.

Está com dúvidas sobre como começar no Locaweb Cloud? Acesse nosso tutorial de apoio. 

2. Configuração de infraestrutura (painel)

Antes de abrir o terminal, prepare a arquitetura de rede e registre o script de inicialização diretamente no painel do Locaweb Cloud.

Passo 1: Registrar o script Userdata

Como uma solução IaaS pura, a Locaweb não realiza instalação automática de frameworks por padrão. No entanto, o recurso de Userdata resolve isso: o hipervisor injeta um script no motor do Cloud-Init que roda como root na primeira inicialização da máquina, automatizando o ambiente.

1. No menu lateral esquerdo do painel, clique em Computação > Userdata > Registrar userdata.
2. Preencha os campos:
   • Nome: Setup-Laravel-Worker-Redis
   • Userdata: Deixe o campo pronto para colar o script Shell que detalharemos na próxima seção.
   • Codificado em Base64: Mantenha desmarcado (utilizaremos texto simples).

Passo 2: Alocar IP Público e Configurar Port Forwarding

1. Navegue até Rede > IPs Públicos e clique em Adquirir novo IP. Anote o endereço alocado.
2. Acesse a aba Encaminhamento de porta (Port Forwarding) deste IP e crie a regra de acesso administrativo:

Protocolo	Porta Pública	Porta Privada	VM de Destino	Finalidade
TCP	22	22	Sua VM de Workers	Acesso SSH Administrativo

 

Passo 3: Configurar as Regras de Firewall

Na aba Firewall do seu IP público, autorize a entrada do tráfego correspondente:

CIDR de Origem	Protocolo	Porta Inicial	Porta Final	Finalidade
<SEU_IP_LOCAL>/32	TCP	22	22	SSH restrito à sua rede de TI

 

3. Configuração de sistema (Userdata Script)

O script a seguir automatiza a preparação do sistema operacional. Copie o código abaixo, cole-o no campo Userdata do painel e salve:

Bash

#!/bin/bash

# 1. Atualização do índice de pacotes e do sistema

apt-get update -y && apt-get upgrade -y




# 2. Instalação de utilitários de sistema e repositórios necessários

apt-get install -y software-properties-common curl unzip git




# 3. Instalação do PHP 8.1 (CLI), Redis e Supervisor

apt-get install -y \

  php8.1-cli php8.1-mbstring php8.1-xml php8.1-bcmath php8.1-curl \

  php8.1-redis php8.1-mysql mysql-client redis-server supervisor




# 4. Instalação do Composer

curl -sS https://getcomposer.org/installer | php -- 
--install-dir=/usr/local/bin --filename=composer




# 5. Configuração automática do Supervisor para gerenciar as filas

cat <<'EOF' > /etc/supervisor/conf.d/laravel-worker.conf

[program:laravel-worker]

process_name=%(program_name)s_%(process_num)02d

command=php /var/www/html/app/artisan queue:work redis --sleep=3 
--tries=3 --max-time=3600

autostart=true

autorestart=true

stopasgroup=true

killasgroup=true

user=www-data

numprocs=4

redirect_stderr=true

stdout_logfile=/var/log/laravel-worker.log

stopwaitsecs=3600

EOF




# 6. Inicialização dos serviços e recarga do Supervisor

systemctl enable redis-server && systemctl start redis-server

systemctl enable supervisor && systemctl start supervisor

supervisorctl reread && supervisorctl update

 

4. Lançando a máquina virtual com o Userdata

1. No painel, acesse Computação > VMs > Adicionar VM e selecione o template Ubuntu 22.04 LTS.
2. Ative a chave de alternância Modo Avançado.
3. Na seção Userdata registrado, selecione o script que salvamos (Setup-Laravel-Worker-Redis).
4. Vincule seu par de chaves SSH e clique em Executar VM.

 

5. Configuração do banco de dados: MySQL

Escolha o cenário de banco de dados que melhor se adapta à topologia do seu projeto:

Cenário A: MySQL na mesma VM (Ambientes Simples)

Conecte-se à VM via SSH e instale o banco de dados:

Bash

sudo apt-get install -y mysql-server

sudo systemctl enable --now mysql

sudo mysql_secure_installation

Acesse o console administrativo e crie a base restrita ao localhost:

Bash

sudo mysql

SQL

CREATE DATABASE laravel_app CHARACTER SET utf8mb4 COLLATE 
utf8mb4_unicode_ci;

CREATE USER 'laravel_user'@'localhost' IDENTIFIED BY 
'TroqueEstaSenhaForte123!';

GRANT ALL PRIVILEGES ON laravel_app.* TO 'laravel_user'@'localhost';

FLUSH PRIVILEGES;

EXIT;

Cenário B: MySQL em VM Dedicada (Ambientes VPC)

Na instância isolada de banco, configure o arquivo de rede para escutar o IP privado da sub-rede:

Bash

sudo nano /etc/mysql/mysql.conf.d/mysqld.cnf

# Ajuste o bind-address com o IP privado do banco, 
ex: bind-address = 10.0.2.10

Abra o console SQL e restrinja o acesso do usuário à sub-rede privada da aplicação:

SQL

CREATE DATABASE laravel_app CHARACTER SET utf8mb4 COLLATE 
utf8mb4_unicode_ci;

CREATE USER 'laravel_user'@'10.0.1.%' IDENTIFIED BY 
'TroqueEstaSenhaForte123!';

GRANT ALL PRIVILEGES ON laravel_app.* TO 'laravel_user'@'10.0.1.%';

FLUSH PRIVILEGES;

EXIT;

Bash

sudo systemctl restart mysql

6. Deploy da aplicação 

O arquivo .env da aplicação clonada deve ser parametrizado com o driver apontando para o Redis:

Ini, TOML

DB_CONNECTION=mysql

DB_HOST=127.0.0.1          # Use o IP 10.0.2.10 caso utilize o 
Cenário B

DB_PORT=3306

DB_DATABASE=laravel_app

DB_USERNAME=laravel_user

DB_PASSWORD=TroqueEstaSenhaForte123!




QUEUE_CONNECTION=redis

REDIS_HOST=127.0.0.1

REDIS_PORT=6379

Método 1: Deploy manual via Git

Acesse a instância via SSH e prepare o diretório do código-fonte:

Bash

sudo mkdir -p /var/www/html

sudo git clone https://github.com/<SUA_ORG>/<SEU_REPO>.git 
/var/www/html/app

cd /var/www/html/app




# Instala dependências de produção otimizando o autoloader

sudo composer install --no-dev --optimize-autoloader

sudo cp .env.example .env

sudo php artisan key:generate

sudo php artisan migrate --force




# Ajusta a propriedade da pasta para os workers operarem

sudo chown -R www-data:www-data /var/www/html/app

Método 2: Deploy automatizado (GitHub Actions)

Você pode configurar uma esteira automatizada no Git utilizando os Secrets de conexão SSH (SSH_HOST, SSH_USER, SSH_KEY). Salve o arquivo .github/workflows/deploy.yml para disparar as atualizações a cada push:

YAML

name: Deploy Laravel Workers




on:

  push:

    branches: [ main ]




jobs:

  deploy:

    runs-on: ubuntu-latest

    steps:

      - name: Conectar via SSH e atualizar a aplicação

        uses: appleboy/ssh-action@v1.0.3

        with:

          host: ${{ secrets.SSH_HOST }}

          username: ${{ secrets.SSH_USER }}

          key: ${{ secrets.SSH_KEY }}

          script: |

            cd /var/www/html/app

            git pull origin main

            composer install --no-dev --optimize-autoloader

            php artisan migrate --force

            php artisan config:cache

            sudo supervisorctl restart laravel-worker:*

7. Validação

Testes de comunicação e serviços

Conecte-se à VM por SSH utilizando o terminal local para validar a saúde dos daemons:

Bash

chmod 400 ~/.ssh/sua-chave.key

ssh -i ~/.ssh/sua-chave.key root@<SEU_IP_PUBLICO>

 

Valide se o Message Broker (Redis) está respondendo perfeitamente na instância interna:

Bash

systemctl status redis-server

redis-cli ping

# Deve retornar "PONG"

Mapeamento do Supervisor

Monitore o status operacional das filas gerenciadas pelo Supervisor:

Bash

supervisorctl status

Bash

# Inicializa o grupo de workers cadastrado

supervisorctl start laravel-worker:*

Acompanhe o processamento de jobs e o fluxo de tarefas em tempo real consumindo os logs de saída do sistema:

Bash

tail -f /var/log/laravel-worker.log

8. Solução de problemas (Troubleshooting)

• Workers permanecem em estado FATAL após o deploy: Certifique-se de que o arquivo /var/www/html/app/artisan possui permissões de execução e que você rodou o comando composer install para baixar os pacotes do framework.
• Jobs acumulados na tabela (Tráfego não processado): Verifique se a variável QUEUE_CONNECTION=redis está configurada corretamente no seu arquivo .env e limpe o cache de configurações rodando php artisan config:clear.
• Acesso SSH administrativo recusado por timeout: Acesse o painel CloudStack na aba de IPs Públicos e certifique-se de que a porta pública 22 está mapeada via Port Forwarding e liberada no Firewall para o seu CIDR local.