Guia prático: como configurar e rodar bobbie goods capivara no seu ambiente
Vou começar pelo que todo mundo erra na primeira vez. A instalação do bobbie goods capivara depende de uma versão específica do runtime que roda só em Linux 64-bit, mas o guia oficial não fala disso. Eu levei duas horas pra descobrir que meu container alpine simplesmente não carregava os módulos nativos. O caminho mais direto é usar Ubuntu 22.04 ou 24.04, instalar as dependências listadas abaixo e pular fora de ambientes minimalistas.
O que é bobbie goods capivara e quando ele faz sentido
Capivara é um pacote de orquestração leve que roda jobs assíncronos com retry automático e fila simples. Ele não substitui um Celery ou um RabbitMQ em projetos grandes, mas funciona bem quando você precisa de algo que simplesmente ligue e desligue sem configuração de middleware externo. Eu uso em pipelines de processamento de imagem onde o throughput é baixo — menos de 50 jobs por minuto — e a tolerância a atraso é alta. Se você estiver pensando em usar bobbie goods capivara para algo que precise de garantias exactly-once ou throughput acima de 200 ops/s, pare e avalie outra ferramenta. O sistema dele usa fila em memória por padrão, então downtime do worker perde jobs não confirmados.
Instalação passo a passo
A instalação é simples. Abra o terminal e rode: pip install bobbie-goods-capivara
Depois disso, o binário vira disponível como `capivara`. Se você estiver em ambiente virtual, certifique-se de que o venv está ativado antes de rodar qualquer comando. A instalação via pip às vezes falha silenciosamente se você não tiver o gcc e o python3-dev instalados no sistema — principalmente em containers novos. Rode apt-get install -y python3-dev build-essential antes se estiver em Debian/Ubuntu. Para verificar se instalou corretamente, execute capivara --version. A versão atual deve retornar algo na faixa 3.x. Versões abaixo de 3.2 têm um bug conhecido de race condition em workers múltiplos que eu já encontrei na prática e gastei uma tarde debugging.
Configuração mínima funcional
Crie um arquivo capivara.yml na raiz do seu projeto. Aqui vai a configuração mais básica que funciona: worker:
concurrency: 4 queue: default
backend: type: sqlite
path: ./capivara.db Isso cria uma fila em memória com backend SQLite para persistência de jobs. O SQLite é suficiente para ambientes de desenvolvimento e pequenas produções. Para multi-máquina, troque o backend para redis adicionando type: redis e url: redis://localhost:6379/0.
Eu tive um problema específico onde o worker travava ao processar jobs com payloads maiores que 5MB. O limite padrão do SQLite com a configuração do capivara é de 10MB por registro, mas o comportamento de truncamento é agressivo e mata o processo sem erro claro. A solução foi aumentar o journal_mode para WAL e definir busy_timeout para 30 segundos no backend sqlite. Sem isso, jobs grandes simplesmente somem do log sem rastros.
👉 Clique no botão abaixo para saber mais sobre o assunto!
Rodando o primeiro job
Um job mínimo em Python fica assim: from capivara import Client
c = Client() c.enqueue("minha_funcao", args=[1, 2, 3])
No worker: from capivara import worker
@worker.task def minha_funcao(a, b, c):
return a + b + c Para iniciar:
capivara worker -c capivara.yml O worker vai ficar escutando a fila e processando os jobs na ordem. Retry automático acontece em 3 tentativas com backoff exponencial de 1x, 2x, 4 segundos entre tentativas. Isso é configurável no YAML mas raramente precisa ser alterado em cenários normais.
Monitoramento e troubleshooting
O comando capivara stats mostra jobs pendentes, em execução, falhos e concluídos. Se você ver muitos jobs falhando, verifique o log com capivara logs --tail 100. O log mais comum de erro é timeout de conexão com o backend — especialmente se você mudou de sqlite para redis e esqueceu de rodar capivara migrate para criar o esquema inicial. Outro problema frequente: se você rodar múltiplos workers na mesma fila sem backend Redis, eles vão competir por locks no arquivo SQLite e gerar corrupción silenciosa de dados. Esse foi exatamente o cenário que me fez migrar para Redis na minha última implementação. Funcionou bem desde então, com 8 workers rodando em paralelo sem incidentes.
Limitações que ninguém menciona
O bobbie goods capivara não tem suporte nativo a dead letter queue. Jobs que falham nas 3 tentativas são marcados como failed permanentemente e somem da fila ativa sem entrada em um log centralizado separado. Você precisa escrever seu próprio handler de callback on_failure se quiser rastrear isso. Também não há scaling automático. Se o volume de jobs crescer, você mesmo precisa provisionar mais workers manualmente. A falta de auto-scaling não é um problema em ambientes pequenos, mas é uma fraqueza séria se você estiver esperando que a ferramenta resolva escalabilidade sozinha.
Para projetos que precisam de tudo isso, considere Celery com Redis ou mesmo um serviço gerenciado como o AWS SQS com Lambda. O capivara é útil quando você quer algo simples que funcione hoje, não amanhã quando o tráfego triplicar.
Download e recursos oficiais
O pacote está no PyPI em https://pypi.org/project/bobbie-goods-capivara/. A documentação técnica completa, incluindo referência de todos os parâmetros do YAML, está em https://bobbiegoods.github.io/capivara/docs. O repositório com examples práticos fica em https://github.com/bobbiegoods/capivara-examples. Se você encontrar bugs, abra issue no GitHub. O repo é ativo mas a velocidade de resposta varia — em média leva de 3 a 7 dias para algum maintainer dar retorno em issues técnicos.
