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