Adicionar Deploy
parent
198f8bb3d8
commit
f0cf823c8c
313
Deploy.md
Normal file
313
Deploy.md
Normal file
@ -0,0 +1,313 @@
|
|||||||
|
# Deploy e Operacao
|
||||||
|
|
||||||
|
Este documento e o manual operacional para subir, atualizar, fazer backup e diagnosticar o Omnichannel Sothis.
|
||||||
|
|
||||||
|
## Decisao estrutural
|
||||||
|
|
||||||
|
O `docker-compose.yml` deste repositorio nao sobe banco de dados.
|
||||||
|
|
||||||
|
Ele sobe somente:
|
||||||
|
|
||||||
|
- `backend`
|
||||||
|
- `frontend`
|
||||||
|
|
||||||
|
O PostgreSQL deve ser externo ao compose: VM dedicada, banco corporativo, RDS, container separado ou instancia local administrada fora deste projeto.
|
||||||
|
|
||||||
|
Essa decisao evita que o ambiente de aplicacao seja tambem responsavel pelo ciclo de vida do banco, reduz risco de perda acidental de volume e deixa backup/migrations como processos explicitos.
|
||||||
|
|
||||||
|
## Visao rapida
|
||||||
|
|
||||||
|
Servicos do `docker-compose.yml`:
|
||||||
|
|
||||||
|
| Servico | Funcao | Porta host | Porta container |
|
||||||
|
|---|---|---:|---:|
|
||||||
|
| `backend` | API NestJS + WhatsApp Web + Socket.IO | `4001` | `3001` |
|
||||||
|
| `frontend` | React/Vite | `4000` | `3000` |
|
||||||
|
|
||||||
|
Servicos externos obrigatorios:
|
||||||
|
|
||||||
|
| Servico | Funcao |
|
||||||
|
|---|---|
|
||||||
|
| PostgreSQL | Banco principal da aplicacao |
|
||||||
|
| LDAP/AD | Login corporativo, se habilitado |
|
||||||
|
| Microsoft Entra ID | OAuth Microsoft, se habilitado |
|
||||||
|
| WhatsApp Web | Sessao do WhatsApp via QR Code |
|
||||||
|
|
||||||
|
URLs comuns:
|
||||||
|
|
||||||
|
- Frontend: `http://localhost:4000`
|
||||||
|
- Backend: `http://localhost:4001`
|
||||||
|
- Health: `http://localhost:4001/health`
|
||||||
|
- WhatsApp status: `http://localhost:4001/whatsapp/status`
|
||||||
|
|
||||||
|
## Pre-requisitos da VM Linux
|
||||||
|
|
||||||
|
- Docker Engine instalado.
|
||||||
|
- Docker Compose plugin instalado.
|
||||||
|
- Git instalado.
|
||||||
|
- PostgreSQL externo criado e acessivel pela VM/container backend.
|
||||||
|
- Acesso de rede ao LDAP/AD, se login corporativo for usado.
|
||||||
|
- Porta de saida liberada para WhatsApp Web.
|
||||||
|
- Memoria suficiente para Chromium/Puppeteer usado pelo `whatsapp-web.js`.
|
||||||
|
|
||||||
|
Sugestao minima para demo/MVP:
|
||||||
|
|
||||||
|
- 2 vCPU
|
||||||
|
- 4 GB RAM
|
||||||
|
- 30 GB disco
|
||||||
|
|
||||||
|
Para uso continuo, considerar mais memoria por causa do WhatsApp Web.
|
||||||
|
|
||||||
|
## Variaveis de ambiente
|
||||||
|
|
||||||
|
O compose usa `.env.development` na raiz para o backend.
|
||||||
|
|
||||||
|
Campos obrigatorios:
|
||||||
|
|
||||||
|
```env
|
||||||
|
DB_HOST=10.0.120.75
|
||||||
|
DB_PORT=5432
|
||||||
|
DB_USER=omnichannel
|
||||||
|
DB_PASSWORD=change-me
|
||||||
|
DB_NAME=omnichannel
|
||||||
|
|
||||||
|
PORT=3001
|
||||||
|
FRONTEND_URL=http://localhost:4000
|
||||||
|
JWT_SECRET=change-this-long-random-secret
|
||||||
|
JWT_EXPIRES_IN=8h
|
||||||
|
REQUEST_BODY_LIMIT=25mb
|
||||||
|
|
||||||
|
AUTH_PROVIDERS=ldap
|
||||||
|
LDAP_ENABLED=true
|
||||||
|
LDAP_URL=ldaps://servidor:636
|
||||||
|
LDAP_DOMAIN=empresa.com.br
|
||||||
|
LDAP_USER_DN_TEMPLATE={{username}}@empresa.com.br
|
||||||
|
LDAP_SEARCH_BASE=DC=empresa,DC=com
|
||||||
|
LDAP_SEARCH_FILTER=(&(objectClass=user)(sAMAccountName={{username}}))
|
||||||
|
```
|
||||||
|
|
||||||
|
Para Microsoft OAuth:
|
||||||
|
|
||||||
|
```env
|
||||||
|
MICROSOFT_ENABLED=true
|
||||||
|
MICROSOFT_TENANT_ID=...
|
||||||
|
MICROSOFT_CLIENT_ID=...
|
||||||
|
MICROSOFT_CLIENT_SECRET=...
|
||||||
|
MICROSOFT_REDIRECT_URI=http://seu-host:4001/auth/oauth/microsoft/callback
|
||||||
|
MICROSOFT_SUCCESS_REDIRECT_URL=http://seu-host:4000/login
|
||||||
|
```
|
||||||
|
|
||||||
|
## Ordem de inicializacao
|
||||||
|
|
||||||
|
1. PostgreSQL externo deve estar ativo e com migrations aplicadas.
|
||||||
|
2. `backend` sobe e conecta no banco externo.
|
||||||
|
3. `frontend` sobe e consome a API do backend.
|
||||||
|
|
||||||
|
Comando:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker compose up -d --build
|
||||||
|
```
|
||||||
|
|
||||||
|
Verificar:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker compose ps
|
||||||
|
docker compose logs -f backend
|
||||||
|
docker compose logs -f frontend
|
||||||
|
```
|
||||||
|
|
||||||
|
## Configuracao do banco
|
||||||
|
|
||||||
|
As migrations ficam em:
|
||||||
|
|
||||||
|
```txt
|
||||||
|
database/migrations
|
||||||
|
```
|
||||||
|
|
||||||
|
O projeto ainda nao possui runner formal de migrations. Para ambiente novo, aplicar as migrations SQL em ordem antes de colocar o backend em uso.
|
||||||
|
|
||||||
|
Exemplo manual, a partir da raiz, apontando para o banco externo:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
for file in database/migrations/*.sql; do
|
||||||
|
psql "postgresql://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME" -f "$file"
|
||||||
|
done
|
||||||
|
```
|
||||||
|
|
||||||
|
No Windows/PowerShell:
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
Get-ChildItem database\migrations\*.sql | Sort-Object Name | ForEach-Object {
|
||||||
|
psql "postgresql://$env:DB_USER`:$env:DB_PASSWORD@$env:DB_HOST`:$env:DB_PORT/$env:DB_NAME" -f $_.FullName
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Recomendacao: criar um runner oficial antes de producao para evitar diferenca entre ambientes.
|
||||||
|
|
||||||
|
## Backup do banco externo
|
||||||
|
|
||||||
|
Backup manual:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pg_dump "postgresql://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME" > backup-omnichannel.sql
|
||||||
|
```
|
||||||
|
|
||||||
|
Backup comprimido:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pg_dump "postgresql://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME" | gzip > backup-omnichannel.sql.gz
|
||||||
|
```
|
||||||
|
|
||||||
|
Restaurar em ambiente vazio:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
psql "postgresql://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME" < backup-omnichannel.sql
|
||||||
|
```
|
||||||
|
|
||||||
|
Restaurar backup gzip:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
gunzip -c backup-omnichannel.sql.gz | psql "postgresql://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Backup da sessao WhatsApp
|
||||||
|
|
||||||
|
O WhatsApp Web depende de sessao local/Puppeteer. Antes de producao, identificar o diretorio persistente usado pelo `whatsapp-web.js` no container e montar volume dedicado no servico `backend`.
|
||||||
|
|
||||||
|
Sem volume persistente, uma recriacao do container pode exigir novo QR Code.
|
||||||
|
|
||||||
|
Recomendacao:
|
||||||
|
|
||||||
|
- mapear a pasta de auth/session do WhatsApp para volume;
|
||||||
|
- documentar como limpar a sessao quando QR travar;
|
||||||
|
- manter somente uma instancia ativa usando a mesma sessao.
|
||||||
|
|
||||||
|
## Atualizacao em producao
|
||||||
|
|
||||||
|
Fluxo recomendado:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git pull
|
||||||
|
docker compose build backend frontend
|
||||||
|
docker compose up -d backend frontend
|
||||||
|
docker compose logs -f backend
|
||||||
|
```
|
||||||
|
|
||||||
|
Se houver migration:
|
||||||
|
|
||||||
|
1. Fazer backup antes.
|
||||||
|
2. Aplicar migration no banco externo.
|
||||||
|
3. Subir backend.
|
||||||
|
4. Validar login, WhatsApp, chat, admin e abertura ativa.
|
||||||
|
|
||||||
|
Backup antes do deploy:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pg_dump "postgresql://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME" > backup-pre-deploy.sql
|
||||||
|
```
|
||||||
|
|
||||||
|
## Rollback
|
||||||
|
|
||||||
|
Rollback simples de codigo:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git checkout <commit-anterior>
|
||||||
|
docker compose up -d --build
|
||||||
|
```
|
||||||
|
|
||||||
|
Rollback com banco:
|
||||||
|
|
||||||
|
1. Parar backend.
|
||||||
|
2. Restaurar backup compativel no banco externo.
|
||||||
|
3. Subir backend.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker compose stop backend
|
||||||
|
psql "postgresql://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME" < backup-pre-deploy.sql
|
||||||
|
docker compose up -d backend
|
||||||
|
```
|
||||||
|
|
||||||
|
## Troubleshooting comum
|
||||||
|
|
||||||
|
### Backend nao conecta no banco
|
||||||
|
|
||||||
|
Verificar:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker compose logs backend
|
||||||
|
```
|
||||||
|
|
||||||
|
Checar:
|
||||||
|
|
||||||
|
- `DB_HOST`;
|
||||||
|
- `DB_PORT`;
|
||||||
|
- usuario/senha;
|
||||||
|
- firewall entre container/VM e banco;
|
||||||
|
- se o banco aceita conexao remota;
|
||||||
|
- se o schema/migrations foram aplicados.
|
||||||
|
|
||||||
|
### Tabelas nao existem
|
||||||
|
|
||||||
|
Provavel causa: migrations nao aplicadas no banco externo.
|
||||||
|
|
||||||
|
Validar com `psql`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
psql "postgresql://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME" -c "\dt"
|
||||||
|
```
|
||||||
|
|
||||||
|
Aplicar migrations em ordem.
|
||||||
|
|
||||||
|
### Login LDAP falha
|
||||||
|
|
||||||
|
Checar:
|
||||||
|
|
||||||
|
- `LDAP_URL`;
|
||||||
|
- `LDAP_DOMAIN`;
|
||||||
|
- `LDAP_USER_DN_TEMPLATE`;
|
||||||
|
- conectividade da VM com o AD;
|
||||||
|
- certificado/porta LDAPS.
|
||||||
|
|
||||||
|
### Microsoft OAuth redireciona errado
|
||||||
|
|
||||||
|
Checar:
|
||||||
|
|
||||||
|
- `MICROSOFT_REDIRECT_URI`;
|
||||||
|
- URL cadastrada no Entra ID;
|
||||||
|
- `MICROSOFT_SUCCESS_REDIRECT_URL`;
|
||||||
|
- host/porta expostos publicamente.
|
||||||
|
|
||||||
|
### WhatsApp nao conecta
|
||||||
|
|
||||||
|
Checar:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker compose logs backend
|
||||||
|
```
|
||||||
|
|
||||||
|
Possiveis causas:
|
||||||
|
|
||||||
|
- QR Code expirou;
|
||||||
|
- sessao corrompida;
|
||||||
|
- Chromium/Puppeteer sem dependencias no container;
|
||||||
|
- container sem memoria suficiente;
|
||||||
|
- multiplas instancias usando a mesma sessao.
|
||||||
|
|
||||||
|
### Frontend chama API errada
|
||||||
|
|
||||||
|
Checar `VITE_API_URL` no build do frontend. Em Vite, variaveis sao resolvidas no build.
|
||||||
|
|
||||||
|
## Checklist de deploy
|
||||||
|
|
||||||
|
- [ ] Banco externo criado.
|
||||||
|
- [ ] Migrations aplicadas no banco externo.
|
||||||
|
- [ ] `.env.development` ajustado para ambiente.
|
||||||
|
- [ ] `JWT_SECRET` forte e exclusivo.
|
||||||
|
- [ ] Backup testado.
|
||||||
|
- [ ] LDAP/Microsoft validado.
|
||||||
|
- [ ] QR WhatsApp validado.
|
||||||
|
- [ ] Frontend acessa backend correto.
|
||||||
|
- [ ] Admin consegue ver usuarios e acessos.
|
||||||
|
- [ ] Agente consegue assumir e responder atendimento.
|
||||||
|
- [ ] Supervisor/admin conseguem ver operacao.
|
||||||
Loading…
Reference in New Issue
Block a user