Ambiente e Configuração
Esta página define os pré-requisitos de infraestrutura, a topologia de containers e a matriz consolidada de variáveis de ambiente necessárias para operar a plataforma EcomSmart Agents tanto em ambiente de desenvolvimento local quanto em servidores dedicados (VPS) de produção.
Topologia de Infraestrutura
A plataforma é orquestrada através do Docker Compose central localizado em infra/docker-compose.yaml, que interliga os módulos de negócio aos bancos de dados compartilhados através de uma rede bridge isolada:
flowchart TD
subgraph Borda [Borda & Acesso Externo]
tunnel[Cloudflare Tunnel]
flow_gw[Flow Gateway Nginx :8080<br>host: 127.0.0.1:3080 por padrão]
dev_gw[Nginx Gateway de Subdomínios :80]
end
subgraph Aplicacoes [Módulos da Plataforma]
landing[Landing :8080]
panel[Panel SPA :8000]
bff[Frontend Entrypoint / BFF :7000]
wpp[WhatsApp Entrypoint :8000]
b2c[Agente B2C :10001]
b2b[Agente B2B]
woo[WooCommerce Wrapper]
ai[GenAI Wrapper]
mkt[Marketing Campaigns]
end
subgraph Persistencia [Persistência & Armazenamento]
pg[(PostgreSQL merchants-db :5432)]
redis[(Redis :6379)]
minio[(MinIO Storage :9000)]
weaviate[(Weaviate Vector Store :8080)]
end
subgraph BootTasks [Tarefas de Inicialização]
migrate[db-migrate: Alembic]
minio_init[minio-init: Buckets]
end
Borda --> Aplicacoes
Aplicacoes --> Persistencia
BootTasks -.-> Persistencia
style Borda fill:#f8fafc,stroke:#64748b,stroke-width:1.5px,color:#1e293b
style Aplicacoes fill:#f0f9ff,stroke:#0284c7,stroke-width:1.5px,color:#0369a1
style Persistencia fill:#fefce8,stroke:#d97706,stroke-width:1.5px,color:#92400e
style BootTasks fill:#f0fdf4,stroke:#16a34a,stroke-width:1.5px,color:#166534
Pré-requisitos de Sistema
| Recurso | Requisito Mínimo (Dev) | Recomendado (Produção) |
|---|---|---|
| Sistema Operacional | Linux Ubuntu 22.04 LTS / Debian 12 | Ubuntu 22.04 LTS x86_64 |
| CPU | 4 vCPUs | 8 vCPUs dedicadas |
| Memória RAM | 8 GB | 16 GB (para rembg e Weaviate) |
| Disco / Armazenamento | 30 GB SSD | 100 GB NVMe |
| Docker Engine | $\ge 24.0.0$ | $\ge 26.0.0$ com plugin compose v2 |
| Rede Docker | Bridge ecomsmart-net |
Bridge ecomsmart-net com MTU padrão |
Matriz Consolidada de Variáveis (.env)
Há duas camadas de configuração. O Compose resolve variáveis de interpolação a partir do ambiente do comando e, quando o comando é executado em infra/, de infra/.env. Já os módulos que declaram env_file: .env usam seu próprio arquivo .env no diretório do serviço. Não presuma que exista um .env único na raiz nem replique segredos sem necessidade.
1. Domínios e Identidade Web
| Variável | Exemplo | Finalidade |
|---|---|---|
PANEL_PUBLIC_URL |
https://flow.ecomsmart.com.br |
URL canônica do painel exibida em links externos e redirecionamentos. |
SESSION_COOKIE_DOMAIN |
(vazio) | Domínio do cookie de sessão. Vazio cria cookie host-only para compatibilidade. |
FLOW_GATEWAY_PORT |
3080 |
Porta local do Nginx unificado para diagnóstico interno na VPS. |
DEV_PREFIX |
producao |
Prefixo usado para compor subdomínios legados no gateway Nginx. |
DEV_DOMAIN |
ecomsmart.com.br |
Domínio base corporativo. |
TUNNEL_TOKEN |
eyJh... |
Token secreto do Cloudflare Tunnel configurado no Zero Trust Dashboard. |
2. Chaves Internas de Serviço (Shared Secrets)
Todas as requisições HTTP entre containers na rede Docker exigem o cabeçalho X-Internal-Key validado contra estes valores:
| Variável | Consumidores Principais | O que protege |
|---|---|---|
PLATFORM_API_INTERNAL_KEY |
WhatsApp Entrypoint, B2B, B2C, WooCommerce | Endpoints /internal/merchants/* no BFF. |
WPP_API_KEY |
Agentes B2C e B2B | Endpoints /api/v1/send-messages/*. |
B2C_INTERNAL_API_KEY |
WhatsApp Entrypoint | Rota de eventos /api/v1/events/ do Agente B2C. |
B2B_INTERNAL_API_KEY |
WhatsApp Entrypoint | Rota de eventos /api/v1/events/ do Agente B2B. |
WC_API_KEY |
Agentes B2C e B2B | Endpoints de produtos, frete e checkout no WC Wrapper. |
AI_UTILS_API_KEY |
B2C, B2B e WC Wrapper | Chamadas de LLM, ghost-mannequin e Weaviate. |
MARKETING_INTERNAL_KEY |
Painel Administrativo / Copilot | Rotas analíticas e servidor MCP de campanhas. |
3. Integração com a Meta & WhatsApp
| Variável | Descrição |
|---|---|
META_APP_SECRET |
Segredo do aplicativo na Meta para validação HMAC-SHA256 de webhooks. |
META_VERIFY_TOKEN |
Token do handshake hub.verify_token configurado no painel de desenvolvedores. |
FLOWS_PRIVATE_KEY |
Chave RSA privada de 2048 bits (formato PEM em linha única com \n) para descriptografia de WhatsApp Flows. |
PHONE_NUMBER_ID |
Identificador do número de WhatsApp central da plataforma. |
WHATSAPP_TOKEN |
Token de sistema da Meta com escopo whatsapp_business_messaging. |
WHATSAPP_WABA_ID |
Identificador da conta WABA central. |
4. Inteligência Artificial (GenAI)
| Variável | Descrição |
|---|---|
OPENAI_API_KEY |
Chave de API da OpenAI para geração de texto, imagem e embeddings. |
GEMINI_API_KEY |
Chave da Google AI Studio para contingência de modelos LLM. |
AI_UTILS_EMBEDDING_MODEL |
Nome do modelo vetorial (padrão: text-embedding-3-small). |
5. Bancos de Dados & Storage
| Variável | Padrão | Descrição |
|---|---|---|
MERCHANTS_DB_HOST |
merchants-db |
Host do container PostgreSQL na rede Docker. |
MERCHANTS_DB_PORT |
5432 |
Porta interna do PostgreSQL. |
MERCHANTS_DB_USER |
merchants_admin |
Usuário do banco PostgreSQL. |
MERCHANTS_DB_PASSWORD |
(segredo forte) | Senha de acesso do PostgreSQL. |
MERCHANTS_DB_NAME |
merchants |
Nome do banco relacional principal. |
REDIS_URL |
redis://redis:6379/0 |
String de conexão para sessões, locks e filas. |
MINIO_ROOT_USER |
minio_admin |
Usuário administrativo do storage S3. |
MINIO_ROOT_PASSWORD |
(segredo forte) | Senha administrativa do storage S3. |
Geração Segura de Credenciais
Para criar credenciais aleatórias fortes durante o setup inicial na VPS:
# 1. Chaves compartilhadas de serviço (execute para cada variável interna)
openssl rand -hex 32
# 2. Hash de senha para o usuário administrador inicial do painel
docker compose -f infra/docker-compose.yaml run --rm --entrypoint python frontend-entrypoint -c \
"from app.auth.passwords import hash_password; print(hash_password('SUA_SENHA_FORTE_AQUI'))"
# 3. Par de chaves RSA para WhatsApp Flows
openssl genrsa -out flows_private.pem 2048
# Extraia a chave pública para cadastrar na Meta:
openssl rsa -in flows_private.pem -pubout -out flows_public.pem
Formatação da Chave RSA no .env
Para inserir o arquivo PEM na variável FLOWS_PRIVATE_KEY do .env, substitua as quebras de linha por \n ou envolva o bloco com aspas duplas:
Procedimento de Inicialização Inicial
# 1. Subir bancos de dados e tarefas de migração
docker compose -f infra/docker-compose.yaml up -d merchants-db redis minio weaviate
docker compose -f infra/docker-compose.yaml run --rm --build --no-deps db-migrate
docker compose -f infra/docker-compose.yaml up --build minio-init
# 2. Subir toda a plataforma de serviços.
# A rede nomeada ecomsmart-net é criada pelo Compose quando necessário.
docker compose -f infra/docker-compose.yaml up -d --build