Skip to content

Configuration Reference

Configuration File

ionflow uses the YAML file format for configuration.

Configuration files are loaded as follows: 

$ ionflow server -c <path/to/config-file.yaml>

A full configuration reference file is shown below, this provides comments and all available options.

ionflow.yaml
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
# The address to bind to for HTTP.
http_listen_addr: ":8080"

# The address to bind to for HTTPS.
https_listen_addr: ":8443"

# The address to bind to for the metrics.
metrics_listen_addr: ":8081"

# The public URL at which the ionflow server can be reached by clients and the CLI.
server_url: "https://ionflow.example.com"

keys:
  # A private, 32 bytes in hex, system admin key
  # Use this key with the CLI when configuring system-wide resources
  # A key can be generated by:
  # - ionflow genkey
  # - openssl rand -hex 32
  system_admin_key:

tls:
  # Disable TLS (not recommended)
  # Use this flag to disable TLS e.g. when running behind a reverse proxy
  disable: false
  # The path to the certificate for TLS.
  # Required when TLS is enabled
  cert_file: ""
  # The path to the private key for the certificate.
  # Required when TLS is enabled
  key_file: ""

provider:
  # The issuer URL of the OAuth2 provider.
  # This URL is used to verify the authenticity of the provider
  # and to obtain the provider's metadata, such as the supported grant types and scopes.
  # The default value is empty.
  issuer:

  # The client ID of the application.
  # This ID is used to identify the application when requesting access to protected resources.
  # The default value is empty.
  client_id:

  # The client secret of the application.
  # This secret is used to authenticate the application when requesting access to protected resources.
  # The default value is empty.
  client_secret:

  # The scopes that the application is requesting access to.
  # The scopes define the permissions that the application has for accessing the protected resources.
  # The default value is empty.
  scopes:

database:
  # The URL for connecting to the database
  # e.g
  # url: "/data/ionflow.db?_pragma=busy_timeout(5000)&_pragma=journal_mode(WAL)"
  # url: "postgres://ionflow:ionflow@localhost/ionflow?sslmode=disable"
  url: "./ionflow.db"

kutlass:
  # Specifies the environment in which the workflow will be executed. 
  runtime_env: native
  # The directory where workflow files will be loaded from on startup. 
  # Use this directory to seed the runtime with an initial set of workflows; workflows can
  # also be added to the database via API.
  # This directory must exist and be readable by the user running the application.
  workflow_dir: /var/lib/ionflow/kutlass
  # Workflow retry settings
  kutlass_retry:
    # The initial delay before retrying a failed workflow.
    # This delay is specified in ISO 8601 duration format,
    # and it can include units such as seconds, minutes, hours, and days.
    # For example, "PT30S" represents a delay of 30 seconds,
    # and "P1DT2H" represents a delay of 1 day and 2 hours.
    # The default value is PT0.1S (100 milliseconds).
    delay: PT0.1S

    # The maximum number of attempts to retry a failed workflow.
    # This value can be either "unlimited" or an integer,
    # and it determines the maximum number of times that a failed workflow will be retried.
    # When the number of attempts exceeds this value, the workflow will be terminated.
    # The default value is unlimited.
    max_attempts: unlimited

    # The maximum delay before retrying a failed workflow.
    # This delay is specified in ISO 8601 duration format,
    # and it can include units such as seconds, minutes, hours, and days.
    # For example, "PT30S" represents a delay of 30 seconds,
    # and "P1DT2H" represents a delay of 1 day and 2 hours.
    # The default value is PT1H (1 hour).
    max_delay: PT1H

    # The increment of the delay between each retry.
    # This increment is a static value that is added to the previous delay,
    # and it is specified in ISO 8601 time format.
    # For example, "PT1S" represents an increment of 1 second,
    # and "PT2M" represents an increment of 2 minutes.
    increment: 

    # The multiplier of the delay between each retry.
    # This multiplier is applied to the previous delay, and it is a decimal value between 0 and 1.
    # The default value is 2.
    multiplier: 2

    # The jitter of the delay between each retry.
    # This jitter can be either a float value or a string,
    # and it determines the maximum amount of random time that is added or subtracted
    # from the delay between each retry of a failed workflow.
    #
    # If the jitter is specified as a float value, it represents the maximum amount of
    # random time relative to the total delay. For example, a jitter value of 0.5
    # means that the random time can be between 0 and 50% of the total delay.
    #
    # If the jitter is specified as a string, it represents the absolute maximum
    # amount of random time in ISO 8601 duration format. For example, "PT1S"
    # represents a maximum of 1 second, and "PT2M" represents a maximum of 2 minutes.
    #
    # The jitter can be used to avoid congestion and reduce the impact of retries on the system.
    # The default value is 0.1
    jitter: 0.1

logging:
  # Whether the logger is in development mode.
  # In development mode, the logger will take stacktraces more liberally
  # and will change the behavior of DPanicLevel.
  # The default value is false.
  development: false
  # The format of the log messages.
  # Available levels: json, console
  # The default format is console
  format: console
  # The log level for the application
  # Available levels: debug, info, warn, error, fatal
  # The default level is info
  level: info

stream:
  # Whether to enable tracing for Jetstream messages.
  # Tracing can be useful for debugging and troubleshooting purposes,
  # but it can also increase the amount of data logged,
  # so it should be used with caution.
  # The default value is false.
  trace: false

  # The directory where stream files will be stored.
  # This directory must exist and be writable by the user running the application.
  # The default value is /var/lib/ionflow/ionrow
  streamdir: /var/lib/ionflow/ionrow

