Online App

Um Carol App online permite hospedar código na infraestrutura da Carol a partir de uma imagem Docker, mantendo uma aplicação disponível para receber requisições HTTP. A imagem reúne o servidor, o código da aplicação e suas dependências. A linguagem e as ferramentas utilizadas são definidas pelo projeto e empacotadas nessa imagem.

Esse formato pode ser utilizado para APIs, serviços de consulta, processamento de requisições e integrações que precisam de um endpoint disponível continuamente.

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, instalar as dependências e iniciar o servidor da aplicação. O procedimento está descrito em Build e atualização.

Configuração e disponibilidade

O manifesto associa o processo à imagem Docker e define os recursos, as variáveis de ambiente, a porta HTTP e o caminho do healthcheck. Essas configurações são descritas em Manifesto e configuração.

Com o manifesto configurado e o build concluído, o serviço pode ser iniciado na aba Process. A Carol utiliza a imagem para criar o contêiner da aplicação. O servidor deve permanecer ativo e escutar na porta declarada no manifesto.

A Carol encaminha as requisições para essa porta e consulta o healthcheck, uma rota HTTP que indica se o serviço está respondendo. A aplicação é responsável por implementar essa rota e os endpoints de negócio.

Exemplo prático

O exemplo desta página implementa um servidor Python com duas rotas: /, que retorna uma mensagem, e /healthz, que informa se o servidor está respondendo. A aplicação não acessa dados da tenant e pode ser executada localmente sem credenciais da Carol.

O projeto contém três arquivos:

Arquivo	Responsabilidade
server.py	Inicia o servidor HTTP e implementa as rotas.
Dockerfile	Define a imagem Docker e o comando que inicia o servidor.
manifest.json	Configura a imagem, os recursos, a porta e o healthcheck na Carol.

Os arquivos completos estão disponíveis nos blocos expansíveis desta página. A execução local permite verificar as respostas HTTP 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/online. Para utilizar os downloads em um projeto próprio, mantenha a mesma organização:

static/examples/carol-apps/
└── online/
    ├── server.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 server.py do diretório utilizado como contexto do build, que nos comandos abaixo é ./online.

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. Por padrão, o servidor utiliza a porta 8080 e retorna a mensagem Olá, Carol!:

cd static/examples/carol-apps
python3 online/server.py

Com o servidor em execução, as rotas podem ser consultadas em outro terminal:

curl -i http://localhost:8080/healthz
curl -i http://localhost:8080/

As duas chamadas devem retornar HTTP 200. O healthcheck retorna {"status": "ok"} e a raiz retorna {"message": "Olá, Carol!"}. O servidor permanece ativo até ser encerrado com Ctrl+C.

As variáveis de ambiente PORT e GREETING permitem alterar a porta e a mensagem. A seção Porta e healthcheck apresenta a configuração desses valores no manifesto.

Código completo e Dockerfile

Baixar server.py

online/server.py

"""Servidor de demonstração sem dependências externas."""

import json
import os
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from urllib.parse import urlsplit


class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        path = urlsplit(self.path).path
        if path == "/healthz":
            status, payload = 200, {"status": "ok"}
        elif path == "/":
            status, payload = 200, {"message": os.environ.get("GREETING", "Olá, Carol!")}
        else:
            status, payload = 404, {"error": "not_found"}

        body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
        self.send_response(status)
        self.send_header("Content-Type", "application/json; charset=utf-8")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)


if __name__ == "__main__":
    port = int(os.environ.get("PORT", "8080"))
    server = ThreadingHTTPServer(("0.0.0.0", port), Handler)
    print(f"Servidor iniciado na porta {port}", flush=True)
    try:
        server.serve_forever()
    except KeyboardInterrupt:
        pass
    finally:
        server.server_close()

Baixar Dockerfile

online/Dockerfile

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

O servidor utiliza a biblioteca padrão do Python para demonstrar o ciclo de desenvolvimento. Em produção, o servidor HTTP, a concorrência, os timeouts e a autenticação dos endpoints de negócio devem ser definidos conforme os requisitos da aplicação.

Execução com Docker

Encerre o servidor Python com Ctrl+C para liberar a porta. A partir de static/examples/carol-apps, execute:

docker build -t carol-demo-online:1.0.0 ./online
docker run --rm --name carol-demo-online -p 8080:8080 \
  -e PORT=8080 -e GREETING="Olá, Carol!" carol-demo-online:1.0.0

Repita as chamadas curl em outro terminal. Para encerrar:

docker stop carol-demo-online

O mapeamento -p 8080:8080 permite acessar o servidor do contêiner por localhost:8080: o primeiro número é a porta da máquina local, e o segundo é a porta do contêiner. EXPOSE documenta a porta da imagem. Na Carol, o encaminhamento usa a configuração do processo.

Porta e healthcheck

As configurações de porta e healthcheck são declaradas em online.processes[].instanceProperties:

Trecho do processo online

{
  "environments": {"PORT": "8080", "GREETING": "Olá, Carol!"},
  "properties": {
    "dockerName": "carol-demo-online",
    "port": 8080,
    "healthcheck": {"path": "/healthz"}
  }
}

O servidor deve escutar em 0.0.0.0, na porta declarada em properties.port. O endpoint de healthcheck deve responder HTTP 200, sem autenticação nem redirecionamento.

Nesse exemplo, PORT configura a porta utilizada pelo código, enquanto properties.port informa à Carol para onde encaminhar as requisições. Os dois valores devem coincidir.

Manifesto completo para download

Este manifesto contém apenas o processo online. 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 online

manifest.json

{
  "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-online",
      "dockerTag": "1.0.0",
      "gitRepoUrl": "https://github.com/SUA_ORGANIZACAO/SEU_REPOSITORIO",
      "gitBranch": "main",
      "gitPath": "/static/examples/carol-apps/online",
      "gitDockerfileName": "Dockerfile"
    }
  ]
}

Requisitos e diagnóstico do healthcheck

Implemente a rota declarada em healthcheck.path e mantenha a resposta rápida. Evite consultas demoradas a banco, storage ou APIs externas nessa rota. Se houver uma etapa de inicialização, responda com sucesso apenas quando ela terminar.

Se o framework aplica autenticação global ou força HTTPS, exclua o healthcheck dessas regras. O acesso externo ao app pode ter controles da Carol, mas a rota dentro do contêiner precisa responder à verificação interna.

O endereço 0.0.0.0 permite ao servidor receber conexões pelas interfaces de rede do contêiner. Um servidor que escuta apenas em 127.0.0.1 fica acessível somente dentro do próprio contêiner e não recebe as chamadas encaminhadas pela Carol.

Se o serviço reiniciar ou não ficar disponível, confira os logs, a porta, o endereço de escuta, a resposta do healthcheck e a memória disponível.

Inicialização na Carol

Após concluir o build da definição carol-demo-online, abra Process, selecione online_demo e inicie o serviço.

Quando o serviço estiver disponível, consulte / pela URL fornecida pela Carol e verifique a mensagem retornada. Alterações em GREETING exigem o envio do manifesto atualizado e o reinício do processo. Alterações no código exigem um novo build. As demais configurações estão descritas em variáveis de ambiente e Settings.

💡 Dicas e acesso

Se a preparação (build) ou a inicialização do aplicativo demorar mais do que o esperado, tente novamente selecionando outra instância, de preferência com mais recursos. Isso pode ajudar a concluir a etapa.

Padrão da URL gerada para o app online: https://<tenantname>-<appname>.apps.carol.ai