Tarefas e execução única

Nem todo código fica rodando. Migration, seed, preflight de release e relatório rodam, terminam e pronto. Veja onde colocar cada um.

Qual usar

  • Fica rodando e recebe visita: app web.
  • Fica rodando sem receber visita (bot, fila, agente): app worker.
  • Precisa rodar a cada deploy (migration): antesDeIniciar no lumahost.json.
  • Roda uma vez e termina (preflight, seed, relatório, conferir migrations): Executar uma vez.

Worker é processo contínuo

A plataforma espera que o worker fique rodando. Quando o processo termina, seja por erro, seja porque acabou o trabalho, ela sobe o processo de novo. E de novo, para sempre. Uma tarefa que roda e termina, publicada como worker, nunca para.

Quando isso acontece em sequência, o app aparece como Reiniciando em ciclo. Parar e Reiniciar continuam disponíveis, e o log de execução mostra o que o processo fez antes de encerrar, mesmo com o container reiniciando ou parado.

Executar uma vez

Roda a imagem do último deploy do app uma única vez, com as variáveis atuais do painel, sem reinício automático. Quando o comando termina, acabou.

  • Você pode informar um comando, escrito como no terminal (&& e aspas funcionam). Sem comando, roda o start do app (com o antesDeIniciar antes, se o app tiver um), e um app web ou worker que fica rodando só para no limite de tempo.
  • Usa as variáveis como estão agora no painel. Uma variável criada depois do último deploy já vale na execução.
  • O código é o do último deploy com sucesso. Mudou o código? Faça um novo deploy antes.
  • Roda com a mesma RAM e CPU do app e na mesma rede, então enxerga os bancos da conta pela URL interna.
  • Limite de 10 minutos. Passou disso, a execução é encerrada.
  • Uma execução por vez em cada app, e até 20 por hora na conta.
  • Vale para apps web e worker. Precisa de pelo menos um deploy com sucesso.
  • O resultado fica no painel, na página do app, em Executar uma vez: início, fim, código de saída e a saída do comando. Código de saída 0 é sucesso. Saída muito longa fica só com o final (as últimas 2.000 linhas). Valores de variáveis sensíveis aparecem como <REDACTED>, como nos logs.
  • Nada fica guardado no disco: o que a execução gravar em arquivo some quando ela termina. Grave no banco.

Exemplos de comando:

npm run preflight
npm run seed
npm run migrate:status
python manage.py relatorio_mensal

Onde usar

  • Painel: na página do app, em Executar uma vez.
  • MCP: peça ao assistente, por exemplo "rode o preflight uma vez e me mostre a saída". As ferramentas são executar_uma_vez e ver_execucao. Veja MCP.
  • API: o mesmo recurso, com o seu token: POST /api/cloud/v1/apps/{id}/execucoes com {"comando": "npm run seed"} inicia, e GET /api/cloud/v1/apps/{id}/execucoes/{execucaoId} mostra o resultado.

E as migrations?

Migration precisa rodar a cada deploy, antes da versão nova atender alguém. Para isso, o caminho recomendado é o campo antesDeIniciar no lumahost.json. Se a migration falhar, o deploy falha e a versão anterior continua no ar; a saída do comando aparece no log do deploy.

Executar uma vez serve para conferir o estado (npm run migrate:status) ou para rodar algo pontual, como um seed.

Não existe terminal no container. Para rodar um comando, use Executar uma vez.