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

# MinIO Setup

> Configure MinIO object storage for document uploads and data ingestion artifacts in on-premises environments

## Overview

MinIO provides an S3-compatible API that Cobi uses to store uploaded documents and data ingestion artifacts. Enable it for on-premises or air-gapped clusters.

**Default ports:**

* `9000` — S3 API (used by the backend and connect service)
* `9001` — Web console

## Configuration

```yaml theme={null}
minio:
  enabled: true

  mode: standalone     # "standalone" for single-node; "distributed" for HA

  auth:
    rootUser: admin
    rootPassword: "<strong-password>"   # minimum 8 characters
    # In production, prefer an existing Secret — see below

  defaultBuckets: "documents"           # created on first startup

  persistence:
    enabled: true
    storageClass: ""     # use cluster default; set "local-path" or "nfs-csi" for on-prem
    accessModes:
      - ReadWriteOnce
    size: 100Gi

  service:
    type: ClusterIP
    ports:
      api: 9000
      console: 9001

  resources:
    requests:
      cpu: 250m
      memory: 512Mi
    limits:
      cpu: "1"
      memory: 1Gi
```

## On-Premises StorageClass

```yaml theme={null}
minio:
  persistence:
    storageClass: "local-path"
    size: 500Gi
```

<Note>
  `standalone` mode with `ReadWriteOnce` works on most on-prem clusters. For production HA, use `mode: distributed` with a StorageClass that supports concurrent access (NFS, Longhorn, etc.).
</Note>

## Using an Existing Secret

```bash theme={null}
kubectl create secret generic minio-credentials \
  --namespace cobi \
  --from-literal=root-user=admin \
  --from-literal=root-password="<strong-password>"
```

```yaml theme={null}
minio:
  auth:
    existingSecret: "minio-credentials"
```

## Exposing the Web Console (optional)

```yaml theme={null}
minio:
  consoleIngress:
    enabled: true
    ingressClassName: nginx
    hostname: minio-console.example.com
    tls: false
```

<Warning>
  Enable TLS before exposing MinIO outside the cluster. Plain HTTP transmits credentials in the clear.
</Warning>

## Verify MinIO

```bash theme={null}
# Port-forward the MinIO API
kubectl port-forward -n cobi svc/cobi-dashboard-minio 9000:9000

# Health check
curl http://localhost:9000/minio/health/live

# List buckets
mc alias set local http://localhost:9000 admin <password>
mc ls local/
```

The `documents` bucket should exist after first startup.

## Connecting the Backend

Set these variables in the backend Secret using the S3 environment variable names:

```bash theme={null}
--from-literal=S3_BUCKET="documents" \
--from-literal=S3_REGION="us-east-1" \
--from-literal=S3_ENDPOINT="http://cobi-dashboard-minio:9000" \
--from-literal=S3_ACCESS_KEY_ID="admin" \
--from-literal=S3_SECRET_ACCESS_KEY="<minio-root-password>"
```

| Variable               | Description                                                       |
| ---------------------- | ----------------------------------------------------------------- |
| `S3_BUCKET`            | Bucket name — must match `minio.defaultBuckets`                   |
| `S3_REGION`            | Signing region. Use `us-east-1` for MinIO                         |
| `S3_ENDPOINT`          | MinIO API endpoint. For in-cluster: `http://<release>-minio:9000` |
| `S3_ACCESS_KEY_ID`     | MinIO `rootUser`                                                  |
| `S3_SECRET_ACCESS_KEY` | MinIO `rootPassword`                                              |

Reference the same Secret from `backend.s3.existingSecret` so Helm projects the generic keys into the backend container.

## Connecting the Connect Service

The connect service also writes ingestion artifacts to MinIO. Set the endpoint using the env vars the service reads from (these are the actual variable names the Python process reads):

```bash theme={null}
--from-literal=S3_ENDPOINT="http://cobi-dashboard-minio:9000" \
--from-literal=AWS_ACCESS_KEY_ID="admin" \
--from-literal=AWS_SECRET_ACCESS_KEY="<minio-root-password>" \
--from-literal=AWS_DEFAULT_REGION="us-east-1"
```

See [Connect Service](/deployment/dashboard-connect) for the full secret.

## Sizing Guide

| Document volume          | Recommended PVC size        |
| ------------------------ | --------------------------- |
| \< 10 000 documents      | 50 Gi                       |
| 10 000–100 000 documents | 100–500 Gi                  |
| > 100 000 documents      | 500 Gi+ or distributed mode |