Local Development

Este guia é voltado para o time de engenharia strattum.ai. Para conectar uma fonte de dados via Console, consulte o Quickstart de Data Pipelines.

Pré-requisitos

Ferramenta	Versão mínima	Verificar
Python	3.12	`python --version`
Docker	24+	`docker --version`
Docker Compose	v2 (plugin)	`docker compose version`
Git	qualquer	—

1. Clonar os repositórios

A infraestrutura (docker-compose.yml e .env) fica em um repositório separado. Ambos devem ser clonados como irmãos:

git clone https://github.com/strattum-ai/strattum-data.git
git clone https://github.com/strattum-ai/strattum-deploy.git

Estrutura esperada:

~/projects/
├── strattum-data/
└── strattum-deploy/

2. Configurar variáveis de ambiente

Copie o arquivo de exemplo e preencha os valores:

cp strattum-deploy/starter/.env.example strattum-deploy/starter/.env

Infraestrutura (Docker Compose)

Variável	Descrição	Padrão
`POSTGRES_USER`	Usuário do PostgreSQL	`strattum`
`POSTGRES_PASSWORD`	Senha do PostgreSQL	alterar obrigatoriamente
`POSTGRES_DB`	Banco principal da aplicação	`strattum`
`PREFECT_API_DATABASE_CONNECTION_URL`	Conexão do Prefect Server com o banco `prefect`	ver exemplo

Desenvolvimento local (pipelines fora do Docker)

Variável	Descrição	Exemplo
`PREFECT_API_URL`	URL do Prefect Server acessível pelo host	`http://localhost:4200/api`
`DATABASE_URL`	DSN do PostgreSQL acessível pelo host	`postgresql+asyncpg://strattum:senha@localhost:5432/strattum`
`STORAGE_BACKEND`	Backend de storage para artefatos	`local`
`STORAGE_PATH`	Caminho local para artefatos	`/tmp/strattum-data`

Conflito de porta: Se a porta 5432 já estiver em uso (PostgreSQL local rodando), altere o binding no docker-compose.yml:

ports:
  - "5433:5432"

E atualize DATABASE_URL para usar a porta 5433.

Credenciais dos conectores

Variável	Descrição
`ZENDESK_SUBDOMAIN`	Subdomínio do Zendesk (ex: `acme` para `acme.zendesk.com`)
`ZENDESK_EMAIL`	E-mail do agente associado ao token de API
`ZENDESK_API_TOKEN`	Token de API do Zendesk — veja como gerar
`POSTGRES_CLIENT_URL`	Connection string do banco PostgreSQL de origem
`GCP_SERVICE_ACCOUNT_JSON`	Service account JSON do GCP para Google Drive

Deixe as credenciais em branco se não for executar aquele flow específico.

3. Subir a infraestrutura

cd strattum-deploy/starter
docker compose up -d

Containers iniciados:

Container	Serviço	Porta no host
`strattum-postgres`	PostgreSQL 16	`5432` (ou `5433`)
`strattum-falkordb`	FalkorDB	`6380`
`strattum-qdrant`	Qdrant	`6333`
`strattum-prefect-server`	Prefect Server	`4200`

Verifique o status:

docker compose ps

Confirme que o Prefect UI está acessível em http://localhost:4200.

4. Instalar dependências Python

cd strattum-data/services/pipelines
pip install -r requirements.txt

5. Carregar variáveis de ambiente

Todos os comandos das etapas seguintes precisam das variáveis carregadas no terminal:

set -a && source strattum-deploy/starter/.env && set +a

Verifique:

echo $PREFECT_API_URL
# esperado: http://localhost:4200/api

6. Registrar os flows

Cria o work pool e registra os três deployments no Prefect Server (executar uma vez):

cd strattum-data/services/pipelines/src
python -m flows.deploy

Output esperado:

INFO  Work pool 'strattum-pool' created (type=process)
INFO  Deploying 'zendesk_sync' (schedule: */15 * * * *, pool: strattum-pool)
INFO  Deployment 'zendesk_sync' registered successfully.
INFO  Deploying 'postgres_sync' ...
INFO  Deploying 'gdrive_sync' ...
INFO  All flows registered. Open http://localhost:4200 to validate them in the UI.

Executar flows.deploy novamente é seguro — o Prefect atualiza os deployments existentes no lugar.

7. Subir o worker

O worker é um processo separado que monitora o work pool e executa as runs agendadas ou disparadas manualmente:

# Em um novo terminal — manter rodando
set -a && source strattum-deploy/starter/.env && set +a
prefect worker start --pool strattum-pool

No Prefect UI, o work pool deve aparecer com status Online.

8. Disparar um run de teste

No Prefect UI:

Acesse Deployments
Clique em zendesk_sync
Clique em Quick run
Acompanhe em Flow Runs

Ou via CLI:

prefect deployment run zendesk_sync/zendesk_sync

Parar o ambiente

# Worker: Ctrl+C no terminal

# Para os containers (mantém volumes / dados)
cd strattum-deploy/starter
docker compose down

# Para e APAGA todos os dados (volumes)
docker compose down -v

Use down -v apenas quando precisar de um ambiente limpo — todos os bancos serão recriados no próximo docker compose up -d.

Visão geral

Bancos de dados

CRM & SaaS

Financeiro

Documentos

Analytics

Referência

Pré-requisitos

1. Clonar os repositórios

2. Configurar variáveis de ambiente

Infraestrutura (Docker Compose)

Desenvolvimento local (pipelines fora do Docker)

Credenciais dos conectores

3. Subir a infraestrutura

4. Instalar dependências Python

5. Carregar variáveis de ambiente

6. Registrar os flows

7. Subir o worker

8. Disparar um run de teste

Parar o ambiente

​Pré-requisitos

​1. Clonar os repositórios

​2. Configurar variáveis de ambiente

​Infraestrutura (Docker Compose)

​Desenvolvimento local (pipelines fora do Docker)

​Credenciais dos conectores

​3. Subir a infraestrutura

​4. Instalar dependências Python

​5. Carregar variáveis de ambiente

​6. Registrar os flows

​7. Subir o worker

​8. Disparar um run de teste

​Parar o ambiente

Pré-requisitos

1. Clonar os repositórios

2. Configurar variáveis de ambiente

Infraestrutura (Docker Compose)

Desenvolvimento local (pipelines fora do Docker)

Credenciais dos conectores

3. Subir a infraestrutura

4. Instalar dependências Python

5. Carregar variáveis de ambiente

6. Registrar os flows

7. Subir o worker

8. Disparar um run de teste

Parar o ambiente