Manifesto e configuração
O arquivo manifest.json define os processos, as imagens Docker e as configurações de execução do Carol App. Um mesmo manifesto pode conter processos batch, online ou ambos.
Estrutura do manifesto
A estrutura resumida apresenta os blocos principais. Os manifestos completos estão disponíveis nas páginas de Batch App e Online App.
{
"batch": {"processes": []},
"online": {"processes": []},
"docker": []
}
Os blocos batch.processes e online.processes contêm listas de processos. O bloco docker contém as definições de build das imagens. Na referência dos campos, a notação [] indica um item dessas listas.
O campo instanceProperties.properties.dockerName associa o processo a uma imagem. Seu valor deve corresponder ao dockerName de uma definição em docker[]. Por exemplo, o processo batch utiliza carol-demo-batch, que também identifica sua definição de build.
Referência dos campos do processo
Os caminhos abaixo são relativos a cada item de batch.processes[] ou online.processes[].
| Campo | Uso |
|---|---|
name | Identificador do processo no manifesto. Use nomes distintos para facilitar a operação. |
algorithmName | Identificador do algoritmo associado à execução. Para imagens próprias, declare a inicialização no Dockerfile ou em command/args. |
algorithmTitle, algorithmDescription | Título e descrição exibidos na interface, com traduções como pt-BR e en-US. |
dataModels | Em batch, modelos acompanhados por agendamentos baseados em alterações nos dados. O exemplo usa [], sem essa condição. |
instanceProperties | Configurações de execução do processo. Contém environments e properties como propriedades irmãs. |
instanceProperties.environments | Mapa de variáveis de ambiente do processo. Chaves e valores devem ser strings. |
instanceProperties.properties.dockerName | Referência a uma entrada de docker[] com o mesmo dockerName. |
instanceProperties.properties.dockerImage | Alternativa a dockerName: referência completa de uma imagem já publicada em um registry acessível à Carol, incluindo a tag. |
instanceProperties.properties.instanceType | Recursos da instância que executará o processo. Consulte os tipos de instância e a disponibilidade na sua tenant. |
instanceProperties.properties.preemptible | Permite instâncias sujeitas a interrupção quando true. Os exemplos usam false; rotinas batch que usam instâncias interrompíveis precisam tolerar reexecução. |
instanceProperties.properties.command, args | Comando e argumentos que substituem a inicialização da imagem. Omita para utilizar a inicialização do Dockerfile, como nos exemplos. |
instanceProperties.properties.deadline | Em batch, duração máxima, por exemplo 40s, 15m ou 1h, respeitando o limite de 24 horas. |
instanceProperties.properties.port | Em online, porta HTTP do contêiner. Deve coincidir com a porta em que o servidor realmente escuta. |
instanceProperties.properties.healthcheck.path | Em online, caminho do endpoint de integridade. Declare explicitamente; o exemplo usa /healthz. |
instanceProperties.properties.autoscale | Em online, configura a escala com enabled, minReplicas e maxReplicas. O exemplo desabilita a escala automática para a primeira validação. |
Manifesto completo com batch e online
Baixar manifest.json combinado
{
"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"
}
}
}
]
},
"online": {
"processes": [
{
"name": "online_demo",
"algorithmName": "online_demo",
"algorithmTitle": {"pt-BR": "API de exemplo", "en-US": "Example API"},
"algorithmDescription": {"pt-BR": "Responde a requisições HTTP.", "en-US": "Handles HTTP requests."},
"instanceProperties": {
"profile": "",
"environments": {"PORT": "8080", "GREETING": "Olá, Carol!"},
"properties": {
"dockerName": "carol-demo-online",
"instanceType": "c1.nano",
"preemptible": false,
"port": 8080,
"healthcheck": {"path": "/healthz"},
"autoscale": {"enabled": false, "minReplicas": 1, "maxReplicas": 2}
}
}
}
]
},
"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"
},
{
"dockerName": "carol-demo-online",
"dockerTag": "1.0.0",
"gitRepoUrl": "https://github.com/SUA_ORGANIZACAO/SEU_REPOSITORIO",
"gitBranch": "main",
"gitPath": "/static/examples/carol-apps/online",
"gitDockerfileName": "Dockerfile"
}
]
}
Variáveis de ambiente
As variáveis de ambiente são declaradas em instanceProperties.environments, no mesmo nível de properties. Todos os valores devem ser strings, inclusive números e booleanos.
{
"environments": {"ITEM_LIMIT": "3"},
"properties": {"dockerName": "carol-demo-batch"}
}
A aplicação acessa esses valores por os.environ em Python ou process.env em Node.js e realiza a conversão para o tipo necessário. No exemplo batch, ITEM_LIMIT chega como texto e é convertido para inteiro pelo código.
Cada processo recebe as variáveis declaradas em seu próprio bloco environments. A atualização dos valores exige o envio do manifesto e uma nova execução batch ou o reinício do serviço online, sem necessidade de reconstruir a imagem.
Arquivo .env no desenvolvimento local
O exemplo online pode utilizar o seguinte arquivo local:
PORT=8080
GREETING=Olá, Carol!
Com a imagem já construída, os valores podem ser fornecidos pelo Docker:
docker run --rm -p 8080:8080 --env-file .env carol-demo-online:1.0.0
Os exemplos não carregam .env diretamente. Na Carol, as variáveis chegam pelo ambiente do processo; a plataforma não cria esse arquivo para o app. Se usar uma biblioteca de .env, permita que o arquivo esteja ausente e preserve os valores recebidos do ambiente.
Mantenha .env fora do Git e do contexto de build, usando .gitignore e .dockerignore.
Variáveis de ambiente e Settings
Variáveis de ambiente atendem à configuração técnica do processo, como porta e nível de log. Carol App Settings permitem definir parâmetros por tenant. A aplicação consulta os Settings pela API ou pelo SDK; esses valores não são convertidos automaticamente em variáveis de ambiente.
Contexto de execução e acesso aos Settings
A Carol também fornece contexto de execução, como CAROLTENANT, CAROLAPPNAME e CAROLAPPOAUTH. Não sobrescreva essas chaves no manifesto nem registre tokens ou todas as variáveis de ambiente nos logs. A disponibilidade de outras variáveis depende do contexto de execução e da integração utilizada; confira os requisitos do SDK ao adicioná-lo ao projeto.
| Configuração | Como definir | Como ler |
|---|---|---|
| Configuração técnica do processo, como porta e nível de log | instanceProperties.environments no manifesto. | Ambiente do processo. |
| Parâmetros do app configuráveis por tenant | Carol App Settings, com as chaves de configuração definidas para o app. | API da Carol ou SDK, como pyCarol. |
Os Settings não são convertidos automaticamente em variáveis de ambiente. O código precisa consultá-los. Mantenha credenciais fora do manifesto versionado e da imagem; utilize o mecanismo de configuração e acesso a segredos disponível no seu ambiente. Para integrar o app à plataforma em Python, consulte a pyCarol.
Imagem publicada em um registry
O campo dockerImage permite utilizar uma imagem já publicada em um registry acessível à Carol. Ele substitui dockerName e dispensa o build dessa imagem na plataforma.
Configuração com dockerImage
O trecho abaixo substitui o bloco properties de um processo online. A referência deve ser ajustada para a imagem da aplicação:
{
"dockerImage": "docker.io/SUA_ORGANIZACAO/carol-demo-online:1.0.0",
"instanceType": "c1.nano",
"preemptible": false,
"port": 8080,
"healthcheck": {"path": "/healthz"}
}
Remova a definição de docker[] que deixou de ser usada e confirme o acesso da plataforma ao registry antes de iniciar o processo. Não inclua credenciais na referência da imagem.
O procedimento de construção de imagens está descrito em Build e atualização. Os requisitos de integridade do serviço estão em healthcheck online.