ionbay:
  # The directory where Ionbay will monitor for file changes.
  # This directory must exist and be readable by the user running the application.
  # The default value is /var/lib/ionflow/ionbay.
  baydir: /var/lib/ionflow/ionbay

  # Whether to delete the monitored files when the application exits.
  # This setting can be useful to automatically clean up temporary files
  # that are no longer needed after the application has finished running.
  # The default value is false.
  delete_on_exit: false

Environment Variables

Configuration can be overriden using environment variables. These values should be used for passing in compromising credentials, environment specific data, and granular controls.

Name Description Default Value
IONFLOW_HTTP_LISTEN_ADDR The address to bind to for HTTP. :8080
IONFLOW_HTTPS_LISTEN_ADDR The address to bind to for HTTPS. :8443
IONFLOW_SERVER_URL The public URL at which the ionflow server can be reached by clients and the CLI. https://localhost:8443
IONFLOW_SYSTEM_ADMIN_KEY A private, 32 bytes in hex, system admin key
Use this key with the CLI when configuring system-wide resources
A key can be generated by:
- ionflow genkey
- openssl rand -hex 32		 ""
IONFLOW_DB_URL The URL for connecting to the database
e.g
- url: "/data/ionflow.db?_pragma=busy_timeout(5000)&_pragma=journal_mode(WAL)"
- url: "postgres://ionflow:ionflow@localhost/ionflow?sslmode=disable"		 ionflow.db
IONFLOW_TLS_DISABLE Disable TLS (not recommended)
Use this flag to disable TLS e.g. when running behind a reverse proxy		 false
IONFLOW_TLS_CERT_FILE The path to the certificate for TLS. Required when TLS is enabled. ""
IONFLOW_TLS_KEY_FILE The path to the private key for the certificate. Required when TLS is enabled. ""
IONFLOW_METRICS_LISTEN_ADDR The address to bind to for the metrics. :8081
IONFLOW_LOGGING_LEVEL The log level for the application.
Available levels: debug, info, warn, error, fatal
 info
IONFLOW_LOGGING_FORMAT The format of the log messages. Available levels: json, console. console
IONFLOW_LOGGING_DEVELOPMENT Whether the logger is in development mode. In development mode, the logger will take stacktraces more liberally and will change the behavior of DPanicLevel. false
IONFLOW_KUTLASS_RUNTIME_ENVIRONMENT Specifies the environment in which the workflow will be executed. native
IONFLOW_KUTLASS_WORKFLOW_DIR The directory where workflow files will be loaded from on startup. Use this directory to seed the runtime with an initial set of workflows; can also be added to the database via API. This directory must exist and be readable by the user running the application. ""
IONFLOW_KUTLASS_DEFAULT_RETRY_DELAY The initial delay before retrying a failed workflow. This delay is specified in ISO 8601 duration format, and it can include units such as seconds, minutes, hours, and days. For example, "PT30S" represents a delay of 30 seconds, and "P1DT2H" represents a delay of 1 day and 2 hours. PT0.1S (100 ms)
IONFLOW_KUTLASS_DEFAULT_RETRY_MAX_ATTEMPTS The maximum number of attempts to retry a failed workflow. This value can be either "unlimited" or an integer, and it determines the maximum number of times that a failed workflow will be retried. When the number of attempts exceeds this value, the workflow will be terminated. unlimited
IONFLOW_KUTLASS_DEFAULT_RETRY_MAX_DELAY The maximum delay before retrying a failed workflow. This delay is specified in ISO 8601 duration format, and it can include units such as seconds, minutes, hours, and days. For example, "PT30S" represents a delay of 30 seconds, and "P1DT2H" represents a delay of 1 day and 2 hours. PT1H (1 hour)
IONFLOW_KUTLASS_DEFAULT_RETRY_INCREMENT The increment of the delay between each retry. This increment is a static value that is added to the previous delay, and it is specified in ISO 8601 time format. For example, "PT1S" represents an increment of 1 second, and "PT2M" represents an increment of 2 minutes. 0
IONFLOW_KUTLASS_DEFAULT_RETRY_MULTIPLIER The multiplier of the delay between each retry. This multiplier is applied to the previous delay, and it is a decimal value between 0 and 1. 2
IONFLOW_KUTLASS_DEFAULT_RETRY_JITTER The jitter of the delay between each retry. This jitter can be either a float value or a string (ISO 8601 duration), and it determines the maximum amount of random time that is added or subtracted from the delay between each retry of a failed workflow. 0.1
IONFLOW_IONBAY_BAY_DIR The directory where Ionbay will monitor for file changes. This directory must exist and be readable by the user running the application. /var/lib/ionflow/ionbay
IONFLOW_IONBAY_DELETE_ON_EXIT Whether to delete the monitored files when the application exits. This setting can be useful to automatically clean up temporary files that are no longer needed after the application has finished running. false
IONFLOW_STREAM_TRACE Whether to enable tracing for Jetstream messages. Tracing can be useful for debugging and troubleshooting purposes, but it can also increase the amount of data logged, so it should be used with caution false
IONFLOW_STREAM_DIRECTORY The directory where stream files will be stored. This directory must exist and be writable by the user running the application. /var/lib/ionflow/ionrow