Pular para conteúdo

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:

awk '{printf "%s\\n", $0}' flows_private.pem


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