Skip to main content

Container Deployment

The IDIAL-APP is delivered as a Docker container. Before the first start, a master encryption key must be generated and persistent volumes must be configured. On every start, the container automatically validates its configuration — if any check fails, it exits with a defined exit code before the application starts.

Prerequisites​

  • Docker Engine ≥ 20.10 or Docker Compose ≥ 2.x
  • Access to the BxC container registry

Generate the Master Key​

The master key is the only external secret the IDIAL-APP requires. It encrypts and decrypts all credentials stored within the application (IDIAL API keys, OIDC secrets, etc.). The key must be base64-encoded and decode to exactly 32 bytes (256 bits).

danger

Store this key securely. A lost master key means all stored credentials are permanently unrecoverable. The key must be identical on every container restart — a changed key will cause startup to fail with exit code 21.

The key is passed to the IDIAL-APP via an environment variable or a key file. In production environments, the IDIAL_MASTER_KEY environment variable is the preferred approach: the key can be injected at runtime from an HSM or KMS (e.g., PKCS#11, AWS KMS, HashiCorp Vault) and never resides unencrypted on the filesystem. For lab and test environments, the file-based approach (IDIAL_MASTER_KEY_FILE) is a simpler alternative.

Lab setup — quick key generation
openssl rand -base64 32

In production environments, ensure the key is generated with sufficient entropy, stored securely, and backed up separately.

Create the directory structure​

mkdir -p idial-app/{secrets,data,config,logs}
cd idial-app

Store the master key (lab setup)​

openssl rand -base64 32 > secrets/master_key.txt
chmod 600 secrets/master_key.txt

docker-compose.yml​

services:
  idial-app:
    image: registry.bxc-security.com/idial-app:latest
    container_name: idial-app
    restart: unless-stopped

    environment:
      - IDIAL_MASTER_KEY_FILE=/run/secrets/master_key
      - PORT=5555
      - LOG_LEVEL=INFO

    secrets:
      - source: master_key
        target: /run/secrets/master_key
        mode: 0400

    volumes:
      - ./data:/app/runtime_data
      - ./config:/app/config
      - ./logs:/app/logs

    ports:
      - "443:5555"

    healthcheck:
      test: ["CMD", "curl", "-fsk", "https://localhost:5555/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s

secrets:
  master_key:
    file: secrets/master_key.txt

Start the container​

docker compose up -d

First Start vs. Restart​

First start​

On the first start, the container automatically creates the following files and structures:

Path in containerContentAction
/app/runtime_data/containers.jsonEmpty container listCreated automatically
/app/runtime_data/users.jsonCreated on first login—
/app/config/crypto/encrypted_keystore.jsonEncrypted test dataset for key validationCreated automatically
/app/runtime_data/certs/cert.pem + key.pemSelf-signed TLS certificate (4096-bit RSA)Generated automatically

The first start typically takes 8–10 seconds (including TLS certificate generation).

Restart​

On a restart, the container runs through the same validation chain but significantly faster (~2–3 seconds), since directories, keystore, and TLS certificate already exist.

warning

The same master key is required. If a different key is provided on restart, keystore validation fails (exit code 23) and the container will not start.

Startup Validation Chain​

The entrypoint script validates the following on every start, in order:

  1. Crypto configuration — master key present, Base64 format correct, exactly 32 decoded bytes, existing keystore decryptable
  2. Directories and write permissions — volumes mounted and writable
  3. Port availability — configured port not already in use
  4. Crypto health check — encryption and decryption functional
  5. TLS setup — load custom certificates or generate self-signed ones
  6. Application start — Gunicorn with 4 worker processes

If any step fails, the container exits with a defined exit code. See Configuration Reference for details.

Using Custom TLS Certificates​

By default, the container generates a self-signed certificate on first start. To use your own certificate, place the files in the volume before starting:

cp /path/to/cert.pem data/certs/cert.pem
cp /path/to/key.pem  data/certs/key.pem

The container detects existing certificates automatically and skips generation.

Verify Health​

# Basic health check (no authentication required)
curl -sk https://localhost/api/health
# Response: {"status": "healthy", "service": "IDIAL Management API"}

# Crypto system status (admin authentication required)
curl -sk https://localhost/api/health/crypto

Check Logs​

# Live log stream
docker compose logs -f idial-app

# Startup output only (last 50 lines)
docker compose logs --tail=50 idial-app

Expected output on successful start:

[OK] Master key provided via environment variable
[OK] Master key format validated (32 bytes)
[OK] Crypto system test passed
[OK] Write permissions verified
[OK] SSL certificates found
[OK] All validations passed - starting application
Starting IDIAL Web Backend with Gunicorn...
[INFO] Starting HTTPS server on port 5555