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

# Connect Service

> Environment variables and secrets required to run the connect service for data source ingestion

## Overview

The **connect service** (`hellocobi/dashboard-connect`) is a Python FastAPI service responsible for ingesting data from external data sources. It:

* Validates connector credentials against third-party APIs (GitHub, Slack, Linear, HubSpot)
* Executes ingestion runs that sync data from those sources into MinIO object storage
* Triggers schema mapping syncs requested by the backend

It runs on port `8000` as a `ClusterIP` service. By default it is reachable only within the cluster, but the chart can expose it through `gateway.connect` or `ingress.connect` when a deployment needs a public Connect endpoint.

Set the backend's `CONNECT_SERVICE_URL` to the in-cluster service URL, usually `http://cobi-dashboard-connect:8000`.

## How Authentication Works

Every request from the backend carries the header:

```
x-connect-service-token: <token>
```

The service reads `CONNECT_SERVICE_TOKEN` at startup and validates each incoming request. If the variable is not set, the service **refuses to start**:

```
RuntimeError: CONNECT_SERVICE_TOKEN must be set
```

The same token value must be present on **both** sides — the connect Secret and the backend Secret.

## Required Secrets

### Connect Secret

```bash theme={null}
kubectl create secret generic cobi-connect-secrets \
  --namespace cobi \
  --from-literal=HOST="0.0.0.0" \
  --from-literal=PORT="8000" \
  --from-literal=CONNECT_SERVICE_TOKEN="<shared-token>"  
```

<Warning>
  `HOST` must be `0.0.0.0`. The default `127.0.0.1` binds to loopback only — the Kubernetes Service cannot reach the pod.
</Warning>

Generate the shared token (use the same value in the backend Secret):

```bash theme={null}
openssl rand -hex 32
```

### Backend Secret additions

The backend also needs `CONNECT_SERVICE_TOKEN` and `CONNECT_BUCKET_PREFIX`. See [Backend Service](/deployment/backend) for the full backend secret.

## Environment Variable Reference

### Server

| Variable                | Required | Default     | Description                                                       |
| ----------------------- | -------- | ----------- | ----------------------------------------------------------------- |
| `HOST`                  | Yes      | `127.0.0.1` | Bind address. **Must be `0.0.0.0`** in a container                |
| `PORT`                  | No       | `8000`      | Port uvicorn listens on. Must match `connect.port` in Helm values |
| `CONNECT_SERVICE_TOKEN` | Yes      | —           | Shared secret for authenticating requests from the backend        |

### MinIO Connection

The connect service writes ingestion artifacts to MinIO. The bucket, prefix, and per-request credentials are passed in the API request body by the backend, but the S3 **endpoint** for MinIO must be set as an environment variable — it is not included in the request body.

| Variable      | Required      | Description                                                                                                                                                            |
| ------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `S3_ENDPOINT` | Yes (on-prem) | MinIO endpoint URL — `http://<release>-minio:9000` for in-cluster. DuckDB httpfs reads this to write storage artifacts. Also enables path-style URL mode automatically |

## Helm Values

```yaml theme={null}
connect:
  enabled: true
  image:
    repository: docker.io/hellocobi/dashboard-connect
    tag: "823edd6d96f97aae01425d8c3ddfc9ef8839c65b"
    pullPolicy: IfNotPresent
  replicaCount: 1
  service:
    type: ClusterIP
    port: 8000
  envFrom:
    - secretRef:
        name: cobi-connect-secrets
  resources:
    requests:
      cpu: 100m
      memory: 256Mi
    limits:
      cpu: 500m
      memory: 512Mi
```

## Verify the Service

```bash theme={null}
# Port-forward
kubectl port-forward -n cobi svc/cobi-dashboard-connect 8000:8000

# Health check — no auth required
curl http://localhost:8000/health
# {"status":"ok"}

# Protected endpoint without token returns 401
curl -X POST http://localhost:8000/internal/mirror-connections/ping
# {"detail":"Invalid connect service token"}
```

## Backend Connection

Add `CONNECT_SERVICE_URL` to the backend Secret or `backend.env`:

```yaml theme={null}
- name: CONNECT_SERVICE_URL
  value: "http://cobi-dashboard-connect:8000"
```

Verify it is set:

```bash theme={null}
kubectl exec -n cobi deploy/cobi-dashboard-backend -- env | grep CONNECT_SERVICE_URL
```