> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strattum.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Local Development

> Step-by-step guide to run strattum-data locally — Prefect Server, pipelines worker and supporting infrastructure.

> [!NOTE]
>
> Este guia é voltado para o **time de engenharia strattum.ai**. Para conectar uma fonte de dados via Console, consulte o [Quickstart de Data Pipelines](https://docs.strattum.ai/data-pipelines/quickstart).

## 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:

```bash theme={null}
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:

```bash theme={null}
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` |

> [!WARNING]
>
> **Conflito de porta:** Se a porta `5432` já estiver em uso (PostgreSQL local rodando), altere o binding no `docker-compose.yml`:
>
> ```yaml theme={null}
> 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](https://docs.strattum.ai/data-pipelines/connectors/zendesk.md#como-obter-o-api-token) |
| `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

```bash theme={null}
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:

```bash theme={null}
docker compose ps
```

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

***

## 4. Instalar dependências Python

```bash theme={null}
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:

```bash theme={null}
set -a && source strattum-deploy/starter/.env && set +a
```

Verifique:

```bash theme={null}
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):

```bash theme={null}
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.
```

> [!TIP]
>
> 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:

```bash theme={null}
# 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:

1. Acesse **Deployments**
2. Clique em `zendesk_sync`
3. Clique em **Quick run**
4. Acompanhe em **Flow Runs**

Ou via CLI:

```bash theme={null}
prefect deployment run zendesk_sync/zendesk_sync
```

***

## Parar o ambiente

```bash theme={null}
# 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
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.