> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/lumina-ai-inc/chunkr/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment Variables

> Complete reference for Chunkr environment variables

Chunkr uses environment variables to configure services, database connections, authentication, and storage. All variables should be set in your `.env` file.

## Quick Setup

<Steps>
  <Step title="Copy example file">
    ```bash theme={null}
    cp .env.example .env
    ```
  </Step>

  <Step title="Review and modify">
    The default values work for local development. Modify for production deployment.
  </Step>

  <Step title="Load environment">
    Docker Compose automatically loads `.env` when starting services.
  </Step>
</Steps>

<Info>
  For local development with Docker Compose, the default values in `.env.example` work out of the box.
</Info>

## Authentication Configuration

### Keycloak Settings

Keycloak handles authentication and authorization for Chunkr.

```bash theme={null}
AUTH__KEYCLOAK_URL=http://keycloak:8080
```

**AUTH\_\_KEYCLOAK\_URL**

* **Description**: Internal URL for backend services to communicate with Keycloak
* **Default**: `http://keycloak:8080`
* **Production**: Use your Keycloak instance URL (e.g., `https://auth.yourdomain.com`)

### Frontend Keycloak Configuration

These variables configure the web UI's connection to Keycloak:

```bash theme={null}
VITE_KEYCLOAK_URL=http://localhost:8080
VITE_KEYCLOAK_REALM=chunkr
VITE_KEYCLOAK_CLIENT_ID=chunkr
VITE_KEYCLOAK_REDIRECT_URI=http://localhost:5173
VITE_KEYCLOAK_POST_LOGOUT_REDIRECT_URI=http://localhost:5173
```

| Variable                                        | Description                                        | Default                 |
| ----------------------------------------------- | -------------------------------------------------- | ----------------------- |
| **VITE\_KEYCLOAK\_URL**                         | Public-facing Keycloak URL accessible from browser | `http://localhost:8080` |
| **VITE\_KEYCLOAK\_REALM**                       | Keycloak realm name                                | `chunkr`                |
| **VITE\_KEYCLOAK\_CLIENT\_ID**                  | OAuth client ID                                    | `chunkr`                |
| **VITE\_KEYCLOAK\_REDIRECT\_URI**               | OAuth callback URL after login                     | `http://localhost:5173` |
| **VITE\_KEYCLOAK\_POST\_LOGOUT\_REDIRECT\_URI** | Redirect URL after logout                          | `http://localhost:5173` |

<Warning>
  In production, update all `localhost` URLs to your actual domain names with HTTPS.
</Warning>

## Storage Configuration (AWS/MinIO)

Chunkr uses S3-compatible storage for document files. By default, it uses MinIO for local storage.

```bash theme={null}
AWS__ACCESS_KEY=minioadmin
AWS__SECRET_KEY=minioadmin
AWS__REGION=us-east-1
AWS__ENDPOINT=http://minio:9000
AWS__PRESIGNED_URL_ENDPOINT=http://localhost:9000
```

### AWS/MinIO Variables

**AWS\_\_ACCESS\_KEY**

* **Description**: S3/MinIO access key ID
* **Default**: `minioadmin` (MinIO default)
* **Production**: Use IAM credentials for AWS S3 or custom MinIO credentials

**AWS\_\_SECRET\_KEY**

* **Description**: S3/MinIO secret access key
* **Default**: `minioadmin` (MinIO default)
* **Production**: Use secure credentials, rotate regularly

**AWS\_\_REGION**

* **Description**: AWS region for S3 bucket
* **Default**: `us-east-1`
* **Production**: Set to your S3 bucket's region

**AWS\_\_ENDPOINT**

* **Description**: Internal S3/MinIO endpoint for backend services
* **Default**: `http://minio:9000` (Docker service name)
* **Production**: Remove for AWS S3, or set to your MinIO URL

**AWS\_\_PRESIGNED\_URL\_ENDPOINT**

* **Description**: Public-facing endpoint for generating presigned URLs
* **Default**: `http://localhost:9000`
* **Production**: Set to your public MinIO/S3 URL (e.g., `https://storage.yourdomain.com`)

<Info>
  When using AWS S3 in production, you can omit `AWS__ENDPOINT` to use the default S3 endpoints.
</Info>

## Database Configuration

### PostgreSQL

```bash theme={null}
PG__URL=postgresql://postgres:postgres@postgres:5432/chunkr
```

**PG\_\_URL**

* **Description**: PostgreSQL connection string
* **Format**: `postgresql://[user]:[password]@[host]:[port]/[database]`
* **Default**: `postgresql://postgres:postgres@postgres:5432/chunkr`
* **Production**: Use strong passwords and consider connection pooling

**Connection string components:**

* **User**: `postgres` (default)
* **Password**: `postgres` (default)
* **Host**: `postgres` (Docker service name)
* **Port**: `5432`
* **Database**: `chunkr`

<Warning>
  Always change the default PostgreSQL password in production deployments.
</Warning>

## Cache and Queue Configuration

### Redis

```bash theme={null}
REDIS__URL=redis://redis:6379
```

**REDIS\_\_URL**

* **Description**: Redis connection string for task queue and caching
* **Format**: `redis://[host]:[port]`
* **Default**: `redis://redis:6379`
* **Production**: Consider Redis Cluster or managed Redis for high availability

