Configuration Reference

Environment Variables

Encryption (Required)

Exactly one of the following variables must be set:

Variable	Recommended for	Description
IDIAL_MASTER_KEY	Production	Master key as a base64-encoded value injected at runtime into the environment variable. Enables integration with HSM or KMS solutions (e.g., PKCS#11, AWS KMS, HashiCorp Vault) so the key never resides unencrypted on disk.
IDIAL_MASTER_KEY_FILE	Lab / Test	Path to a file containing the master key. Simpler to set up, but requires strict filesystem access controls: only authorized identities may read the key file. Not recommended for environments with elevated security requirements.

The key must be base64-encoded and decode to exactly 32 bytes (256 bits).

Lab setup — generating a key

For test environments, a key can be quickly generated with openssl rand -base64 32.

Production environments have stricter requirements: the key must be generated with sufficient entropy, stored securely, and backed up separately. A lost master key means permanent loss of access to all encrypted content in the container.

Application (Optional)

Variable	Default	Description
PORT	5555	Port the application server listens on
SERVER_HOST	0.0.0.0	Server bind address

Logging (Optional)

Variable	Default	Accepted values
LOG_LEVEL	INFO	DEBUG, INFO, WARNING, ERROR, CRITICAL
LOG_FILE_ENABLED	true	true / false

---

Volume Paths

Path in container	Purpose	Persistent required
/app/runtime_data	Application database — all runtime data of the application	Yes
/app/config	Configuration files and encrypted key store	Yes
/app/logs	Application logs	No (recommended)

warning

If persistent volumes are not mounted on restart, all application data is lost. Volumes are initialized automatically when they are empty or new.

First-Start Initialization

On the first start with empty volumes, the container automatically initializes:

• Database — All application data is created in an encrypted data store
• Key store — An encrypted keystore is generated and used on every subsequent start to validate the master key
• TLS certificate — A self-signed certificate is generated so the container is immediately reachable via HTTPS

No manual creation of files or directory structures is required.

---

Ports

Port	Protocol	Configurable via
5555 (default)	HTTPS	PORT environment variable

In a Docker Compose deployment, port 5555 is typically mapped to the host's port 443:

ports:
  - "443:5555"

---

Exit Codes

The container returns a defined exit code on startup failure that identifies the failure area.

Crypto Errors (20–23)

Code	Cause	Resolution
20	Neither IDIAL_MASTER_KEY nor IDIAL_MASTER_KEY_FILE is set	Configure one of the two variables
21	Master key has wrong format or length (does not decode to 32 bytes)	Verify the key — it must be base64-encoded and decode to exactly 32 bytes
22	File at IDIAL_MASTER_KEY_FILE not readable or not found	Check the path and file permissions
23	Crypto health check failed — existing key store cannot be decrypted	Verify that the same master key as on first start is being provided

Port Errors (30)

Code	Cause	Resolution
30	Configured port already in use	Choose a different port via the PORT variable or stop the conflicting process

Configuration Errors (40–42)

Code	Cause	Resolution
40	Data volume not writable	Check volume mount and file permissions
41	Configuration volume not writable	Check volume mount and file permissions
42	Application build not found in container image	Check the container image

Config File Errors (10–11)

Code	Cause	Resolution
10	Configuration file present but invalid	Check the configuration file for valid JSON or remove it (will be recreated)
11	Invalid environment variable (e.g., PORT outside 1–65535)	Check the value of the affected variable

---

Health Check Endpoints

Endpoint	Auth	Description
GET /api/health	None	Returns {"status": "healthy"} when the application is running
GET /api/health/crypto	Admin	Detailed status of the encryption system