Ambientes e infraestrutura

Esta página descreve os processos necessários para executar o SteerCrew. Docker, provedor de nuvem e supervisor são escolhas de hospedagem; Laravel, banco, fila, scheduler e armazenamento são requisitos da aplicação.

Componentes

Componente	Responsabilidade	Obrigatório em produção
Aplicação web	Laravel, Inertia, autenticação, portal, APIs e webhooks	Sim
PostgreSQL	Dados das empresas, operação, flows e filas persistidas	Sim na arquitetura atual
Redis	Cache, sessão e fila na configuração recomendada	Sim quando esses drivers são redis
Worker	Consome events, whatsapp, workflows e default	Sim
Scheduler	Dispara agenda de flows, esperas e retenção	Sim
Reverb	Atualização em tempo real de conversas e execuções	Condicional; recomendado
Armazenamento	Fotos e anexos no disco público persistente	Sim
E-mail	Verificação de conta e notificações do framework	Condicional ao uso
Nginx/proxy	HTTPS, arquivos estáticos e encaminhamento para PHP/Reverb	Recomendado
Wiki VitePress	Documentação pública hospedada separadamente	Sim para publicar esta documentação

Ambientes

Desenvolvimento local

O repositório oferece Docker Compose com aplicação, Nginx, PostgreSQL, Redis, worker, scheduler, Reverb e Mailpit.

make up
make migrate

Depois valide:

• app em http://localhost:8081;
• wiki em seu próprio servidor local depois de npm run dev no repositório steercrew-docs;
• Mailpit em http://localhost:8025;
• websocket local exposto na porta 8082.

As senhas e chaves presentes no Compose e em .env.example são conveniências locais. Não as reutilize fora da máquina de desenvolvimento.

Homologação

Homologação deve reproduzir produção: HTTPS, banco isolado, Redis, worker, scheduler, armazenamento e Reverb. Use domínio, credenciais e contas Meta próprios. Nunca conecte o número oficial do cliente nem envie e-mail real antes do aceite.

Produção

Em produção:

1. Defina APP_ENV=production, APP_DEBUG=false e uma APP_KEY exclusiva.
2. Termine TLS no proxy e configure APP_URL com HTTPS.
3. Use banco, Redis e o volume público de arquivos persistentes com backup.
4. Execute migrações de forma controlada.
5. Mantenha web, worker, scheduler e Reverb sob reinício automático.
6. Gere os assets do app e da wiki em seus respectivos repositórios com npm run build.
7. Configure SMTP e Meta somente com segredos do ambiente.
8. Monitore logs, fila com falha, espaço, saúde do banco e expiração de tokens.

Processos de longa duração

Exemplos mínimos fora do Docker:

php artisan queue:work --queue=events,whatsapp,workflows,default --sleep=3 --tries=3 --timeout=90
php artisan schedule:work
php artisan reverb:start

Em vez de schedule:work, um cron pode executar php artisan schedule:run a cada minuto. Use supervisor, systemd ou o gerenciador equivalente da plataforma. Depois de deploy de código ou configuração, reinicie processos de longa duração de forma graciosa.

Persistência e arquivos

Publique o link de storage e preserve storage/app/public. Os uploads de atualizações usam explicitamente o disco public, independentemente de FILESYSTEM_DISK; em múltiplas instâncias, monte esse diretório em volume compartilhado. Migrar esses uploads para S3 exige mudança de código e migração dos arquivos existentes, não apenas uma variável de ambiente.

O build VitePress grava em docs/.vitepress/dist no repositório steercrew-docs. Não edite esse diretório gerado: a fonte fica em docs.

Rede e HTTPS

• Exponha somente o proxy, não banco, Redis ou portas administrativas.
• Permita websocket seguro (wss) para o host do Reverb.
• Preserve cabeçalhos de proxy e host usados pelo Laravel.
• Webhooks da Meta e callbacks OAuth precisam de HTTPS público.
• Nodes HTTP de flows não acessam localhost nem redes privadas e não seguem redirect.

Backup e recuperação

Inclua no plano de backup:

• banco PostgreSQL;
• arquivos/anexos em storage/app/public;
• variáveis e segredos no cofre da plataforma;
• configuração do proxy e dos processos.

Teste restauração em ambiente isolado. Redis, caches, assets compilados e vendor/node_modules podem ser reconstruídos; não devem ser a única cópia de dados de negócio.

Checklist de saúde

• [ ] /login abre por HTTPS.
• [ ] Banco e Redis respondem apenas na rede privada.
• [ ] Worker consome as quatro filas.
• [ ] php artisan schedule:list mostra workflows:tick e workflows:prune.
• [ ] Reverb aceita conexão wss pelo domínio publicado.
• [ ] O volume storage/app/public permanece acessível após novo deploy e, quando houver, em todas as instâncias.
• [ ] E-mail de verificação chega no ambiente correto.
• [ ] Webhook da Meta é validado.
• [ ] /docs/ abre e a pesquisa encontra um tutorial.
• [ ] Backup e restauração foram ensaiados.

Veja Configuração de ambiente, Jobs e fila e Diagnóstico.