Batch App

Um Carol App batch permite executar código na infraestrutura da Carol a partir de uma imagem Docker. A imagem reúne o código da aplicação, suas dependências e o comando de inicialização. A linguagem e as ferramentas utilizadas são definidas pelo projeto e empacotadas nessa imagem.

Esse formato pode ser utilizado para importação de dados, integrações, geração de relatórios, enriquecimento de dados e outras rotinas de processamento. A execução pode ser iniciada manualmente ou por um agendamento na Carol.

Preparação da imagem

O código e o Dockerfile devem estar em um repositório Git. Durante o build, a Carol acessa esse repositório para obter os arquivos da aplicação. Se o repositório for privado, é necessário informar na tela de build um token com permissão de leitura para autorizar esse acesso.

O build é realizado pelo recurso Build do app, utilizando a branch configurada. O Dockerfile descreve como preparar o ambiente da aplicação, instalar as dependências e definir o comando de inicialização da imagem. O procedimento está descrito em Build e atualização.

Configuração e execução

O manifesto associa o processo à imagem Docker e define os recursos de execução, as variáveis de ambiente e a duração máxima da tarefa. Essas configurações são descritas em Manifesto e configuração.

Com o manifesto configurado e o build concluído, a tarefa pode ser iniciada na aba Process, manualmente ou por agendamento. A cada execução, a Carol utiliza a imagem para criar um contêiner e iniciar o comando da aplicação. O resultado pode ser acompanhado pelos logs da tarefa, e o código deve encerrar ao concluir o processamento.

Exemplo prático

O exemplo desta página demonstra esse ciclo com uma rotina Python que simula o processamento de três itens. A aplicação registra um evento por item e uma mensagem de conclusão. Não há acesso a dados da tenant nem necessidade de credenciais para a execução local.

O projeto contém três arquivos:

Arquivo	Responsabilidade
main.py	Implementa a rotina de processamento.
Dockerfile	Define a imagem Docker e o comando que inicia a rotina.
manifest.json	Configura a imagem, os recursos e as variáveis do processo na Carol.

Os arquivos completos estão disponíveis nos blocos expansíveis desta página. A execução local permite verificar o comportamento da rotina antes de configurar o manifesto e realizar o build na Carol.

Organização dos arquivos para executar o exemplo

Neste repositório, os arquivos estão em static/examples/carol-apps/batch. Para utilizar os downloads em um projeto próprio, mantenha a mesma organização:

static/examples/carol-apps/
└── batch/
    ├── main.py
    ├── Dockerfile
    └── manifest.json

Os comandos de execução usam essa estrutura. Caso adote outro diretório, ajuste os comandos locais e o campo docker[].gitPath do manifesto. O Dockerfile copia main.py do diretório utilizado como contexto do build, que nos comandos abaixo é ./batch.

Execução local

O exemplo utiliza apenas a biblioteca padrão do Python. Com Python 3.13 instalado e os arquivos organizados na estrutura apresentada acima, execute os comandos a partir da raiz do projeto:

cd static/examples/carol-apps
python3 batch/main.py

A aplicação processa três itens e encerra. O último evento deve ser {"event": "completed", "total": 3}.

A quantidade de itens pode ser alterada pela variável de ambiente ITEM_LIMIT. Quando ela não é informada, o código utiliza o valor padrão 3:

Trecho de main.py

limit = int(os.environ.get("ITEM_LIMIT", "3"))

Código completo e Dockerfile

Baixar main.py

batch/main.py

"""Processo batch mínimo: lê configuração, registra resultado e encerra."""

import json
import os


def main():
    limit = int(os.environ.get("ITEM_LIMIT", "3"))
    if limit < 1:
        raise ValueError("ITEM_LIMIT deve ser maior que zero")

    for item in range(1, limit + 1):
        print(json.dumps({"event": "item_processed", "item": item}), flush=True)
    print(json.dumps({"event": "completed", "total": limit}), flush=True)


if __name__ == "__main__":
    main()

Baixar Dockerfile

batch/Dockerfile

