Manifesto de Carol App

Esta seção tem o objetivo de apresentar o arquivo de manifesto e compartilhar alguns projetos de amostra disponíveis em repositórios públicos.

O arquivo de manifesto é criado automaticamente ao criar um novo aplicativo Carol (Online ou Batch).

Arquivo de exemplo

A seguir um exemplo do arquivo de manifesto:

{
  "batch": {
    "processes": [{
      "algorithmDescription": {
        "en-US": "Batch task Description",
        "pt-BR": "Descrição do Tarefa Batch"
      },
      "algorithmName": "batch_carolapp_algorithm",
      "algorithmTitle": {
        "en-US": "Batch task Description",
        "pt-BR": "Descrição do Tarefa Batch"
      },
      "dataModels": [],
      "instanceProperties": {
        "properties": {
          "dockerName": "batch_carolapp-batch_carolapp_algorithm",
          "instanceType": "c1.nano",
          "preemptible": false
        }
      },
      "name": "batch_carolapp"
    }]
  },
  "online": {
    "processes": [{
      "algorithmDescription": {
        "en-US": "Online Description",
        "pt-BR": "Descrição do Online app"
      },
      "algorithmName": "online_app",
      "algorithmTitle": {
        "en-US": "Online Description",
        "pt-BR": "Descrição do Online app"
      },
      "instanceProperties": {
        "profile": "",
        "properties": {
          "instanceType": "c1.nano",
          "dockerImage": "online_app",
          "autoscale": {
            "enabled": true,
            "minReplicas": 1,
            "maxReplicas": 5
          },
          "healthcheck": {
            "path": "/healthy"
          },
          "port": 8080,
          "preemptible": true
        }
      },
      "name": "online_carolapp"
    }]
  },
  "docker": [{
    "dockerName": "batch_carolapp-batch_carolapp_algorithm",
    "dockerTag": "0.1.0",
    "gitBranch": "app_review",
    "gitPath": "/batch_carolapp",
    "gitDockerfileName": "Dockerfile",
    "gitRepoUrl": "https://github.com/totvslabs/carolapp-samples"
  }]
}

Compreendendo o arquivo de manifesto

Esta seção explica as propriedades mais importantes no arquivo de manifesto.

