From f0cf823c8c0c7b3a1716302ec24c25ba29ddeb45 Mon Sep 17 00:00:00 2001 From: Rafael Alves Lopes Date: Wed, 27 May 2026 15:19:43 -0300 Subject: [PATCH] Adicionar Deploy --- Deploy.md | 313 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 313 insertions(+) create mode 100644 Deploy.md diff --git a/Deploy.md b/Deploy.md new file mode 100644 index 0000000..c345e29 --- /dev/null +++ b/Deploy.md @@ -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 +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.