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

# Primeiros passos com o Fetcher

> Guia rápido para rodar o Fetcher localmente com Docker Compose e executar seu primeiro job de extração de dados.

Este guia leva você de um checkout limpo a um ambiente Fetcher em execução e um job de extração concluído. Tudo roda localmente com Docker Compose.

Ao final, você terá:

* Manager, Worker e sua infraestrutura rodando localmente
* Uma conexão de banco de dados registrada e testada
* Um job de extração criado e com status consultado

## Pré-requisitos

***

* [ ] **Docker** e **Docker Compose**
* [ ] **Make**
* [ ] **Go** (apenas para desenvolvimento — a versão do toolchain está declarada no `go.mod` do repositório)

## Configurar e rodar

***

<Steps>
  <Step title="Clone o repositório">
    ```bash theme={null}
    git clone https://github.com/LerianStudio/fetcher.git
    cd fetcher
    ```
  </Step>

  <Step title="Configure os arquivos de ambiente">
    ```bash theme={null}
    make set-env
    ```

    Isso cria os arquivos `.env` de cada componente a partir dos templates `.env.example`.
  </Step>

  <Step title="Gere a chave-mestra de criptografia">
    ```bash theme={null}
    make generate-master-key
    ```

    Copie a chave gerada e defina-a como `APP_ENC_KEY` em **ambos** `components/manager/.env` e `components/worker/.env`. Essa chave é obrigatória — os serviços não iniciam sem ela, e os dois devem usar o mesmo valor: o Worker precisa dela para descriptografar credenciais de conexão e verificar assinaturas de mensagens.
  </Step>

  <Step title="Suba todos os serviços">
    ```bash theme={null}
    make up
    ```
  </Step>

  <Step title="Verifique se a API está no ar">
    * API REST: `http://localhost:4006`
    * Swagger UI: `http://localhost:4006/swagger/index.html`
    * Gerenciamento do RabbitMQ: `http://localhost:3008`
  </Step>
</Steps>

## Execute sua primeira extração

***

Uma extração tem três movimentos: registrar uma conexão, criar um job e consultar o job até ele terminar.

### 1. Registre uma conexão de banco de dados

```bash theme={null}
curl -X POST http://localhost:4006/v1/management/connections \
  -H "Content-Type: application/json" \
  -d '{
    "configName": "meu_postgres",
    "type": "POSTGRESQL",
    "host": "host.docker.internal",
    "port": 5432,
    "databaseName": "meudb",
    "userName": "postgres",
    "password": "postgres"
  }'
```

A senha é criptografada antes de ser armazenada. Teste a conexão antes de usá-la:

```bash theme={null}
curl -X POST http://localhost:4006/v1/management/connections/{id}/test
```

### 2. Crie um job de extração

Diga ao Fetcher quais campos extrair, de quais tabelas, por datasource:

```bash theme={null}
curl -X POST http://localhost:4006/v1/fetcher \
  -H "Content-Type: application/json" \
  -d '{
    "dataRequest": {
      "mappedFields": {
        "meu_postgres": {
          "accounts": ["id", "email", "created_at"]
        }
      }
    },
    "metadata": {
      "source": "quickstart"
    }
  }'
```

A API responde `202 Accepted` com o ID do job. Se um job idêntico foi submetido nos últimos 5 minutos, o Fetcher detecta a duplicata e retorna o job existente com `200 OK` em vez de criar um novo.

### 3. Consulte o status do job

```bash theme={null}
curl http://localhost:4006/v1/fetcher/{id}
```

Um job passa por `pending` → `processing` → `completed` (ou `failed`). Na conclusão, o Worker já criptografou os resultados no object storage e publicou um evento `job.completed`.

<Note>
  Quando a autenticação está habilitada (`PLUGIN_AUTH_ENABLED=true`), as requisições também carregam um header `Authorization: Bearer <token>`. O quickstart local roda com autenticação desabilitada.
</Note>

## Próximos passos

***

<CardGroup cols={2}>
  <Card title="Conceitos centrais" icon="book" href="/pt/fetcher/fetcher-core-concepts">
    Entenda conexões, descoberta de esquemas, jobs, filtros e resultados.
  </Card>

  <Card title="Configuração" icon="gear" href="/pt/fetcher/fetcher-configuration">
    As variáveis de ambiente que moldam uma implantação do Fetcher.
  </Card>
</CardGroup>