Parâmetro	Descrição
batch/online	O mesmo arquivo pode especificar a configuração para o aplicativo em lote e online Carol. Isso significa que o aplicativo Carol suporta os dois tipos de aplicativo Carol, incluindo o recurso da Web, sendo implantado como um recurso separado na Carol.
algorithmDescription/algorithmTitle	Ambas as propriedades permitem especificar informações que estarão disponíveis na tela para o usuário que opera o aplicativo Carol. Essas propriedades suportam internacionalização.
algorithmName	Esta propriedade especifica o nome do algoritmo responsável por inicializar a execução do Batch Carol App ou Online Carol App.
instanceProperties	Permitir a especificação de algumas propriedades personalizadas para o aplicativo Carol. Algumas propriedades predefinidas são descritas abaixo (docker, por exemplo).
dataModels	Especifique os modelos de dados que este processo está procurando por eventos (alteração, um novo registro ou registros excluídos) para ativar a próxima tarefa agendada. Se não tiver evento, a tarefa será criada na Carol apenas para deixar claro para o usuário que o cronograma está funcionando, mas nenhuma instância e nenhum processo serão executados.
instanceProperties.properties.dockerName	A propriedade dockerName refere-se à instância direita do docker abaixo. Especificando todas as configurações relacionadas ao docker, como tag , gitBranch , gitpath, instanceType, gitDockerfilename , gitRepoUrl.
instanceProperties.properties.gitRepoUrl	A propriedade gitRepoURL refere-se ao caminho do repositório onde a imagem docker e demais fontes do Carol App se encontram e é utilizada no processo de checkout. Lembre-se de apenas colocar a URL até o local raiz do repositório, evitando colocar algum caminho específico, o que implicará em erros ao realizar o clone do repositório.
instanceProperties.properties.gitPath	A propriedade gitpath refere-se ao caminho específico onde a imagem docker do Carol App se encontra. Lembre-se de apenas colocar o caminho absoluto, logo após a raiz do repositório e sem incluir o nome do arquivo. Deste modo o processo de validação irá correr sem erros.
instanceProperties.properties.gitDockerfileName	A propriedade gitDockerfilename refere-se apenas ao nome do arquivo docker. Esta propriedade é combinada com a propriedade gitpath durante o processo de validação da build.
instanceProperties.properties.instanceType	Este é o tipo de instância para executar o processo Carol App.
instanceProperties.preemptible	O valor true especifica que a instância pode morrer subitamente e false significa que a instância é mais robusta (e cara) e não morre subitamente. Normalmente, os aplicativos em lote são aceitáveis com preemptivo como true, mas recomendamos fortemente que os aplicativos on-line usem como false preemptivo. O valor padrão é true.
name	Este é o identificador para os processos (online e batch) dentro do arquivo de manifesto.
docker	Esta seção descreve todas os dockers usados pelo arquivo de manifesto. O link acontece através do dockerName tag. Essa propriedade especifica a seguinte configuração relacionada a esta imagem docker, como tag, gitBranch, gitpath, gitRepoUrl. Essa configuração foi adicionada recentemente, após a implantação 3.7, mas os arquivos antigos do manifesto sem essa propriedade ainda são suportados.
instanceProperties.properties.autoscale	Essa configuração está disponível apenas para aplicativos online, permitindo ativar o dimensionamento automático (com base no uso da CPU), bem como as réplicas mínima e máxima que um aplicativo online deve ter.
instanceProperties.properties.autoscale.enabled	Se o aplicativo deve ser escalado automaticamente ou não. Se ativado, ele irá escalar o aplicativo se o uso médio da CPU estiver acima de 75% por algum tempo e para baixo se permanecer abaixo desse marcador por alguns minutos. O padrão é false .
instanceProperties.properties.autoscale.minReplicas	Réplicas mínimas que um aplicativo deve ter. O padrão é 1 .
instanceProperties.properties.autoscale.maxReplicas	Máximo de réplicas que um aplicativo deve ter. Deve ser maior que minReplicas e no máximo 5.
instanceProperties.properties.healthcheck.path	A configuração healthcheck está disponível apenas para aplicativos online, permitindo definir um caminho personalizado para a verificação de integridade do aplicativo. Esta configuração neste cenário torna-se <span style={{color:'red'}}>Obrigatória, pois a falta dela incorrerá em instabilidades na inicialização do aplicativo online. O padrão é /.
instanceProperties.properties.port	Personalize a porta na qual o aplicativo online escuta. O padrão é 5000.
instanceProperties.properties.command	O comando a ser executado pelo contêiner. Equivalente à propriedade Docker ENTRYPOINT.
instanceProperties.properties.args	Os argumentos passados para o comando que o contêiner executará.
instanceProperties.properties.deadline	Tempo máximo que um lote pode ser executado. Deve ser informado em segundos, minutos ou horas. Por exemplo: 40s, 15m, 1h . O limite rígido é de 24 horas.
instanceProperties.properties.environments	Contempla as variáveis de ambiente utilizadas na interface de porta de entrada do servidor web (WSGI) que definem sua capacidade de atendimento aos processos iniciados pelo aplicativo. Para Python é utilizada a implementação Gunicorn e as variáveis utilizadas tanto no seu arquivo de configuração quanto no manifesto são: workers, threads e timeout.

Exemplo de configuração da propriedade environments

Cabe ressaltar que o seu correto dimensionamento é de responsabilidade do cliente e vai depender da: quantidade de core na CPU da instância, do Carol App e da stack de tecnologia utilizada. Um mal dimensionamento poderá ocasionar problemas de sobrecarga por concorrência (requisições simultâneas) levando o aplicativo a reinicializações frequentes.