## Worker Configuration

These variables configure internal service communication:

```bash theme={null}
WORKER__GENERAL_OCR_URL=http://ocr:8000
WORKER__SEGMENTATION_URL=http://segmentation:8000
WORKER__SERVER_URL=http://localhost:8000
```

### Worker Variables

**WORKER\_\_GENERAL\_OCR\_URL**

* **Description**: Internal URL for OCR service
* **Default**: `http://ocr:8000`
* **Notes**: Uses nginx load balancer in front of OCR workers

**WORKER\_\_SEGMENTATION\_URL**

* **Description**: Internal URL for document segmentation service
* **Default**: `http://segmentation:8000`
* **Notes**: Uses nginx load balancer in front of segmentation workers

**WORKER\_\_SERVER\_URL**

* **Description**: URL for task workers to communicate with main server
* **Default**: `http://localhost:8000`
* **Production**: Set to your API server URL

## LLM Configuration

```bash theme={null}
LLM__MODELS_PATH=./models.yaml
```

**LLM\_\_MODELS\_PATH**

* **Description**: Path to the models configuration file
* **Default**: `./models.yaml`
* **Notes**: Defines which LLM models to use for document processing
* **Important**: This file must exist before starting services

<Info>
  The `models.yaml` file is mounted as a read-only volume in the Docker containers.
</Info>

## Frontend API Configuration

```bash theme={null}
VITE_API_URL=http://localhost:8000
```

**VITE\_API\_URL**

* **Description**: API endpoint URL for the web frontend
* **Default**: `http://localhost:8000`
* **Production**: Set to your API server's public URL (e.g., `https://api.yourdomain.com`)

## Production Configuration Example

Here's a complete example for production deployment:

```bash theme={null}
# Authentication
AUTH__KEYCLOAK_URL=https://auth.yourdomain.com

# Storage (AWS S3)
AWS__ACCESS_KEY=AKIAIOSFODNN7EXAMPLE
AWS__SECRET_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS__REGION=us-west-2
# AWS__ENDPOINT not needed for AWS S3
AWS__PRESIGNED_URL_ENDPOINT=https://s3.us-west-2.amazonaws.com

# Database
PG__URL=postgresql://chunkr_user:secure_password_here@db.yourdomain.com:5432/chunkr_prod

# Redis
REDIS__URL=redis://redis.yourdomain.com:6379

# Workers
WORKER__GENERAL_OCR_URL=http://ocr:8000
WORKER__SEGMENTATION_URL=http://segmentation:8000
WORKER__SERVER_URL=https://api.yourdomain.com

# LLM
LLM__MODELS_PATH=/app/models.yaml

# Frontend (Keycloak)
VITE_KEYCLOAK_URL=https://auth.yourdomain.com
VITE_KEYCLOAK_REALM=chunkr
VITE_KEYCLOAK_CLIENT_ID=chunkr-prod
VITE_KEYCLOAK_REDIRECT_URI=https://app.yourdomain.com
VITE_KEYCLOAK_POST_LOGOUT_REDIRECT_URI=https://app.yourdomain.com

# Frontend (API)
VITE_API_URL=https://api.yourdomain.com
```

## HTTPS Configuration

<Warning>
  The default configuration uses HTTP for local development. For production deployments, always use HTTPS.
</Warning>

When deploying with HTTPS:

1. Update all `http://localhost` URLs to your domain with `https://`
2. Configure reverse proxy (nginx, Traefik, etc.) for SSL termination
3. Update Keycloak redirect URIs to use HTTPS
4. Ensure presigned URL endpoints use HTTPS

## Environment Variable Validation

Chunkr validates required environment variables on startup. Missing or invalid variables will prevent services from starting with clear error messages.

### Common Validation Errors

**Missing PG\_\_URL:**

```
Error: Database connection string not configured
```

**Invalid Redis URL:**

```
Error: Cannot connect to Redis at specified URL
```

**Keycloak unreachable:**

```
Error: Authentication service unavailable
```

## Security Best Practices

1. **Never commit `.env` to version control** - Add to `.gitignore`
2. **Use strong passwords** - Especially for database and storage
3. **Rotate credentials regularly** - Update access keys and secrets periodically
4. **Limit network exposure** - Use internal Docker networks where possible
5. **Enable HTTPS in production** - Never use HTTP for production deployments
6. **Use secret management** - Consider HashiCorp Vault or AWS Secrets Manager for production

## Debugging Configuration Issues

### View current configuration

```bash theme={null}
# Check if .env file exists
ls -la .env

# View environment variables in running container (sanitized)
docker compose exec server env | grep -v SECRET | grep -v PASSWORD
```

### Test database connection

```bash theme={null}
docker compose exec server psql $PG__URL -c "SELECT version();"
```

### Test Redis connection

```bash theme={null}
docker compose exec server redis-cli -u $REDIS__URL ping
```

### Verify storage access

```bash theme={null}
# Test MinIO connection
docker compose exec server curl http://minio:9000/minio/health/live
```

## Next Steps

* Complete your [Docker Compose Deployment](/deployment/docker-compose)
* Configure [GPU Setup](/deployment/gpu-setup) for acceleration
* Learn about [Scaling](/deployment/scaling) for production workloads