Instalação e configuração

Este guia mostra como instalar e executar o Ro-DOU localmente para experimentação e desenvolvimento. Ao final, você terá o ambiente completo rodando em containers Docker, com um clipping de exemplo já configurado.

Tempo estimado: 10 a 15 minutos (a primeira inicialização dos containers pode levar alguns minutos).

Pré-requisitos

• 4Gb de memória RAM
• 2Gb de espaço em disco
• Sistema operacional Linux, macOS ou Windows com WSL
• Docker e Docker Compose (Docker Compose versão 1.29 ou superior)

⚠️ Usuários de Windows: recomenda-se utilizar o WSL (Windows Subsystem for Linux). Antes de continuar, confirme que:

• o WSL está instalado e configurado;
• o Docker está habilitado no WSL.

Prefere acompanhar em vídeo? Os tutoriais abaixo cobrem o passo a passo de instalação:

O código-fonte está disponibilizado no perfil do do Ministério da Gestão e da Inovação em Serviços Públicos.

1. Clonando o repositório

Abra o terminal e execute:

git clone https://github.com/gestaogovbr/Ro-dou
cd Ro-dou

2. Iniciando o ambiente

O repositório já vem com comandos pré-definidos no Makefile para facilitar a execução. Para iniciar todos os serviços necessários, rode:

make run

💡 Dica: este comando baixa as imagens Docker, builda o container do Ro-DOU e configura automaticamente as variáveis de ambiente e conexões do Airflow — não é necessário nenhum passo manual adicional.

Você deverá ver uma saída parecida com esta:

Se esta não for a primeira execução, os bancos e conexões já existirão e você verá mensagens como:

psql:/sql/init-db.sql:1: ERROR:  database "inlabs" already exists
psql:/sql/init-db.sql:5: NOTICE:  schema "dou_inlabs" already exists, skipping
psql:/sql/init-db.sql:35: NOTICE:  relation "article_raw" already exists, skipping

Isso é esperado e não indica um problema — o Ro-DOU verifica o que já existe antes de criar novamente.

3. Confirmando que o Airflow está no ar

O Apache Airflow — do qual o Ro-DOU depende — pode levar alguns minutos para subir na primeira inicialização. Aguarde e acesse:

http://localhost:8080/

Autentique-se com usuário airflow e senha airflow.

4. Ativando o clipping de exemplo

Na tela inicial do Airflow (lista de DAGs), você verá clippings de exemplo já configurados a partir dos arquivos YAML do diretório dag_confs/. Todas as DAGs começam pausadas — vamos ativar uma para testar o ambiente:

1. Localize a DAG all_parameters_example na lista e ative-a clicando no botão toggle à esquerda do nome.
2. Assim que ativada, o Airflow dispara a execução automaticamente (uma única vez). Clique no nome da DAG para acompanhar na visualização em Grid.

5. Visualizando o clipping

Acesse http://localhost:5001/ — um serviço que simula uma caixa de e-mail (servidor SMTP) para fins de experimentação — e veja a mensagem recebida. Voilà!

6. Encerrando o ambiente

Quando terminar de utilizar o ambiente de teste, desligue-o com:

make down

Você pode subir o ambiente novamente a qualquer momento com make run.

---

Próximos passos

• Quer criar seus próprios clippings? Use o Gerador de configuração (YAML) pela interface web, ou rode make gerar-yml no terminal — ele pergunta os campos passo a passo, valida com as mesmas regras do Ro-DOU e salva o arquivo direto em dag_confs/. Veja o vídeo tutorial do gerador e da CLI.
• Confira os parâmetros de pesquisa disponíveis nos YAMLs.
• Veja exemplos prontos em Exemplos.

---

Configurações avançadas (opcional)

As seções abaixo são independentes entre si — configure apenas o que fizer sentido para o seu caso de uso.

Usando o INLABS como fonte de dados

O INLABS é o portal da Imprensa Nacional que disponibiliza os dados do Diário Oficial da União em lote. Usá-lo como fonte no Ro-DOU libera recursos extras não disponíveis na fonte padrão (API do DOU), como texto completo, resumos por IA e operadores de busca avançados.

Para configurar:

1. Crie uma conta no portal do INLABS: acesse https://inlabs.in.gov.br/acessar.php e cadastre-se.

   ⚠️ Observação: é comum o portal exibir uma mensagem de erro logo após o cadastro. Pode ignorar — a conta costuma ser criada normalmente mesmo assim.

2. Acesse as conexões do Airflow em http://localhost:8080/connection/list/. O make run já cria duas conexões: inlabs_db e inlabs_portal.

3. Edite a conexão inlabs_portal e preencha:

   • Login: o e-mail usado para criar a conta no INLABS
   • Password: a senha da conta

4. Rode a DAG ro-dou_inlabs_load_pg — ela faz a carga inicial dos dados do INLABS no banco de dados.

Backend de busca do INLABS (SQL ou OpenSearch)

O OpenSearch é um mecanismo de busca e indexação utilizado pelo Ro-DOU para realizar pesquisas textuais nas publicações do INLABS. Por padrão, o Ro-DOU utiliza o PostgreSQL (modo SQL). Para alternar para o OpenSearch, use a variável do Airflow RO_DOU_INLABS_USE_OPENSEARCH.

Para criar a variável automaticamente:

make create-opensearch-variable

Ou crie manualmente na interface do Airflow em http://localhost:8080/variable/list/:

Variável	Valor padrão	Descrição
RO_DOU_INLABS_USE_OPENSEARCH	False	Define o backend de busca do INLABS. Use False para PostgreSQL (SQL) ou True para OpenSearch.
OPENSEARCH_HOST	http://opensearch:9200	Endereço do serviço OpenSearch (definido no docker-compose).
OPENSEARCH_USER	OPENSEARCH_USER	Usuário para autenticação no OpenSearch.
OPENSEARCH_PASS	OPENSEARCH_PASS	Senha para autenticação no OpenSearch.

Observação: Quando o valor é False (padrão), o OpenSearch não precisa estar disponível no ambiente. A task de indexação é automaticamente ignorada na DAG ro-dou_inlabs_load_pg.

Resumos automáticos com IA generativa

O Ro-DOU também suporta gerar resumos automáticos das publicações usando LLMs (OpenAI, Gemini, Claude ou Azure). Veja o guia completo — build com o provedor desejado, variáveis de API e configuração do YAML — em Habilitando IA nos resumos.

---

Referência rápida de comandos

Comando	O que faz
make run	Sobe todos os containers e configura o ambiente (idempotente — pode rodar de novo a qualquer momento)
make down	Desliga todos os containers
make build AI_PROVIDERS="..."	Reconstrói a imagem incluindo suporte a provedor(es) de IA
make gerar-yml	Gera um novo arquivo de configuração YAML por um assistente interativo no terminal (requer o ambiente já rodando)
make create-opensearch-variable	Cria a variável do Airflow para usar o OpenSearch como backend de busca do INLABS
make create-azure-openai-variables	Cria as variáveis do Airflow necessárias para usar o provedor Azure OpenAI

Solução de problemas comuns

• make run falha ou trava: confirme que o Docker Desktop/daemon está em execução antes de rodar o comando.
• Porta já em uso (8080 ou 5001): verifique se outro serviço na sua máquina já está usando essas portas e finalize-o, ou libere a porta antes de rodar make run.
• Airflow não carrega em http://localhost:8080/: aguarde alguns minutos — a mensagem "Waiting for Airflow API to start" no terminal indica que o serviço ainda está subindo.
• make gerar-yml retorna erro de container: o ambiente precisa estar rodando primeiro; execute make run antes.