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

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

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

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:[e-mail]: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

• Complete your Docker Compose Deployment
• Configure GPU Setup for acceleration
• Learn about Scaling for production workloads