FROM python:3.13-slim
WORKDIR /app
ENV PYTHONUNBUFFERED=1
COPY main.py .
USER 10001:10001
ENTRYPOINT ["python", "main.py"]

O ENTRYPOINT inicia main.py. O campo algorithmName identifica o processo na Carol; ele não substitui o comando de inicialização da imagem.

Execução com Docker e validação de erros

A partir de static/examples/carol-apps:

docker build -t carol-demo-batch:1.0.0 ./batch
docker run --rm -e ITEM_LIMIT=3 carol-demo-batch:1.0.0

A execução deve terminar com código 0. O comando abaixo permite validar o tratamento de uma configuração inválida:

docker run --rm -e ITEM_LIMIT=0 carol-demo-batch:1.0.0

O processo deve registrar ValueError e encerrar com código diferente de zero. O exemplo usa apenas a biblioteca padrão do Python e não precisa de credenciais da Carol.

Configuração do processo

No manifesto, as configurações de execução são declaradas em batch.processes[].instanceProperties:

Trecho do processo batch

{
  "environments": {"ITEM_LIMIT": "3"},
  "properties": {
    "dockerName": "carol-demo-batch",
    "instanceType": "c1.nano",
    "preemptible": false,
    "deadline": "15m"
  }
}

dockerName vincula o processo à definição de build da imagem. instanceType seleciona os recursos de CPU e memória, e deadline define a duração máxima da tarefa. ITEM_LIMIT é disponibilizada ao processo como variável de ambiente. A referência dos demais campos está em Manifesto e configuração.

Manifesto completo para download

Este manifesto contém apenas o processo batch. Antes do build, substitua SUA_ORGANIZACAO/SEU_REPOSITORIO pelos nomes da organização e do repositório e ajuste a branch e gitPath conforme a localização dos arquivos.

Baixar manifest.json batch

manifest.json

{
  "batch": {
    "processes": [
      {
        "name": "batch_demo",
        "algorithmName": "batch_demo",
        "algorithmTitle": {
          "pt-BR": "Processar itens",
          "en-US": "Process items"
        },
        "algorithmDescription": {
          "pt-BR": "Processa itens e encerra.",
          "en-US": "Processes items and exits."
        },
        "dataModels": [],
        "instanceProperties": {
          "environments": {
            "ITEM_LIMIT": "3"
          },
          "properties": {
            "dockerName": "carol-demo-batch",
            "instanceType": "c1.nano",
            "preemptible": false,
            "deadline": "15m"
          }
        }
      }
    ]
  },
  "docker": [
    {
      "dockerName": "carol-demo-batch",
      "dockerTag": "1.0.0",
      "gitRepoUrl": "https://github.com/SUA_ORGANIZACAO/SEU_REPOSITORIO",
      "gitBranch": "main",
      "gitPath": "/static/examples/carol-apps/batch",
      "gitDockerfileName": "Dockerfile"
    }
  ]
}

Execução na Carol

Após concluir o build da definição carol-demo-batch, abra Process, selecione batch_demo e execute a tarefa. A conclusão deve ser acompanhada pelo evento completed nos logs.

O agendamento pode ser configurado na interface após a validação da execução manual. Verifique o fuso horário e a data da próxima execução.

Agendamento e reprocessamento

A tarefa deve encerrar após a conclusão do processamento. Servidores ou laços de espera mantêm o processo ativo e impedem sua finalização.

Falhas devem ser propagadas ao processo principal para que a execução termine com código diferente de zero. O tratamento de reexecuções deve impedir que a mesma entrada gere efeitos duplicados.

O exemplo usa preemptible: false. Se optar por instâncias interrompíveis, a tarefa precisa tolerar interrupção e retomada ou reprocessamento. O campo deadline aceita durações como 40s, 15m ou 1h, respeitando o limite de 24 horas.

Para tarefas disparadas por mudanças em modelos de dados, configure dataModels conforme os modelos acompanhados. O exemplo usa uma lista vazia e não depende dessa condição.

Se a tarefa não encerrar, verifique threads abertas, laços sem fim e o comando de inicialização. Se precisar disponibilizar arquivos gerados, consulte Carol App Storage.