> ## Documentation Index
> Fetch the complete documentation index at: https://strattumai.mintlify.site/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](/data-pipelines/quickstart).
</Note>

## 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`.
</Warning>

### 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](/data-pipelines/connectors/zendesk#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.
</Tip>

***

## 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`.
</Warning>