Os valores utilizados no exemplo abaixo são apenas ilustrativos e sua alteração fica a critério do cliente.

gunicorn.conf.py

-workers = 1
-threads = 16
-timeout = 240
 bind = ":5000"

O parâmetro bind vinculará o aplicativo no host local nas interfaces ipv6 e ipv4.

Dúvidas sobre este parâmetro? → Veja mais informações em Server Socket.

manifest file

             "dockerImage": "carolappprd/carolappapiprd:1.0.0",
             "instanceType": "c1.large",
             "preemptible": false
           },
           "environments": {
             "GUNICORN_CMD_ARGS": "--workers 8 --threads 16 --timeout 240"
           }
         }
       }

Dúvidas sobre a configuração das variáveis? → Veja mais informações em Worker Processes.

Tipo de Instância

A documentação a seguir compartilha todos os tipos de instância possíveis.

Especificação de uma imagem externa do Docker

Você pode especificar um nome de imagem docker externo (URL) substituindo as propriedades dockerName em instanceProperties/properties por dockerImage.

Um exemplo completo dessa configuração está disponível aqui: https://github.com/totvslabs/carolapp-samples/blob/master/online-nodejs-carolapp/ai-script/manifest.json

Variáveis de ambiente

A propriedade environments do manifesto define as variáveis de ambiente que a Carol injeta no contêiner do Carol App no momento da execução. Ela está disponível tanto para processos batch quanto online.

Importante

environments é filha direta de instanceProperties, não de instanceProperties.properties. Esse é o nível usado em todos os exemplos oficiais. Declarar a propriedade em outro nível faz com que as variáveis não cheguem ao contêiner.

manifest.json — posição correta de environments

{
  "online": {
    "processes": [
      {
        "algorithmName": "run_me",
        "name": "onlineapp",
        "instanceProperties": {
          "profile": "",
          "environments": {
            "NODE_ENV": "production",
            "LOG_LEVEL": "info",
            "APP_TIMEZONE": "America/Sao_Paulo"
          },
          "properties": {
            "dockerImage": "registry.exemplo.com/meu-app:1.0.0",
            "instanceType": "c1.large",
            "preemptible": false,
            "port": 8080,
            "healthcheck": {
              "path": "/healthz"
            }
          }
        }
      }
    ]
  }
}

Regras de uso:

• Chaves e valores são sempre string. Números e booleanos devem ser escritos entre aspas ("8080", "true").
• As variáveis valem para todos os processos daquela definição — cada processo do manifesto tem o seu próprio bloco environments.
• Alterações em environments só passam a valer em uma nova execução do processo (batch) ou após o restart do serviço (online).

Variáveis injetadas automaticamente pela Carol

Além das variáveis declaradas no manifesto, a plataforma injeta um conjunto de variáveis no contêiner. Elas são o meio oficial de a aplicação descobrir em qual tenant e ambiente está rodando:

Variável	Descrição
CAROLTENANT	Nome da tenant em que o Carol App está sendo executado.
CAROLAPPNAME	Nome do Carol App.
CAROLAPPOAUTH	Token de autenticação do Carol App, usado pela pyCarol e pelas demais integrações.
CAROLCONNECTORID	Identificador do connector associado ao Carol App.
CAROLDOMAIN / ENV_DOMAIN	Domínio/ambiente da Carol (por exemplo, produção ou QA).
LONGTASKID	Identificador da task que originou a execução. Usado para publicar logs e status na Carol.
ALGORITHM_NAME	Nome do algoritmo (algorithmName) em execução.

Importante

Não redefina essas variáveis em environments. Sobrescrevê-las quebra a autenticação da aplicação com a Carol e o envio de logs e de status da tarefa.

Dica

Para inspecionar exatamente o que chega ao seu contêiner, use o exemplo batch_carol_app_env_vars, que imprime todas as variáveis de ambiente no log da execução.

