4 Guia de instalação do colibri

Este guia detalha, passo a passo, a instalação descrita no README do repositório, com variações para Windows (PowerShell) e Mac/Linux.

4.1 Pré-requisitos

Python 3.12 ou superior instalado.
git instalado.
Credenciais do Colibri (veja Credenciais de acesso abaixo) — ou, alternativamente, um bucket S3-compatível próprio (veja Instalar o ambiente em um S3 próprio).

4.2 Passo a passo

4.2.1 1. Clonar o repositório

git clone https://github.com/gestaogovbr/colibri
cd colibri

git clone https://github.com/gestaogovbr/colibri
cd colibri

4.2.2 2. Criar e ativar um ambiente virtual (recomendado)

O repositório não exige um ambiente virtual especificamente, mas é a forma mais segura de isolar as dependências do Colibri do resto do sistema.

python3 -m venv env
source env/bin/activate

python -m venv env
.\env\Scripts\Activate.ps1

Se o PowerShell bloquear a ativação com um erro de política de execução, rode uma vez (como o próprio usuário, sem precisar de administrador):

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

4.2.3 3. Instalar a CLI do `colibri`

Instala a CLI localmente, junto com as dependências Python do projeto.

pip install -e .

4.2.4 4. Instalar as dependências do dbt

cd dbt
dbt deps
cd ..

4.2.5 5. Configurar os segredos do bucket R2

Copie o template e preencha com suas credenciais:

cp .segredos_template.yml .segredos.yml

4.2.6 6. Configurar o `profiles.yml` do dbt

O template já vem pronto, sem caminhos para editar — os caminhos são relativos ao diretório dbt/:

cp dbt/profiles_template.yml dbt/profiles.yml

4.2.7 Desinstalação da CLI

pip uninstall colibri

4.3 Credenciais de acesso

O Colibri distingue dois perfis de credencial, ambos configurados em .segredos.yml:

colibri-token-desenvolvedor: credencial de leitura e escrita, usada por padrão nos comandos de pipeline, upload/purge de bucket e nos comandos de lake que alteram dados (drop-table, maintenance).
colibri-token-visualizador: credencial somente leitura, usada por padrão nos comandos de consulta e exploração (lake tables, years, download, query, ui). O comando colibri lake drop-table recusa rodar com essa credencial.

Importante

Enquanto o Colibri está sendo testado, ambas as credenciais ainda são concedidas apenas a usuários selecionados. Se você não recebeu as suas, entre em contato com a equipe do projeto — ou monte seu próprio ambiente apontando para um bucket S3 próprio, como descrito a seguir.

4.4 Instalar o ambiente em um S3 próprio

Quem quiser rodar o Colibri de ponta a ponta sem depender das credenciais oficiais pode apontar o projeto para um bucket S3-compatível próprio (Cloudflare R2, AWS S3, GCS etc.).

Crie um bucket (ou dois: um para dados brutos, outro para o lakehouse) na plataforma de sua escolha e gere uma chave de acesso com permissão de leitura e escrita.

Em .segredos.yml, preencha os campos do template com esses dados:

colibri-token-desenvolvedor:
  endpoint: "https://<ACCOUNTID>.r2.cloudflarestorage.com"
  access_key: "<SUA ACCESS KEY>"
  secret_key: "<SUA SECRET KEY>"
  bucket_raw: "<NOME DO SEU BUCKET RAW>"
  bucket_lake: "<NOME DO SEU BUCKET LAKE>"

Em dbt/profiles.yml, ajuste o bloco de segredo S3 e o attach para apontar para o mesmo bucket:

secrets:
  - type: s3
    provider: config
    key_id: <SUA ACCESS KEY>
    secret: <SUA SECRET KEY>
    endpoint: "<ACCOUNTID>.r2.cloudflarestorage.com"
    region: auto
    url_style: path
    use_ssl: true
attach:
  - path: "ducklake:../meta.ducklake"
    alias: lake
    options:
      data_path: "s3://<NOME DO SEU BUCKET LAKE>/lake/"

Rode colibri pipeline run para popular o bucket do zero — o meta.ducklake local é criado automaticamente na primeira execução.

A partir daí, todos os comandos da CLI e do dbt operam normalmente contra o seu próprio bucket, sem depender da infraestrutura oficial do Colibri.