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

# Getting started with Fetcher

> Quickstart guide to run Fetcher locally with Docker Compose and execute your first data extraction job.

This guide takes you from a clean checkout to a running Fetcher environment and a completed extraction job. Everything runs locally with Docker Compose.

By the end you will:

* Have Manager, Worker, and their infrastructure running locally
* Register and test a database connection
* Create an extraction job and read its status

## Prerequisites

***

* [ ] **Docker** and **Docker Compose**
* [ ] **Make**
* [ ] **Go** (only for development — the toolchain version is declared in the repo's `go.mod`)

## Set up and run

***

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

  <Step title="Set up environment files">
    ```bash theme={null}
    make set-env
    ```

    This creates the `.env` files for each component from their `.env.example` templates.
  </Step>

  <Step title="Generate the master encryption key">
    ```bash theme={null}
    make generate-master-key
    ```

    Copy the generated key and set it as `APP_ENC_KEY` in **both** `components/manager/.env` and `components/worker/.env`. This key is required — the services will not start without it, and both must use the same value: the Worker needs it to decrypt connection credentials and verify message signatures.
  </Step>

  <Step title="Start all services">
    ```bash theme={null}
    make up
    ```
  </Step>

  <Step title="Verify the API is up">
    * REST API: `http://localhost:4006`
    * Swagger UI: `http://localhost:4006/swagger/index.html`
    * RabbitMQ management: `http://localhost:3008`
  </Step>
</Steps>

## Run your first extraction

***

An extraction has three moves: register a connection, create a job, poll the job until it finishes.

### 1. Register a database connection

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

The password is encrypted before it is stored. Test the connection before using it:

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

### 2. Create an extraction job

Tell Fetcher which fields to extract from which tables, per datasource:

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

The API answers `202 Accepted` with a job ID. If an identical job was submitted within the last 5 minutes, Fetcher detects the duplicate and returns the existing job with `200 OK` instead of creating a new one.

### 3. Poll the job status

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

A job moves through `pending` → `processing` → `completed` (or `failed`). On completion, the Worker has encrypted the results into object storage and published a `job.completed` event.

<Note>
  When authentication is enabled (`PLUGIN_AUTH_ENABLED=true`), requests also carry an `Authorization: Bearer <token>` header. The local quickstart runs with auth disabled.
</Note>

## Next steps

***

<CardGroup cols={2}>
  <Card title="Core concepts" icon="book" href="/en/fetcher/fetcher-core-concepts">
    Understand connections, schema discovery, jobs, filters, and results.
  </Card>

  <Card title="Configuration" icon="gear" href="/en/fetcher/fetcher-configuration">
    The environment variables that shape a Fetcher deployment.
  </Card>
</CardGroup>