1 Deploy

Rafael Alves Lopes edited this page 2026-05-27 15:19:43 -03:00

Table of Contents

• Deploy e Operacao
• Decisao estrutural
• Visao rapida
• Pre-requisitos da VM Linux
• Variaveis de ambiente
• Ordem de inicializacao
• Configuracao do banco
• Backup do banco externo
• Backup da sessao WhatsApp
• Atualizacao em producao
• Rollback
• Troubleshooting comum
• Backend nao conecta no banco
• Tabelas nao existem
• Login LDAP falha
• Microsoft OAuth redireciona errado
• WhatsApp nao conecta
• Frontend chama API errada
• Checklist de deploy

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:

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:

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:

docker compose up -d --build

Verificar:

docker compose ps
docker compose logs -f backend
docker compose logs -f frontend

Configuracao do banco

As migrations ficam em:

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:

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:

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:

pg_dump "postgresql://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME" > backup-omnichannel.sql

Backup comprimido:

pg_dump "postgresql://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME" | gzip > backup-omnichannel.sql.gz

Restaurar em ambiente vazio:

psql "postgresql://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME" < backup-omnichannel.sql

Restaurar backup gzip:

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:

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:

pg_dump "postgresql://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME" > backup-pre-deploy.sql

Rollback

Rollback simples de codigo:

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.

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:

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:

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:

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.