Uso do arquivo .env

É comum que aplicações (Node.js, Python, etc) carreguem sua configuração de um arquivo .env durante o desenvolvimento local. Na Carol não existe um arquivo .env dentro do contêiner: a configuração chega pela propriedade environments do manifesto, já como variável de ambiente do processo ou injetado de forma automática no início do container (destacadas acima).

O padrão recomendado é:

• Desenvolvimento local — mantenha o .env na sua máquina e carregue-o normalmente (python-dotenv, dotenv, phpdotenv etc.).
• Execução na Carol — declare as mesmas chaves em instanceProperties.environments. A aplicação continua lendo process.env / os.environ / env() sem nenhuma alteração de código.

caution

Importante — o carregamento do .env não pode ser obrigatório

Se o código exigir a existência do .env, a aplicação falha ao subir na Carol, porque o arquivo não existe no contêiner. Use sempre a variante "tolerante à ausência do arquivo" da sua biblioteca:

Stack	Chamada segura	Comportamento quando o .env não existe
Python	load_dotenv(".env")	Retorna False e segue a execução — as variáveis passam a vir do ambiente do contêiner.
Node.js	require("dotenv").config()	Retorna um objeto com error e segue a execução; process.env continua servido pelo contêiner.
PHP / Laravel	Dotenv::createImmutable(...)->safeLoad()	Não lança exceção. Evite ->load(), que interrompe a inicialização quando o arquivo não existe.

Em todas essas bibliotecas, variáveis já presentes no ambiente têm precedência sobre o .env — ou seja, o que está no manifesto vence, que é o comportamento desejado na Carol.

Importante

Não versione o .env no repositório e não coloque segredos em environments, pois o manifesto é um arquivo de texto versionado junto ao código do Carol App. Para segredos, use os Carol App Settings.

Node environment

Aplicações Node.js seguem exatamente o mesmo mecanismo: as chaves declaradas em environments ficam disponíveis em process.env. Não há nada específico da Carol a instalar — apenas o dockerImage com a sua aplicação.

manifest.json — Carol App online em Node.js

{
  "online": {
    "processes": [
      {
        "algorithmDescription": {
          "en-US": "Demo Web App using NodeJS",
          "pt-BR": "Aplicação web de exemplo em NodeJS"
        },
        "algorithmName": "run_me",
        "algorithmTitle": {
          "en-US": "Demo Web App using NodeJS",
          "pt-BR": "Aplicação web de exemplo em NodeJS"
        },
        "instanceProperties": {
          "profile": "",
          "environments": {
            "NODE_ENV": "production",
            "NODE_OPTIONS": "--max-old-space-size=768"
          },
          "properties": {
            "dockerImage": "docker.io/exemplo/node-web-app:1.0.0",
            "instanceMemory": "1",
            "instanceVCPUs": "0.5",
            "port": 5000,
            "healthcheck": {
              "path": "/healthz"
            },
            "preemptible": false
          }
        },
        "name": "onlineapp"
      }
    ]
  }
}

server.js

const express = require('express');
 
const app = express();
const PORT = process.env.PORT || 5000;
const HOST = '0.0.0.0'; // obrigatório: 127.0.0.1 não recebe tráfego do contêiner
 
app.get('/healthz', (req, res) => res.status(200).send('ok'));
 
app.get('/', (req, res) => {
  res.send(`Rodando em ${process.env.CAROLTENANT} (${process.env.NODE_ENV})`);
});
 
app.listen(PORT, HOST);

Importante

A aplicação precisa escutar em 0.0.0.0 e na mesma porta declarada em instanceProperties.properties.port (padrão 5000). Escutar apenas em localhost/127.0.0.1 faz o contêiner subir sem receber tráfego, e o health check falha.

Exemplo completo

Um Carol App online em Node.js está disponível em online-nodejs-carolapp.

Health check

