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

# Primeros pasos con Fetcher

> Guía rápida para ejecutar Fetcher localmente con Docker Compose y correr tu primer job de extracción de datos.

Esta guía te lleva de un checkout limpio a un entorno Fetcher en ejecución y un job de extracción completado. Todo corre localmente con Docker Compose.

Al final tendrás:

* Manager, Worker y su infraestructura corriendo localmente
* Una conexión de base de datos registrada y probada
* Un job de extracción creado y con su estado consultado

## Prerrequisitos

***

* [ ] **Docker** y **Docker Compose**
* [ ] **Make**
* [ ] **Go** (solo para desarrollo — la versión del toolchain está declarada en el `go.mod` del repositorio)

## Configura y ejecuta

***

<Steps>
  <Step title="Clona el repositorio">
    ```bash theme={null}
    git clone https://github.com/LerianStudio/fetcher.git
    cd fetcher
    ```
  </Step>

  <Step title="Configura los archivos de entorno">
    ```bash theme={null}
    make set-env
    ```

    Esto crea los archivos `.env` de cada componente a partir de sus plantillas `.env.example`.
  </Step>

  <Step title="Genera la clave maestra de cifrado">
    ```bash theme={null}
    make generate-master-key
    ```

    Copia la clave generada y defínela como `APP_ENC_KEY` en **ambos** `components/manager/.env` y `components/worker/.env`. Esta clave es obligatoria — los servicios no arrancan sin ella, y los dos deben usar el mismo valor: el Worker la necesita para descifrar credenciales de conexión y verificar firmas de mensajes.
  </Step>

  <Step title="Levanta todos los servicios">
    ```bash theme={null}
    make up
    ```
  </Step>

  <Step title="Verifica que la API está arriba">
    * API REST: `http://localhost:4006`
    * Swagger UI: `http://localhost:4006/swagger/index.html`
    * Gestión de RabbitMQ: `http://localhost:3008`
  </Step>
</Steps>

## Ejecuta tu primera extracción

***

Una extracción tiene tres movimientos: registrar una conexión, crear un job y consultar el job hasta que termine.

### 1. Registra una conexión de base de datos

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

La contraseña se cifra antes de almacenarse. Prueba la conexión antes de usarla:

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

### 2. Crea un job de extracción

Dile a Fetcher qué campos extraer, de qué tablas, por datasource:

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

La API responde `202 Accepted` con el ID del job. Si un job idéntico se envió en los últimos 5 minutos, Fetcher detecta el duplicado y devuelve el job existente con `200 OK` en lugar de crear uno nuevo.

### 3. Consulta el estado del job

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

Un job pasa por `pending` → `processing` → `completed` (o `failed`). Al completarse, el Worker ya cifró los resultados en el object storage y publicó un evento `job.completed`.

<Note>
  Cuando la autenticación está habilitada (`PLUGIN_AUTH_ENABLED=true`), las peticiones también llevan un header `Authorization: Bearer <token>`. El quickstart local corre con la autenticación deshabilitada.
</Note>

## Próximos pasos

***

<CardGroup cols={2}>
  <Card title="Conceptos centrales" icon="book" href="/es/fetcher/fetcher-core-concepts">
    Entiende conexiones, descubrimiento de esquemas, jobs, filtros y resultados.
  </Card>

  <Card title="Configuración" icon="gear" href="/es/fetcher/fetcher-configuration">
    Las variables de entorno que dan forma a un despliegue de Fetcher.
  </Card>
</CardGroup>