Environment Variables Reference¶

This document provides a comprehensive reference for all environment variables used in the KrakenHashes system.

Table of Contents¶

• Backend Server
• Frontend Application
• Agent
• Docker & Deployment
• Database
• Authentication & Security
• TLS/SSL Configuration
• Logging & Debugging
• WebSocket Configuration

Backend Server¶

Core Configuration¶

Data & Storage¶

Directory Structure¶

The backend automatically creates the following subdirectories under KH_DATA_DIR: - binaries/ - Executable files (hashcat, john, etc.) - wordlists/ - Wordlist files with subdirectories: - general/ - Common wordlists - specialized/ - Domain-specific wordlists - targeted/ - Client/project-specific wordlists - custom/ - User-created wordlists - rules/ - Rule files with subdirectories: - hashcat/ - Hashcat-compatible rules - john/ - John the Ripper rules - custom/ - User-created rules - hashlists/ - Hash files and crack results

Frontend Application¶

API Configuration¶

Development Server¶

Debug Configuration¶

Agent¶

Core Configuration¶

The agent creates the same directory structure as the backend under its data directory.

Docker & Deployment¶

Container Configuration¶

Volume Mounts¶

Port Mappings¶

Database¶

Connection Settings¶

* Either DATABASE_URL or individual DB_* variables must be set ** Required if DATABASE_URL is not provided

Authentication & Security¶

JWT Configuration¶

CORS Configuration¶

TLS/SSL Configuration¶

Certificate Mode¶

Certificate Details¶

Self-Signed CA Configuration¶

User-Provided Certificates¶

* Required when KH_TLS_MODE=provided

Let's Encrypt (Certbot) Configuration¶

* Required when KH_TLS_MODE=certbot ** Required for DNS-01 challenge with Cloudflare

Logging & Debugging¶

Debug Flags¶

Log Directories¶

Nginx Logging¶

WebSocket Configuration¶

Duration format: 10s, 5m, 1h, etc.

Environment Variable Priority¶

1. Explicit environment variables take precedence
2. Docker environment files (.env) are loaded next
3. Default values are used as fallback

Best Practices¶

1. Security: Never commit sensitive values (passwords, JWT secrets) to version control
2. Production: Always set strong values for JWT_SECRET, DB_PASSWORD, and certificate configurations
3. Development: Use .env files for local development configuration
4. Docker: Mount configuration directories to persist data between container restarts
5. Paths: Use absolute paths for file and directory configurations
6. Validation: The backend validates critical environment variables on startup

Example Configurations¶

Minimal Development Setup¶

# .env
DB_CONNECTION_STRING=postgres://krakenhashes:krakenhashes@localhost:5432/krakenhashes?sslmode=disable
JWT_SECRET=dev-secret-change-in-production
DEBUG=true

Production Docker Setup¶

# .env.production
PUID=1000
PGID=1000
DB_HOST=postgres
DB_PASSWORD=strong-random-password
JWT_SECRET=very-long-random-secret
KH_TLS_MODE=certbot
KH_CERTBOT_DOMAIN=kraken.example.com
KH_CERTBOT_EMAIL=admin@example.com
CLOUDFLARE_API_TOKEN=your-cloudflare-api-token
DEBUG=false
LOG_LEVEL=WARNING

Agent Configuration¶

# Agent environment
KH_DATA_DIR=/opt/krakenhashes-agent/data
KH_CONFIG_DIR=/opt/krakenhashes-agent/config
HASHCAT_EXTRA_PARAMS=-O -w 3