> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Deployment do Reporter > Faça o deploy do Reporter: um binário com um seletor de modo de execução, MongoDB, a fila de comandos de relatório, armazenamento de objetos compatível com S3, Redis ou Valkey, dimensionamento do worker, e retenção de relatórios por meio de uma política de ciclo de vida do bucket. O Reporter é entregue como um único binário com duas superfícies, e `RUN_MODE` seleciona quais superfícies um processo serve. A mesma imagem roda como a API, como o worker de relatórios, ou como ambas. Quatro dependências ficam por trás delas. O Reporter lê os seus bancos de dados por meio de um motor de extração que roda dentro do processo do worker. Não existe um serviço de extração separado para o deploy. ## O que compõe o deploy *** | Componente | Papel | Escala com | | - | - | - | | **Superfície da API** | API REST para templates, relatórios, prazos, fontes de dados, instituições e remessa regulatória. Publica comandos de relatório. | Taxa de requisições. | | **Worker de relatórios** | Consumidor da fila. Extrai os dados, renderiza o relatório, e grava o artefato. | Profundidade da fila. | | **MongoDB** | Templates, relatórios, prazos, e o outbox durável de eventos. | Volume de metadados. | | **RabbitMQ** | A fila de comandos de relatório, e a exchange de eventos de negócio. | Taxa de relatórios. | | **Armazenamento de objetos** | Fontes de template e relatórios renderizados. Compatível com S3. | Volume de artefatos e retenção. | | **Redis ou Valkey** | Locks de idempotência, cache de schema, e ciclo de vida do tenant. | Ambas as superfícies. | ## Modos de execução *** `RUN_MODE=api` atende operações REST, `/health` e `/version` em `SERVER_ADDRESS`. `RUN_MODE=worker` consome a fila de comandos de relatório e não tem superfície REST. `RUN_MODE=all` roda ambas as superfícies em um único processo. Um processo atende `/health`, `/readyz` e `/metrics` em `HEALTH_PORT` quando você define essa variável. Um worker sem `HEALTH_PORT` não tem listener e encerra na inicialização, e a imagem do worker define `8099`. Use `all` para desenvolvimento local. Em produção, faça o deploy das duas superfícies separadamente, para que a geração de relatórios escale por conta própria. O exemplo a seguir define a porta de health nos dois deploys. ```bash theme={null} # API deployment RUN_MODE=api SERVER_ADDRESS=:4005 HEALTH_PORT=8099 # Worker deployment RUN_MODE=worker HEALTH_PORT=8099 ``` ## MongoDB *** Ambas as superfícies usam o mesmo deployment do MongoDB. A superfície da API grava templates, relatórios, e prazos. O worker atualiza um relatório conforme ele é concluído. `MONGO_HOST` e `MONGO_NAME` são obrigatórias na inicialização quando `MULTI_TENANT_ENABLED` é `false`, o padrão. ## RabbitMQ *** Duas responsabilidades separadas compartilham um broker. ### A fila de comandos de relatório Essa fila carrega trabalho da superfície da API para o worker. `RABBITMQ_EXCHANGE`, `RABBITMQ_GENERATE_REPORT_QUEUE`, e `RABBITMQ_GENERATE_REPORT_KEY` nomeiam a exchange, a fila, e a routing key. A superfície da API publica, então precisa das três variáveis mais sua conexão com o broker: `RABBITMQ_HOST`, `RABBITMQ_PORT_AMQP`, `RABBITMQ_DEFAULT_USER`, e `RABBITMQ_DEFAULT_PASS`. O worker consome da fila e precisa dessa mesma conexão mais `RABBITMQ_GENERATE_REPORT_QUEUE`. Os objetos do broker devem existir antes que qualquer um dos dois serviços seja iniciado. O canal é interno ao Reporter. Para saber que um relatório terminou, inscreva-se nos eventos de negócio abaixo, ou faça polling no relatório. Um worker que falha ao processar uma mensagem tenta de novo até cinco vezes com backoff, e depois a rejeita sem requeue. Vincule uma dead-letter exchange à fila de comandos, para que um relatório rejeitado vá parar em algum lugar onde você possa inspecioná-lo. Quando o broker não responde, o worker continua tentando assinar a fila de novo, com backoff. Ele assina de novo depois que o broker fecha o canal. ### A exchange de eventos Eventos de negócio (`template.*`, `report.*`, `deadline.*`, `regulatory.*`) vão para uma exchange que você nomeia em `RABBITMQ_REPORT_EVENTS_EXCHANGE`. O valor é configurado pelo operador. O valor de referência é `reporter.events`. Defina essa exchange, `STREAMING_BROKERS`, e `STREAMING_CLOUDEVENTS_SOURCE` sempre que `STREAMING_ENABLED=true`. Com o streaming desligado, ambas as superfícies iniciam normalmente e não publicam nada. ## Armazenamento de objetos *** O Reporter usa um bucket compatível com S3, nomeado em `OBJECT_STORAGE_BUCKET`. Ele guarda dois tipos de objeto, cada um sob seu próprio prefixo: * a fonte do template, como `templates/.tpl` * o relatório renderizado, como `reports//.` AWS S3, MinIO, e SeaweedFS funcionam todos. Alcance o SeaweedFS pelo gateway S3 dele. `OBJECT_STORAGE_USE_PATH_STYLE=true` é o que MinIO e SeaweedFS esperam, e `OBJECT_STORAGE_DISABLE_SSL` permanece `false` fora do desenvolvimento local. ### Retenção de relatórios O Reporter mantém para sempre os arquivos de relatório e as remessas regulatórias. Ele não tem endpoint de exclusão nem configuração de retenção, então o bucket cresce com o seu volume de relatórios. A única forma de um arquivo expirar é uma regra de ciclo de vida do armazenamento de objetos que você configura. **Essa regra também exclui as remessas regulatórias aprovadas, que são o registro regulatório da instituição.** As linhas salvas a partir das quais uma correção regulatória renderiza o rascunho de novo também ficam em `reports/`, então uma regra de expiração pode impedir a correção de um rascunho mais antigo. > [!WARNING] > > Mantenha `templates/` fora do escopo: uma regra que cobre o bucket inteiro também remove os templates a partir dos quais os seus relatórios são renderizados. ## Redis ou Valkey *** `REDIS_HOST` é obrigatória na superfície da API. O Redis sustenta o lock de idempotência na criação de relatórios e o cache de schema da fonte de dados. O estado de idempotência vive no Redis, não na memória do processo, então as réplicas da API o compartilham. ## Fontes de dados *** O Reporter lê dados de relatório a partir de fontes de dados PostgreSQL e MongoDB no seu registro persistido. Crie e gerencie essas fontes por meio da [API de fontes de dados](https://docs.lerian.studio/pt/reference/products/reporter/list-data-sources.md). Um bloco opcional `DATASOURCE_{NAME}_*` popula uma entrada de registro gerenciada pelo usuário na inicialização do Manager. Ele popula a entrada apenas quando esse `configName` está ausente. Edições e exclusões posteriores pela API têm precedência sobre o ambiente. Tanto o Manager quanto o worker exigem a mesma `DATASOURCE_CRED_ENC_KEY` persistente para proteger as credenciais do registro. Mantenha-a inalterada entre reinicializações e deployments para que eles continuem decifrando as credenciais armazenadas. O Reporter também inicia sem nenhuma configurada, e serve templates, prazos, e métricas. ## Dimensionando o worker *** `RABBITMQ_NUMBERS_OF_WORKERS` define quantas tarefas de relatório um processo worker executa em paralelo. Para escala horizontal, adicione réplicas de worker e direcione-as pela profundidade da fila de comandos. A saída em PDF é renderizada por um pool de navegadores headless: `PDF_POOL_WORKERS` renderizações simultâneas, cujo padrão é 2, cada uma limitada por `PDF_TIMEOUT_SECONDS`, cujo padrão é 90. Dimensione a memória do worker em função desse pool, não apenas das linhas que um relatório lê. Os demais formatos de saída não o usam. Cada extração de uma fonte de dados também carrega limites. São 20 tabelas por fonte de dados e 50 campos por tabela. Também cobrem um prazo de 300 segundos e um teto de 256 MiB nos dados extraídos. As variáveis `ENGINE_*` os alteram. Cada tabela também retorna no máximo 150.000 linhas e cada consulta expira após 300 segundos, a menos que a fonte de dados defina os próprios valores. ## Modo de deployment e TLS *** `DEPLOYMENT_MODE` declara a modalidade do deploy: `local`, `byoc` ou `saas`. Em `saas`, exige TLS. > [!WARNING] > > **O modo SaaS exige TLS em toda dependência.** Defina `DEPLOYMENT_MODE=saas` e uma URL de MongoDB, RabbitMQ, Redis, ou armazenamento de objetos sem criptografia interrompe o processo. Ele para antes de qualquer conexão abrir. Deixe `ALLOW_INSECURE_TLS` não definida em produção. Ela contorna essas verificações, e a stack de desenvolvimento local é o único lugar para ela. ## Verificações de inicialização *** O Reporter valida sua configuração antes de servir qualquer coisa. Cada verificação abaixo interrompe o processo, e o erro nomeia cada variável responsável. | Gatilho | O que o operador vê | | - | - | | `SERVER_ADDRESS`, `REDIS_HOST`, qualquer variável obrigatória de conexão com o RabbitMQ ou de fila de comandos, ou `DATASOURCE_CRED_ENC_KEY` ausente na superfície da API | A validação de configuração falha e lista cada variável ausente. | | Qualquer uma entre `RABBITMQ_HOST`, `RABBITMQ_PORT_AMQP`, `RABBITMQ_DEFAULT_USER`, `RABBITMQ_DEFAULT_PASS`, `RABBITMQ_GENERATE_REPORT_QUEUE`, ou `DATASOURCE_CRED_ENC_KEY` ausente na superfície do worker | A validação de configuração falha e lista cada variável ausente. | | `MONGO_HOST` ou `MONGO_NAME` ausente quando `MULTI_TENANT_ENABLED` é `false` | A validação de configuração as nomeia. | | `STREAMING_ENABLED=true` sem `RABBITMQ_REPORT_EVENTS_EXCHANGE`, `STREAMING_BROKERS`, e `STREAMING_CLOUDEVENTS_SOURCE` (as três são obrigatórias para uma inicialização com streaming habilitado) | A inicialização aborta em vez de rodar com eventos que não vão a lugar nenhum. | | `DEPLOYMENT_MODE=saas` com uma URL de dependência sem criptografia | A inicialização aborta antes de qualquer conexão abrir. | | `LICENSE_KEY` vazia, ou uma licença que não é validada, em qualquer modo de execução | A inicialização aborta. | | `HEALTH_PORT` que não seja um número de porta de 1 a 65535 em qualquer modo de execução | A inicialização aborta. | | `SHUTDOWN_DRAIN_DELAY` ou `SHUTDOWN_TIMEOUT` que não seja uma duração válida | A inicialização aborta. | | `WORKER_HEARTBEAT_STALE_SEC` abaixo de três vezes `WORKER_HEARTBEAT_INTERVAL_SEC`, um `REPORT_TIMEZONE` desconhecido, ou um `REGULATORY_CATALOG_DIR` cujo catálogo não carrega | A inicialização aborta. | > [!NOTE] > > `/readyz` retorna 503 até que cada verificação de inicialização passe. A API verifica o Redis e, no modo single-tenant, o MongoDB e o RabbitMQ. O worker verifica o MongoDB. Após a primeira passagem, uma falha de dependência compartilhada informa readiness degradada com HTTP 200. O consumidor, os dispatchers do outbox, o gatilho de prazos e o reaper de relatórios só começam depois que as verificações de inicialização passam. ## Atualizações contínuas *** `SIGTERM` não muda a readiness. Os listeners continuam atendendo durante o drain, e o worker para de receber mensagens novas. A parada ocorre após o drain. Reserve tempo suficiente para a renderização de relatório mais longa. Veja a [referência de health e readiness](https://docs.lerian.studio/pt/reference/health-and-readiness.md) para o contrato de probes e a [referência de configuração BYOC](https://docs.lerian.studio/pt/reference/byoc-configuration.md#server) para o ciclo de vida compartilhado de parada, incluindo `SHUTDOWN_DRAIN_DELAY` e `SHUTDOWN_TIMEOUT`. ## Próximos passos *** > [card] [Variáveis de ambiente](https://docs.lerian.studio/pt/products/reporter/reporter-environment-variables.md) > > Toda variável do Reporter, por categoria. > [card] [Configuração do BYOC](https://docs.lerian.studio/pt/reference/byoc-configuration.md) > > Os blocos de configuração que todo produto Lerian compartilha. > [card] [Saúde e readiness](https://docs.lerian.studio/pt/reference/health-and-readiness.md) > > O contrato de probe e o que cada resposta significa. > [card] [Conecte o Reporter ao Midaz](https://docs.lerian.studio/pt/products/reporter/connecting-reporter-to-midaz.md) > > Aponte o Reporter para um banco de dados do Midaz e renderize seu primeiro relatório. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.