Skip to main content

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.

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

​
Quick Setup

1

Copy example file

cp .env.example .env
2

Review and modify

The default values work for local development. Modify for production deployment.
3

Load environment

Docker Compose automatically loads .env when starting services.
For local development with Docker Compose, the default values in .env.example work out of the box.

​
Authentication Configuration

​
Keycloak Settings

Keycloak handles authentication and authorization for Chunkr. 
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: 
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
VariableDescriptionDefault
VITE_KEYCLOAK_URLPublic-facing Keycloak URL accessible from browserhttp://localhost:8080
VITE_KEYCLOAK_REALMKeycloak realm namechunkr
VITE_KEYCLOAK_CLIENT_IDOAuth client IDchunkr
VITE_KEYCLOAK_REDIRECT_URIOAuth callback URL after loginhttp://localhost:5173
VITE_KEYCLOAK_POST_LOGOUT_REDIRECT_URIRedirect URL after logouthttp://localhost:5173
In production, update all localhost URLs to your actual domain names with HTTPS.

​
Storage Configuration (AWS/MinIO)

Chunkr uses S3-compatible storage for document files. By default, it uses MinIO for local storage. 
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)
When using AWS S3 in production, you can omit AWS__ENDPOINT to use the default S3 endpoints.

​
Database Configuration

​
PostgreSQL

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
Always change the default PostgreSQL password in production deployments.

​
Cache and Queue Configuration

​
Redis

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: 
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

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
The models.yaml file is mounted as a read-only volume in the Docker containers.

​
Frontend API Configuration

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

The default configuration uses HTTP for local development. For production deployments, always use HTTPS.
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

# 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

docker compose exec server psql $PG__URL -c "SELECT version();"

​
Test Redis connection

docker compose exec server redis-cli -u $REDIS__URL ping

​
Verify storage access

# Test MinIO connection
docker compose exec server curl http://minio:9000/minio/health/live

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us