Configuration

wfx is configured in the following order of precedence using

1. command line parameters (e.g. --log-level),
2. environment variables (prefixed with WFX_, e.g. WFX_LOG_LEVEL),
3. configuration files in YAML format (either via the --config command line parameter or present in one of the default search locations, see wfx --help).

Note that wfx supports configuration file live reloading so that a running wfx instance can be reconfigured without the need for restarting it.

Without configuration,

/usr/bin/wfx

starts wfx using the built-in SQLite-based persistent storage. The northbound (management) API is available at http://127.0.0.1:8081/api/wfx/v1/, whereas the southbound (client) API is available at a different port: http://127.0.0.1:8080/api/wfx/v1.

wfxctl credential helpers

wfxctl can delegate HTTP authentication to a Git-style credential helper. Set --credential-helper=<name> to run wfxctl-credential-<name> get, or pass a path containing / to run that executable directly. WFX_CREDENTIAL_HELPER and the credential-helper YAML key are also supported.

The helper receives protocol, host, and path fields on standard input, one per line, followed by an empty line that terminates the field list. It must return either username and password for Basic authentication, or authtype and credential for schemes such as Bearer authentication, in the same key=value line format. A trailing empty line in the response is optional:

protocol=https
host=wfx.example.com
path=api/wfx/v1/jobs

authtype=Bearer
credential=secret-token

An explicit Authorization header set with --header takes precedence over the credential helper.

Systemd Integration

For production deployments, it’s recommended to run wfx under a service supervisor such as systemd. The share/systemd directory provides pre-configured systemd service units. These units are also included in the distribution packages available with wfx releases.

systemctl enable --now wfx@foo.socket
# multiple instances of wfx can be running at the same time, e.g.
systemctl enable --now wfx@bar.socket

The wfx services launch on-demand, i.e., they start when a client connects:

wfxctl --host unix:///var/run/wfx/foo/client.sock version

Persistent Storage

wfx requires a persistent storage to save workflows and jobs. The default persistent storage is SQLite and requires no further configuration.

The command line argument --storage={sqlite,postgres,mysql} is available to choose a persistent storage backend out of the compiled-in available ones at run-time. Each persistent storage allows further individual configuration via --storage-opt=<options>.

Note that wfx needs to manage the database schema and hence needs appropriate permissions to, e.g., create tables. This is in particular important for the PostgreSQL and MySQL persistent storage options as they’re connecting to an external database service which has to be setup accordingly.

SQLite

SQLite is the default persistent storage and automatically selected if no other persistent storage option is given. Unless overridden, wfx uses the DSN file:wfx.db?_fk=1&_journal=WAL, i.e. the database file wfx.db is created in wfx’s working directory. It can be further configured with the --storage-opt configuration option, see the go-sqlite3 Wiki for available Data Source Name (DSN) options.

As an example, the following command runs a wfx instance with an ephemeral in-memory SQLite database:

wfx --storage sqlite --storage-opt "file:wfx?mode=memory&cache=shared&_fk=1"

Note that all state is lost on wfx exiting so it’s advised to use it for testing purposes only.

PostgreSQL

PostgreSQL is a well-known open source object-relational database. Via environment variables or a Data Source Name (DSN) passed as --storage-opt, the link to a PostgreSQL instance is configured, see PostgreSQL’s parameter key word names for DSN and environment variables documentation for details and available options.

As an example, the following two commands each run a wfx instance connecting to the same PostgreSQL instance but with different configuration means:

# Configuration via DSN key=value string
wfx --storage postgres \
    --storage-opt "host=localhost port=5432 user=wfx password=secret database=wfx" &

# Configuration using environment variables
env PGHOST=localhost \
    PGPORT=5432 \
    PGUSER=wfx \
    PGPASSWORD=secret \
    PGDATABASE=wfx \
    wfx --storage postgres

AWS RDS IAM Authentication

wfx supports AWS RDS IAM authentication for PostgreSQL, enabling passwordless authentication using IAM roles (IRSA in Kubernetes, EC2 instance profiles, etc.):

# Configuration via environment variables (recommended)
export PGHOST=mydb.us-east-1.rds.amazonaws.com
export PGPORT=5432
export PGUSER=myuser
export PGDATABASE=wfx
export PGSSLMODE=require
export WFX_POSTGRES_IAM_AUTH=true
export WFX_POSTGRES_REGION=us-east-1

wfx --storage postgres

MySQL

MySQL is another well-known open source relational database.

Note that MariaDB is currently unsupported due to the lack of certain JSON features (specifically the inability to directly index JSON data).

With the Data Source Name (DSN) passed as --storage-opt, the link to a MySQL instance is configured, see Go’s SQL Driver for available options and as reference.

As an example, the following command runs a wfx instance connecting to a MySQL instance using similar configuration options as for PostgreSQL:

# Configuration via DSN URL string
wfx --storage mysql \
    --storage-opt "wfx:secret@tcp(localhost:3306)/wfx"

Communication Channels

wfx currently supports the following network communication channels:

• http: Unencrypted HTTP
• https: HTTP over TLS (Transport Layer Security)
• unix: Unix-domain sockets

With the --scheme configuration option, one or multiple from the preceding list are enabled. For instance, to use wfx in HTTPS-only mode:

wfx --scheme=https \
    --tls-certificate=localhost/cert.pem \
    --tls-key=localhost/key.pem

To enable both, HTTP and HTTPS, simultaneously, bound to different hosts:

wfx --scheme=http,https \
    --client-host=localhost \
    --client-tls-host=0.0.0.0 \
    --tls-certificate=localhost/cert.pem \
    --tls-key=localhost/key.pem

To exclusively use Unix-domain sockets:

wfx --scheme unix \
    --client-unix-socket /tmp/wfx-client.sock \
    --mgmt-unix-socket /tmp/wfx-mgmt.sock

The following connectivity parameters are available:

Cross-Origin Resource Sharing (CORS)

CORS headers are disabled by default and never applied to the southbound API. The following parameters control CORS for the northbound API:

--cors-allow-credentials requires explicit origins. Configuration is rejected if --cors-allowed-origins contains * while credentials are enabled.

For example, to enable CORS headers:

wfx --cors-enabled --cors-allowed-origins https://wfx-ui.company.cloud

File Server

wfx comes with a built-in file server that serves artifacts at http://<wfx host:{client,mgmt} port>/download/. This feature is particularly useful for dynamic deployments or when an external file storage solution is unavailable. To configure the directory that backs the file server URL’s contents, use the --simple-fileserver=/path/to/folder option.

Note that this feature is disabled by default and must be explicitly enabled at run-time using this option.