Configuration Reference

This guide covers all configuration options for Kuetix Engine, including environment variables, configuration files, and workflow settings.

:::info Configuration is Optional All configuration is optional. The engine provides sensible defaults for all settings, allowing you to run workflows immediately without any configuration files. You only need to configure what differs from the defaults. :::

Quick Start - Zero Configuration

You can run workflows immediately without any configuration:

# No .env file needed
# No .ini file needed
# Just run your workflow!
kuetix my_workflow

# The engine will use defaults:
# - Environment: production
# - Debug: false
# - Retry: 3 times
# - RetryDelay: 1 second
# - RestartPolicy: on-failure

Default Values

When no configuration file is provided, the engine uses these defaults:

ApplicationConfig {
    Env:           "production"
    Debug:         false
    Locale:        "en"
    LogFile:       "log/application.log"
    ModulesPath:   "modules"
    WorkflowsPath: "workflows"
}

WorkflowConfigItem {
    Amount:        1
    Retry:         3
    RetryDelay:    1              // seconds
    RestartPolicy: "on-failure"
}

Environment Variables

:::tip Optional Configuration Environment variables are completely optional. If no .env file is present, the engine defaults to production mode with config path etc/production. :::

Core Variables

Variable	Description	Default	Required
`NAME`	Application name	`kuetix`	No
`APP_ENV`	Environment (development/production)	`production`	No
`CONFIG_PATH`	Path to configuration directory	`etc/{APP_ENV}`	No

Setup (Optional)

Copy the example environment file (if you want to customize):

cp .env.example .env

Edit .env with your settings:

NAME=kuetix
APP_ENV=development
CONFIG_PATH=etc/development

Note: If you don't create a .env file, the engine will run in production mode.

Configuration Files

:::tip Optional INI Files Configuration files (.ini) are completely optional. The engine works out-of-the-box with default values. Only create configuration files when you need to override defaults. :::

Directory Structure (Optional)

etc/
├── development/
│   └── engine.ini
└── production/
    └── engine.ini

engine.ini Format

Configuration uses INI file format. All fields are optional with sensible defaults:

[application]
name = kuetix
env = development
debug = true
timezone = UTC
locale = en
log_file = log/engine.log
modules_path = modules
workflows_path = workflows

# You can also configure workflows in the INI file
[workflow.my_workflow]
name = my_workflow
path = workflows/my_workflow/workflow.wsl
amount = 5
retry = 3
retry_delay = 1
restart_policy = on-failure

Config Structure

Config

The main configuration structure:

type Config struct {
    FilePath       string               // Config file location
    Application    ApplicationConfig    // Application settings
    WorkflowConfig []WorkflowConfigItem // Workflow definitions
    Items          IniConfig            // Additional custom items
}

ApplicationConfig

Application-level settings with default values:

type ApplicationConfig struct {
    Name          string    // Application name
    Env           string    // Environment (default: "production")
    Debug         bool      // Enable debug logging (default: false)
    Timezone      string    // Timezone setting (default: "")
    Locale        string    // Locale setting (default: "en")
    Version       string    // Application version
    BuildTime     string    // Build timestamp
    LogFile       string    // Log file path (default: "log/application.log")
    ModulesPath   string    // Path to modules directory (default: "modules")
    WorkflowsPath string    // Path to workflows directory (default: "workflows")
    Items         IniConfig // Additional custom items
}

Default values when no config file exists:

Env: "production"
Debug: false
Locale: "en"
LogFile: "log/application.log"
ModulesPath: "modules"
WorkflowsPath: "workflows"

Workflow Configuration

WorkflowConfigItem

Configure individual workflows. All fields except Name and Path have default values:

type WorkflowConfigItem struct {
    Name          string                 // Workflow name (required)
    Path          string                 // Workflow file path (required)
    Amount        int                    // Concurrency level (default: 1)
    Retry         int                    // Retry count (default: 3)
    RetryDelay    int                    // Delay between retries in seconds (default: 1)
    RestartPolicy string                 // Restart policy (default: "on-failure")
    Options       map[string]interface{} // Additional options
}

Default values:

Amount: 1 (single instance)
Retry: 3 (retry up to 3 times on failure)
RetryDelay: 1 (1 second between retries)
RestartPolicy: "on-failure" (restart only on errors)

