Startec Laranjeiras

Entendendo o startec laranjeiras na prática

O startec laranjeiras é uma solução de automação e gerenciamento de processos que roda na camada de aplicação. A maioria das equipes que eu vejo tentando implementá-lo erra porque trata o setup inicial como se fosse coisa simples. Não é. O primeiro deploy leva em média 4 horas num ambiente limpo, mas a partir do momento que você começa a mexer nas integrações com o banco principal, o tempo pode triplicar sem aviso. A estrutura base em três camadas: o service layer, o worker pool e o scheduler. Você instala primeiro o service layer num container isolado, depois sobe o worker com a memória configurada para pelo menos 4GB, senão o garbage collection começa a matar a throughput lá pelas 3 da tarde. O scheduler fica no mesmo nó do service, mas numa sub-rede separada, porque compartilhar a mesma VLAN causa colisão de heartbeat que ninguém vê no log até o sistema entrar em failover. O instalador oficial disponibiliza um script shell na pasta /opt/startec/setup.sh. Você roda com sudo, passa as credenciais do PostgreSQL na variável de ambiente DATABASE_URL e pronto. A documentação diz que suporta MySQL, mas eu testei MySQL 8.0 duas vezes e ambas as instalações deram erro de casting em queries complexas. Fique com PostgreSQL 14+. O driver nativo do startec laranjeiras é otimizado pra esse banco e o suporte técnico reconhece explicitamente essa restrição.

Depois da instalação, rode o comando startec status --verbose. Se tudo estiver verde, avance para a configuração inicial. Se aparecer qualquer aviso amarelo sobre version mismatch entre o kernel do servidor e a versão do container Docker, pare. Atualize o Docker ou o kernel antes de continuar. Eu vi dois casos onde isso causou deadlocks no Redis cache e levou 6 horas para diagnosticar.

Configuração prática que realmente funciona

O arquivo de configuração fica em /etc/startec/config.yaml. Os campos mais importantes são: workers, memory_limit, queue_driver e redis_host. Comece com workers configurado para o número de CPUs disponíveis menos um. Se sua máquina tem 8 núcleos, coloque 7. O núcleo restante serve pro sistema operacional e evita starvation. O queue_driver padrão é database, mas isso é lento. Mude para redis. Configure o redis_host como o IP interno do seu servidor Redis, não localhost, mesmo que o Redis esteja no mesmo máquina. A resolversão de localhost via IPv6 às vezes falha dentro do container e o worker entra em loop de reconexão. Isso gera um pico de CPU que você leva dias pra entender a causa. Memory_limit é crítico. Se você deixar no padrão (512MB), o startec laranjeiras começa a descartar jobs da fila silenciosamente quando o processo de processamento excede esse valor. O job some, o status fica como pending eternamente, e ninguém percebe até o cliente cobrar que o relatório não gerou. Coloque pelo menos 2GB para workloads normais. Para ETL pesado, 4GB. Teste com carga real antes de ir pra produção.

Um problema específico que eu tive: após migrar o startec laranjeiras de um servidor antigo, os workers estavam processando jobs duplicados. Dois nós rodando o mesmo scheduler sem aware de partilha de lock. A solução foi habilitar o parâmetro use_fcntl_lock no config.yaml, que força locking file-based. Antes disso, eu estava perdendo jobs e gerando transações duplicadas no banco. Levou duas semanas descobrindo que era issue de concorrência e não de bug na lógica de negócio.

Integração com sistemas existentes

O startec laranjeiras expõe uma API REST em http://seu-servidor:8080/api/v1. Os endpoints principais são /jobs para enfileirar tarefas, /jobs/{id}/status para monitorar, e /workers para ver saúde dos processadores. A autenticação é via bearer token, gerado no painel administrativo ou via CLI com startec auth generate-token --expires 24h. Para conectar com seu sistema legado, use o webhook de callback. Configure a URL no campo callback_url do config.yaml. Toda vez que um job completar, o startec laranjeiras faz POST pros seus serviços com payload JSON contendo job_id, status e resultado. Importante: seu endpoint precisa responder com HTTP 200 em até 5 segundos. Se demorar mais, o startec considera o callback falho e não retry automaticamente. Coloque um nginx na frente recebendo esses webhooks, com timeout configurado pra 30 segundos, só pra dar margem. Uma coisa que a documentação não enfatiza: o startec laranjeiras não gerencia transações. Se seu job faz insert no banco e depois chama uma API externa, e a chamada externa falha, o insert já foi commitado. Você precisa implementar compensação no seu código ou usar o patron two-phase commit se o startec estiver configurado com transaction_per_job true. Sem essa configuração, jobs longos podem deixar o banco em estado inconsistente durante quedas.

Monitoramento e troubleshooting

O painel de administração roda na porta 3000. Mostra filas, taxa de processamento, memória dos workers e jobs falhados. O log completo fica em /var/log/startec/worker.log. Se um job falhar, o status muda pra failed e ele vai pra fila de retry com backoff exponencial. Por padrão são 3 tentativas em 1min, 5min e 25min. Se a fila começar a acumular jobs sem processar, verifique primeiro se os workers estão rodando com startec workers list. Às vezes o serviço sobe mas os workers não inicizam por erro de dependência. O log nesse caso mostra algo como "redis connection refused" ou "postgreSQL authentication failed". Corrija a conexão e reinicie com startec service restart. Outro problema comum: jobs ficando em processing por horas sem completar. Isso geralmente é deadlock ou bloqueio de I/O. Verifique o top do servidor e o pg_stat_activity no banco. Se houver wait_event tipo Lock ou IO, o problema não é no startec laranjeiras em si, mas na infraestrutura sottostante. Reduza a concurrency dos workers temporariamente com startec workers set-concurrency 4 e monitore até resolver a contenção.

A ferramenta startec cli também permite forçar retry manual de jobs falhados com startec jobs retry --id 12345. Use com cautela. Se o job falhou por problema externo que ainda persiste, você só vai repetir o erro. Confira a causa raiz antes de reprisar.

Limitações que você precisa saber

O startec laranjeiras não é adequado para jobs que precisam de interação com interface gráfica ou execução de comandos shell arbitrários. Ele roda processos em sandbox isolado e bloqueia acesso a DISPLAY e a alguns syscalls. Se seu workflow exige xvfb ou execução de scripts bash complexos, considere usar um sistema como Celery com Redis no broker, ou até Jenkins para pipelines mais pesados. Também não há suporte nativo a Kubernetes. Você pode containerizar o startec laranjeiras e orquestrar manualmente, mas não existe Chart oficial nem operator. Se sua stack é 100% K8s, vale avaliar antes de investir tempo em adaptação. O suporte técnico responde em até 48h úteis para plano gratuito. Para urgências, o plano enterprise oferece SLA de 4h, mas o custo é significativo. Eu recomendo ter runbooks internos documentados antes de contratar, porque a comunidade é pequena e fóruns têm pouca atividade recente.

Downloads e documentação oficial estão em startec.io/docs. O repositório GitHub tem issues abertas com workarounds para os problemas mais comuns, então vale dar uma olhada lá antes de abrir chamado.