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
• SSO Configuration
• TLS/SSL Configuration
• Logging & Debugging
• WebSocket Configuration

Backend Server¶

Core Configuration¶

Data & Storage¶

Network Share Storage¶

Optional. Lets the server keep its wordlists and rules on a mounted network share instead of local disk, so servers (and select agents) don't each need a large SSD. See Storage Architecture for the full model.

Whether the server reads wordlists/rules from local disk or the share is database state (storage_backend = local|share), flipped by the in-app migration — not an environment variable. Hashlists, binaries, charsets, uploads and the potfile always stay local. The share is mounted by docker-compose with the operator's own credentials; KrakenHashes stores no share credentials.

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.

Storage Tier¶

Controls how an agent obtains wordlists/rules. These are a seed: they set the agent's initial tier/mount, reported to the server at registration; afterwards the admin UI (Admin → System Settings → Storage, per agent) is authoritative and re-asserts its value on each reconnect. Equivalent CLI flags are --storage-tier and --network-share-mount-path. See agent configuration.

Docker & Deployment¶

Container Configuration¶

Volume Mounts¶

Port Mappings¶

Database¶

Connection Settings¶

The backend builds the connection string dynamically from these variables.

Authentication & Security¶

JWT Configuration¶

CORS Configuration¶

Secret Encryption¶

The key is resolved in this order:

1. KH_ENCRYPTION_KEY
2. SSO_ENCRYPTION_KEY (legacy)
3. $KH_CONFIG_DIR/secrets/encryption.key — generated on first boot at mode 0600 inside a 0700 directory, then reused on every later start
4. A throwaway key, only when KH_ALLOW_EPHEMERAL_KEY=true

Setting either variable is therefore optional: a server with neither still keeps its secrets across restarts. Set one explicitly to hold the key outside the config directory, or to share a single key across several servers.

SSO Configuration¶

Single-Instance Guard¶

Only one backend may run against a given database: the job scheduler's concurrency guard is process-local, so two backends dispatch the same keyspace intervals twice.

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_HOST=localhost
DB_PORT=5432
DB_NAME=krakenhashes
DB_USER=krakenhashes
DB_PASSWORD=krakenhashes
DB_ARGUMENTS=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