Visão geral
O Guaraci é um orquestrador de downloads de dados públicos: ele se conecta diretamente às fontes oficiais — DATASUS (FTP de microdados), catálogo aberto do Ministério da Saúde (OpenDataSUS/DEMAS), IBGE (API SIDRA), NASA (POWER, FIRMS, GPM) e gov.br (SNIS/SINISA) — e entrega os dados prontos para uso em CSV, Parquet ou SQLite.
Três princípios guiam o projeto:
- Fonte primária, sempre. O Guaraci nunca busca em espelhos ou curadorias de terceiros: cada base vem do sistema oficial que a produz. Você recebe o dado com a atualização que a fonte tiver publicado, rastreável até a origem.
- Fidelidade ao dado original. A coleta preserva o conteúdo publicado — a conversão de formatos técnicos (como o
.dbcdo DATASUS) não altera os valores. - Docker-first. O caminho oficialmente suportado roda em um contêiner Docker: o ambiente é idêntico em qualquer máquina, sem conflito de dependências.
Duas portas de entrada, mesma engine: a interface web (formulários no navegador, sem código) e a linha de comando guaraci fetch (para automação e scripts). As duas leem o mesmo schema de parâmetros documentado no catálogo.
1 · Instalação
Você precisa de dois programas gratuitos: Git (copia o projeto) e Docker Desktop (roda o Guaraci). Instale ambos com as opções padrão e deixe o Docker Desktop aberto.
1.1 Copie o projeto
Abra o terminal (no Windows, procure por PowerShell no menu Iniciar) e digite:
1.15 Verifique o Docker antes de continuar
A causa mais comum de falha na instalação é o Docker Desktop não estar pronto (fechado, ainda abrindo, ou engine sem responder) — não um problema do Guaraci. Rode o diagnóstico abaixo primeiro, sempre que algo travar:
No Linux/macOS: ./scripts/desktop/check-docker.sh. O script diz exatamente o que está falho e como corrigir — se ele passar ([OK] em tudo) e o Guaraci mesmo assim der erro, o problema é do Guaraci, não do Docker.
1.2 Monte a imagem (uma única vez)
docker build --no-cache -t guaraci ..1.3 Ligue o Guaraci
Jeito recomendado (Windows) — o launcher sobe o contêiner, espera o health check e abre a interface sozinho:
No Linux/macOS: ./scripts/desktop/start-guaraci.sh. Para conferir o status, status-guaraci; para desligar, stop-guaraci.
Jeito manual (útil para depurar — o terminal fica exibindo os logs; Ctrl+C encerra):
-v "${PWD}:/app"). Sem ele, downloads e manifestos são perdidos quando o contêiner encerra.1.4 Confira se está tudo funcionando
1.5 Problemas comuns
| Sintoma | Solução |
|---|---|
500 Internal Server Error / ...docker...ping ao rodar docker build ou docker run | O Docker Desktop não está pronto, não o Guaraci. Rode .\scripts\desktop\check-docker.cmd (ou .sh) — ele aponta o item exato que falhou. Normalmente basta abrir o Docker Desktop e esperar o ícone da baleia parar de "Starting..."; se travar, reinicie com wsl --shutdown e abra de novo. |
| Porta 8002 ocupada (port is already allocated) | Pare o contêiner antigo com stop-guaraci ou suba em outra porta: start-guaraci.cmd (edite HostPort) ou powershell -ExecutionPolicy Bypass -File scripts/desktop/start-guaraci.ps1 -HostPort 8003. |
| UI sem dados ou "Guaraci UI not found" | Confira o volume (-v "${PWD}:/app") e as permissões de escrita da pasta data/. |
| "PySUS is required for SIH functionality" | Reconstrua a imagem com docker build --no-cache -t guaraci .. |
| Contêiner encerra na hora, sem logs | No modo manual, garanta a flag -it. |
| Botão "Abrir pasta" não faz nada | Dentro do Docker não há como abrir o explorador do host: copie o caminho host_output_dir exibido na interface. |
| Exportação pedida, mas nenhum arquivo gerado | Os filtros provavelmente excluíram 100% dos registros — veja os logs e o aviso export_warning. |
2 · Interface web
Com o Guaraci no ar, a interface fica em http://localhost:8002. O fluxo inteiro acontece em uma tela:
- Escolha a fonte. A lista traz as 94 fontes com busca. Cada uma expõe seus próprios parâmetros — o formulário se monta sozinho a partir do schema (o mesmo documentado no catálogo).
- Preencha os filtros básicos. Período (anos), estados, grupos ou doenças, conforme a fonte. Os campos avançados (paginação, URL alternativa, snapshot bruto) ficam recolhidos — os padrões atendem a maioria dos casos.
- Escolha o formato de exportação.
CSV(abre no Excel),Parquet(análise de dados) ouSQLite(banco local). Sem formato, o Guaraci só coleta e registra o manifesto. - Crie o download e acompanhe. A barra de progresso e o log ao vivo mostram cada arquivo sendo buscado, validado e convertido. Jobs ficam no histórico — dá para repetir ou depurar depois.
- Abra o resultado. Os arquivos ficam na pasta Guaraci Downloads (na Área de Trabalho, por padrão), junto com um
manifest.jsondescrevendo a coleta.
guaraci fetch discover.3 · Linha de comando
O grupo guaraci fetch alcança qualquer fonte registrada com quatro subcomandos. Dentro do Docker, prefixe com docker run --rm -v "${PWD}:/app" guaraci (ou use o shell interativo).
3.1 fetch list — o que existe
3.2 fetch schema — os parâmetros de uma fonte
3.3 fetch discover — meça antes de baixar
Disponível para o SIH e os onze sistemas de microdados FTP do DATASUS (SIA, CNES, SINASC etc.): conta arquivos por grupo/UF sem baixar nada. Com --sizes, soma também o tamanho total. SIM e SINAN resolvem seus arquivos internamente durante a coleta e ficam de fora do preflight.
3.4 fetch run — colete
Regras úteis:
--set CHAVE=VALORé convertido automaticamente para o tipo declarado no schema (inteiro, booleano, lista).- Omita
--formatpara coletar sem exportar (só o manifesto é gravado). -o PASTAmuda o destino (padrão: Guaraci Downloads na Área de Trabalho).- Credenciais NASA nunca são flags — só variáveis de ambiente (§5).
Cada fonte do catálogo traz um exemplo de fetch run pronto para copiar.
4 · Formatos e saída
| Formato | Quando usar |
|---|---|
csv | Abrir no Excel/LibreOffice, compartilhar com quem não programa. |
parquet | Análise de dados (pandas, polars, R, Spark): compacto e rápido, preserva tipos. |
sqlite | Consultas SQL locais sem servidor; um arquivo .db único. |
manifest.json— toda coleta grava um manifesto com fonte, parâmetros, arquivos e horários: é o registro de proveniência do dado.keep_raw=true— além da exportação, salva o snapshot bruto (raw/*.jsonlnas APIs) para auditoria.export_warning— se os filtros zerarem os registros ou a paginação truncar (max_pages), o aviso aparece no manifesto e nos logs. É o primeiro lugar para olhar quando "não veio nada".- Formatos de origem — arquivos
.dbc/.DBFdo DATASUS são decodificados automaticamente; você nunca precisa lidar com eles.
5 · Credenciais (NASA)
Quase tudo no Guaraci dispensa cadastro. As exceções são duas fontes da NASA — e as chaves são gratuitas:
| Fonte | Credencial | Variável de ambiente | Onde obter |
|---|---|---|---|
nasa_firms | MAP_KEY | GUARACI_FIRMS_MAP_KEY | firms.modaps.eosdis.nasa.gov |
nasa_gpm | Token Earthdata | GUARACI_EARTHDATA_TOKEN | urs.earthdata.nasa.gov (autorize o app NASA GESDISC DATA ARCHIVE) |
nasa_power e todas as fontes IBGE, OpenDataSUS, DATASUS e gov.br não exigem credencial. Por segurança, as chaves são lidas apenas do ambiente: nunca entram como parâmetro de job nem são gravadas em manifesto.
6 · Orquestrador (uso em servidor)
Para quem mantém um acervo contínuo (como o data lake Sabiá), o guaraci orchestrate automatiza a coleta em duas camadas bronze:
raw/— o arquivo oficial cru, na granularidade nativa da fonte (SINAN anual continua anual; SIH mensal continua mensal).refined/— as mesmas linhas reparticionadas na árvore uniformefonte/grupo/UF/ano/mês, fatiadas pela data do evento.
Comandos: orchestrate profiles (cadência de cada fonte), plan (dry-run), backfill (histórico completo), update (só o delta, guiado por um ledger CSV) e status. Os wrappers scripts/server/orchestrate.{sh,ps1} prontos para cron cuidam de lock e log. Detalhes em docs/ORCHESTRATOR.md no repositório.
7 · Boas práticas
- Comece pequeno. Menor janela de tempo e filtros mais estreitos possíveis; amplie depois que o fluxo estiver validado.
- Meça antes de baixar. Nas fontes FTP volumosas (SIA, SIH, CNES), rode
fetch discoverprimeiro — seleções amplas podem resolver para milhares de arquivos e muitos gigabytes. - Exporte só quando precisar. Defina
output_formatapenas quando quiser o dataset final; a coleta sem exportação é mais rápida e já fica registrada. - Vigie o
export_warning. Ele denuncia exportações vazias e paginação truncada. - Dado do ano corrente é parcial. As fontes DATASUS aceitam o ano em curso, mas há atraso de publicação de ~2–3 meses — compare com cuidado.
- Cite a fonte oficial. As condições de uso são as da instituição produtora; o Guaraci traz um
CITATION.cffcaso queira citar também a ferramenta.
8 · Catálogo das 94 fontes
Cada fonte abaixo documenta: o identificador canônico (o mesmo usado na interface, na API e no fetch run), transporte e fonte primária, cadência de atualização, todos os parâmetros com tipo, fase, padrão e valores aceitos, os campos reais observados em amostra e um exemplo de linha de comando pronto.