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
# 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 |