Restart Policies

Policy	Constant	Behavior
`always`	`RestartPolicyAlways`	Always restart after completion
`on-failure`	`RestartPolicyOnFailure`	Restart only on error
`stop`	`RestartPolicyStop`	Stop after first execution

Example Configuration

wfConfig := domain.WorkflowConfigItem{
    Name:          "my_workflow",
    Path:          "runtime/workflows/my_workflow/workflow.wsl",
    Amount:        5,           // Run 5 concurrent instances
    Retry:         3,           // Retry 3 times on failure
    RetryDelay:    1,           // Wait 1 second between retries
    RestartPolicy: "on-failure",
    Options: map[string]interface{}{
        "debug": true,
    },
}

Boot Options

Options Struct

type Options struct {
    EngineName    string              // Engine identifier
    ConfigName    string              // Configuration profile name
    Verbose       bool                // Enable verbose logging
    Quiet         bool                // Suppress output
    Amount        int                 // Concurrency level
    Retry         int                 // Retry attempts on failure
    RetryDelay    int                 // Delay in seconds between retries
    RestartPolicy string              // Restart policy: always, on-failure, stop
    Workflow      string              // Workflow name to execute
    Version       string              // Engine version
    BuildTime     string              // Build timestamp
    LogPath       string              // Log file path
    Config        *domain.Config      // Pre-loaded configuration
    Args          []string            // Additional arguments (key=value)
    Settings      map[string]interface{} // Additional settings
}

Example Usage

options := &domain.Options{
    EngineName:    "kuetix",
    ConfigName:    "development",
    Verbose:       true,
    Amount:        1,
    Retry:         3,
    RetryDelay:    2,
    RestartPolicy: "on-failure",
    LogPath:       "log/my_workflow.log",
    Workflow:      "hello_world",
    Args:          []string{"message=Hello"},
}

responses := engine.RunWorkflow("production", options)

Logging Configuration

Log Levels

Level	Description
`debug`	Detailed debugging information
`info`	General operational information
`warning`	Warning messages
`error`	Error messages
`fatal`	Fatal errors that stop execution

Log Output

Logs are written to runtime/log/ by default. Configure the log file in your configuration:

[application]
log_file = runtime/log/engine.log

Programmatic Logging

import "github.com/kuetix/logger"

logger.Debug("Debug message")
logger.Info("Info message")
logger.Warn("Warning message")
logger.Error("Error message")

Module Configuration

Module Path

Set the modules directory in configuration:

[application]
modules_path = modules

Resolvers

Workflows specify which modules they use via the import statement in WSL:

import services/common
import auth/login

These imports are resolved at runtime from the configured modules path.

Environment-Specific Configuration

Development

[application]
name = kuetix
debug = true
log_file = runtime/log/development.log

[server]
port = 8080

Production

[application]
name = kuetix
debug = false
log_file = /var/log/kuetix/engine.log

[server]
port = 80

Switching Environments

Set the environment via the APP_ENV variable:

# Development
APP_ENV=development ./runtime/bin/myapp-cli hello_world

# Production
APP_ENV=production ./runtime/bin/myapp-cli hello_world

Docker Configuration

docker-compose.yaml

version: '3.8'

services:
  kuetix:
    build: .
    environment:
      - NAME=kuetix
      - APP_ENV=production
      - CONFIG_PATH=/app/runtime/etc
    volumes:
      - ./runtime:/app/runtime
    ports:
      - "8080:8080"

Environment File

Use .env with Docker Compose:

docker-compose --env-file .env up

CLI Reference - Command-line options
Module System - Module configuration
Architecture - System overview

Quick Start - Zero Configuration​

Default Values​

Environment Variables​

Core Variables​

Setup (Optional)​

Configuration Files​

Directory Structure (Optional)​

engine.ini Format​

Config Structure​

Config​

ApplicationConfig​

Workflow Configuration​

WorkflowConfigItem​

Restart Policies​

Example Configuration​

Boot Options​

Options Struct​

Example Usage​

Logging Configuration​

Log Levels​

Log Output​

Programmatic Logging​

Module Configuration​

Module Path​

Resolvers​

Environment-Specific Configuration​

Development​

Production​

Switching Environments​

Docker Configuration​

docker-compose.yaml​

Environment File​

Related Topics​