O health check é o endpoint HTTP que a Carol consulta periodicamente para decidir se uma réplica do aplicativo online está saudável. Réplicas que não respondem com sucesso são reiniciadas.

A configuração fica em instanceProperties.properties.healthcheck.path:

manifest.json

"properties": {
  "dockerImage": "registry.exemplo.com/meu-app:1.0.0",
  "port": 8080,
  "healthcheck": {
    "path": "/healthz"
  }
}

Importante

Ainda que o valor padrão seja /, declarar explicitamente o healthcheck.path é fortemente recomendado. A ausência da configuração — ou um caminho que não responde com sucesso — provoca instabilidade e reinicializações na subida do aplicativo online.

Aplicativos Python com pyCarol

Carol Apps online construídos com a pyCarol (OnlineApi) já expõem os endpoints de infraestrutura, sem que você precise implementá-los:

• /healthz — verificação de integridade;
• /statusz — status da aplicação;
• /logs — logs da aplicação. Nesse caso, basta apontar o manifesto para /healthz.

Aplicativos com stack própria (Node.js, PHP, Java, Go…)

Quando o Carol App usa uma imagem própria, o endpoint de health check é responsabilidade da aplicação. Requisitos:

1. Responder no caminho declarado em healthcheck.path, na porta declarada em port.
2. Retornar HTTP 200 quando a aplicação estiver pronta para receber tráfego.
3. Não exigir autenticação — a verificação é feita internamente, sem credenciais.
4. Ser leve e rápido: não consultar banco de dados, storage ou APIs externas. O endpoint responde sobre o processo, não sobre as dependências dele.

Flask

@app.route("/healthz")
def healthz():
    return "ok", 200

Laravel — routes/web.php

Route::get('/healthz', fn () => response('ok', 200));

Importante — redirecionamentos

Frameworks que forçam HTTPS ou aplicam redirecionamento global (por exemplo, o URL::forceScheme('https') / middleware de redirect do Laravel) fazem o endpoint de health check responder com um redirecionamento em vez de 200, e a aplicação passa a ser reiniciada em ciclo.

Exclua a rota de health check de qualquer regra de redirecionamento ou de autenticação. Se a sua aplicação depende do cabeçalho X-Forwarded-Proto para decidir o esquema, configure os trusted proxies do framework antes de ativar o redirecionamento.

Variáveis de ambiente x Carol App Settings

São dois mecanismos diferentes e não intercambiáveis:

	instanceProperties.environments (manifesto)	Carol App Settings (tela do app)
Onde é definido	No manifest.json, versionado no repositório	Na aba Settings do Carol App, na interface da Carol
Quem altera	Time de desenvolvimento, via novo build/deploy	Usuário administrador da tenant, sem novo deploy
Como a aplicação lê	Variável de ambiente (os.environ, process.env, env())	API da Carol, normalmente via pyCarol
Varia por tenant	Não	Sim
Indicado para	Configuração técnica da execução e do runtime	Parâmetros de negócio, credenciais e valores por cliente

Importante

Os valores configurados na tela Settings do Carol App não são convertidos em variáveis de ambiente do contêiner. Eles não aparecem em os.environ / process.env e precisam ser lidos explicitamente pela aplicação através da pyCarol.

Lendo os Carol App Settings com pyCarol

import os
from pycarol import Carol, Apps
 
carol = Carol(environment=os.environ['ENV_DOMAIN'])
 
settings = Apps(carol).get_settings()
 
webhook_url = settings.get('data_validation_webhook')

Dica

Precisa de um valor de setting em uma aplicação que não é Python? Leia o setting pela API da Carol na inicialização do processo e exporte-o para o ambiente da sua aplicação no entrypoint do contêiner, usando o CAROLAPPOAUTH injetado pela plataforma.

Possíveis incidentes

Se algo der errado, você verá a seguinte tela:

O problema mais comum é especificar a versão latest para pyCarol. É obrigatório especificar uma versão, pois hoje (23/02/2020) a versão mais recente e estável é a 2.30.0.