Configuration

Overview

This section explains how to completely configure a WorkflowGen container, including the web.config file, iisnode configuration for Node.js applications, database connection strings, etc. Everything is configurable via an environment variable except the license file, which is configured via a volume.

WorkflowGen environment variables

WorkflowGen's image provides a number of specific environment variables that makes specific configurations possible. The following table provides descriptions of each of them:

Variable	Description & values
WFGEN_ADMIN_USERNAME	The username for the WorkflowGen Administrator account Changing this value is useful when you're configuring this image with an OpenID provider. You can set it to a username that exists on the provider that you have access to. Then, when you browse to WorkflowGen, you can authenticate with it and it will log you in as an administrator. For example, if you have a username on your provider named [e-mail], then you can set this environment variable to this username and authenticate with it in the container to have administrative access to WorkflowGen. ✏️ Note: If you change this, make sure to update the database as well. Possible values: wfgen_admin (default)
WFGEN_DATABASE_CONNECTION_STRING	Required variable The connection string of the main database source This environment variable must be present, or else the container will throw an error and exit.
WFGEN_DATABASE_READONLY_ CONNECTION_STRING	The connection string of the read-only database source for a database setup with replicas
WFGEN_AUTH_MODE	This variable indicates which authentication method to be used by WorkflowGen Possible values: adfs application (default) auth0 azure-v1 basic ms-identity-v2 okta windows
WFGEN_GEN_APP_SYM_ENCRYPT_KEY	Indicates whether or not the ApplicationSecurityPasswordSymmetricEncryptionKey should be generated if no value is provided If Y, the ApplicationSecurityPasswordSymmetricEncryptionKey is regenerated when the container restarts. It is not compatible for usage in production because the secrets will be encrypted with different keys. Therefore, use Y only for developing or testing a single container scenario. Possible values: Y (default), N
WFGEN_LICENSE_FILE_NAME	File name (including extension) of the license needed in the C:\licenses volume If none is specified, the first file found is taken.
WFGEN_START_SERVICE	Indicates what the container should run You can either run the WorkflowGen web application or Windows Services, or both. In a cluster, you'd probably want to have multiple containers in web app mode and only one container in Windows Services mode. You can also divide more by running multiple containers in web app mode, one container in engine mode, and one container in directory sync mode. Possible values: all (default) dir_sync engine web_apps win_services
WFGEN_MACHINE_KEY_VALIDATION_KEY	Represents the validationKey property of the machineKey element in the web.config file By default, IIS generates one when it isn't there. It's recommended to use this environment variable to share the machine key between instances of this container (e.g. in a web farm). See the Resolving view state message authentication code (MAC) errors and MachineKeySection Class Microsoft articles for more details.
WFGEN_MACHINE_KEY_DECRYPTION_KEY	Represents the decryptionKey property of the machineKey element in the web.config file By default, IIS generates one when it isn't there. It's recommended to use this environment variable to share the machine key between instances of this container (e.g. in a web farm). See the Resolving view state message authentication code (MAC) errors and MachineKeySection Class Microsoft articles for more details.
WFGEN_MACHINE_KEY_VALIDATION_ALG	Represents the validation property of the machineKey element in the web.config file The algorithm name used to generate the validation key. Default: HMACSHA256
WFGEN_MACHINE_KEY_DECRYPTION_ALG	Represents the decryption property of the machineKey element in the web.config file The algorithm name used to generate the decryption key. Default: AES
WFGEN_DEPENDENCY_CHECK_INTERVAL	Time between dependency check retries in milliseconds Default: 1000 (1 second)
WFGEN_DEPENDENCY_CHECK_RETRIES	Number of retries to attempt for each dependency check Default: 10
WFGEN_DEPENDENCY_CHECK_ENABLED	Indicates whether or not the dependency check should be done Possible values: Y (default), N
WFGEN_GRAPHQL_CORS_ENABLED	Enables CORS headers for the GraphQL API Possible values: Y (default), N
WFGEN_GRAPHQL_CORS_ALLOWED_ORIGINS	Comma-separated list of origins from which CORS will allow requests Default: *

Format-based environment variables

WorkflowGen's image also exposes various environment variables based on a specific format in order to configure more generic elements.

web.config

In WorkflowGen, the web.config file is the main point of configuration. Since a container is by definition ephemeral, any changes made in the Configuration Panel would not persist between container restarts.

In order to set configuration properties in the web.config file, you need to use a specific format for an environment variable that will contain the value of the property you want to set; this format is WFGEN_APP_SETTING_<name>.

For example, if you want to set the ApplicationUrl property in the web.config to https://mycorporation.com/wfgen, you would set the WFGEN_APP_SETTING_ApplicationUrl=https://mycorporation.com/wfgen environment variable in the container.

📌 Example with the run command

docker container run `
    # ...
    --env 'WFGEN_APP_SETTING_ApplicationUrl=https://mycorporation.com/wfgen' `
    # ...
    advantys/workflowgen:7.16.0-win-ltsc2019

For a list of web.config parameters and their descriptions and possible values, see the Web and Application Configuration Parameters appendix in the WorkflowGen Technical Guide.

iisnode configuration for Node.js applications

You can also set specific iisnode properties for each Node.js application. To do this, you need to set an environment variable with the following format: WFGEN_IISNODE_<node name>_<property name>.

• Replace <node name> with the name of the Node.js application (AUTH, HOOKS, GRAPHQL, or SCIM).

• Replace <property name> with the name of the property you want to set for the <iisnode/> XML node in the specific Node.js application's web.config file.

For example, if you want to set the iisnode loggingEnabled property in the Auth application to true, you would set the environment variable WFGEN_IISNODE_AUTH_loggingEnabled=true.

📌 Example with the run command

docker container run `
    # ...
    --env WFGEN_IISNODE_AUTH_loggingEnabled=true `
    # ...
    advantys/workflowgen:7.16.0-win-ltsc2019

Special iisnode options for Node.js applications

There are some special options that you can enable for each Node.js application by setting an environment variable that has the following template: WFGEN_ENABLE_IISNODE_OPTION_<node app name>. Then, you replace <node app name> with the name of the Node.js application (AUTH for example) and the value must be one of the following:

Value name	Description
exposelogs	Exposes the logs of the application through http. They will then be available at https://example.com/wfgen/auth/iisnode if the chosen Node.js application is AUTH. ✏️ Note: This option is for debugging purposes only. It is not recommended to use it in production.

Trace configuration

You can activate .NET tracing for different WorkflowGen components using environment variables. Use the WFGEN_TRACE_<component>_<option>=<value> template with <component> as the name of the component you want to set the option on, <option> as the name of the option you want to set, and <value> as the value of the option.

Available components

• WEB_APPS (web applications)

• ENGINE (engine service)

• DIR_SYNC (directory synchronization service)

• NODE (Node.js components)

Options

Name	Description
LEVEL	Controls the amount of information traced and therefore written in files Possible values: ActivityTracing All Critical Error Information Off (default) Verbose Warning For more information on .NET tracing levels, see the SourceLevels Enum Microsoft article.
INDENT	Controls the indentation inside the trace logs Default value: 4 (maximum: 8)

📌 Example

To enable tracing for web applications with an indentation of 2 and only trace errors for the engine with an indentation of 0, you would configure the environment variables as follows:

WFGEN_TRACE_WEB_APPS_LEVEL=Information
WFGEN_TRACE_WEB_APPS_INDENT=2
WFGEN_TRACE_ENGINE_LEVEL=Error
WFGEN_TRACE_ENGINE_INDENT=0

Database configuration

Main connection string

The main connection string can be configured via the WFGEN_DATABASE_CONNECTION_STRING environment variable. You can put any string in this variable and its value will be put in WorkflowGen's web.config file at the MainDbSource connection string.

Here's how to specify the connection string with the run command:

docker container run `
    # ...
    --env WFGEN_DATABASE_CONNECTION_STRING=SomeConnectionString `
    # ...
    advantys/workflowgen:7.16.0-win-ltsc2019

Read-only connection string

If you have a read-only replica, you can configure it in the container as well. You can specify it with the WFGEN_DATABASE_READONLY_CONNECTION_STRING environment variable. It will be added to WorkflowGen's web.config file as a new entry in the connection strings with the name ReadOnlyDbSource.

Here's how to specify the read-only connection string with the run command:

docker container run `
    # ...
    --env WFGEN_DATABASE_CONNECTION_STRING=SomeConnectionString `
    --env WFGEN_DATABASE_READONLY_CONNECTION_STRING=SomeReadOnlyConnectionString `
    # ...
    advantys/workflowgen:7.16.0-win-ltsc2019

Custom connection strings

You can also configure more connections to custom data sources if you need to. They can be configured using a specific environment variable format: WFGEN_CUSTOM_CONNECTION_STRING_<name>=<connection_string>.

For example, if you want a data source named MyDataSource with the connection string value of MyConnectionString in the WorkflowGen web.config, you would specify the following environment variable: WFGEN_CUSTOM_CONNECTION_STRING_MyDataSource=MyConnectionString.

📌 Example with the run command

docker container run `
    # ...
    --env WFGEN_DATABASE_CONNECTION_STRING=SomeConnectionString `
    --env WFGEN_DATABASE_READONLY_CONNECTION_STRING=SomeReadOnlyConnectionString `
    --env WFGEN_CUSTOM_CONNECTION_STRING_MyDataSource=MyConnectionString `
    # ...
    advantys/workflowgen:7.16.0-win-ltsc2019

Secrets

When using an orchestrator such as Kubernetes, you'll probably want to secure secrets using their built-in secret management tools. Follow the specific guide for your orchestrator to know how to create a secret.

For Kubernetes, see https://kubernetes.io/docs/concepts/configuration/secret/.

It's recommended to inject secrets into WorkflowGen containers as files because they won't be exposed as environment variables and they'll be removed from the container when it's stopped or removed.

Secrets management is only possible using an orchestrator.

In order to get the secret value in the file, you need to suffix any environment variable you want to get the value of this way with _FILE and set its value to the path of the file containing the secret. The container will then get the value in the file at the specified path and set the environment variable without the suffix with that value.

For example, let's say you want to set the license serial number in the web.config to WFG-SOME-LICENSE-KEY using the environment variable WFGEN_APP_SETTING_ApplicationSerialNumber, but you want to use a secret for the value. All you have to do is suffix the environment variable name with _FILE so it becomes WFGEN_APP_SETTING_ApplicationSerialNumber_FILE. Then, set the value of this variable to the path of the file containing the serial number.

📌 Example with Docker Swarm orchestrator

# Create the secret for the license serial number
"WFG-SOME-LICENSE-KEY" | docker secret create ApplicationSerialNumber -

# Create the container service in Docker Swarm
docker service create `
    # ...
    --env WFGEN_APP_SETTING_ApplicationSerialNumber_FILE=C:\ProgramData\Docker\secrets\ApplicationSerialNumber `
    --secret ApplicationSerialNumber `
    # ...
    advantys/workflowgen:7.18.3-win-ltsc2019

For Kubernetes, you would create a ConfigMap that complements your secret like this:

apiVersion: v1
kind: ConfigMap
metadata:
  name: wfgen-config
data:
  WFGEN_APP_SETTING_ApplicationSerialNumber_FILE: C:\secrets\ApplicationSerialNumber
---
apiVersion: v1
kind: Secret
type: Opaque
metadata:
  name: wfgen-secret
data:
  # "V0ZHLVNPTUUtTElDRU5TRS1LRVkK" is the base64-encoded value of "WFG-SOME-LICENSE-KEY"
  ApplicationSerialNumber: 'V0ZHLVNPTUUtTElDRU5TRS1LRVkK'

Then, you would map the ConfigMap as environment variables and mount the secret as a volume like this:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: wfgen
spec:
  selector:
    matchLabels:
      # ...
  template:
    metadata:
      labels:
        # ...
    spec:
      containers:
        - name: wfgen
          image: advantys/workflowgen:7.18.3-win-ltsc2019
          # ...
          envFrom: # ConfigMap as environment variables
            - configMapRef:
                name: wfgen-config
          env:
            - name: WFGEN_START_SERVICE
              value: webapps
          # ...
          volumeMounts:
            # ...
            - mountPath: C:\secrets # Mount Secret as a volume
              readOnly: true
              name: secrets
      volumes:
        # ...
        - name: secrets # Mount Secret as a volume
            secret:
              secretName: wfgen-sec

Configuring the authentication mode

For all authentication modes, you need to set WFGEN_APP_SETTING_ApplicationUrl and WFGEN_APP_SETTING_ApplicationSerialNumber in order to avoid unwanted behaviors.

Application authentication

In order to let WorkflowGen handle authentication and the storage of user passwords, you don't need to configure anything special in the container. Keep in mind that the default username for the WorkflowGen administrative account is wfgen_admin.

Windows and Basic authentication

In order to make Windows or Basic authentication modes work, your host needs to be in an Active Directory forest. Creating a user account on the host for Basic authentication won't work, because the IIS web server inside the container will try to find a user account registered inside the container instead of the host. For this reason, you need Active Directory.

To configure your Docker host to work with Active Directory to authenticate users, follow the Group Managed Service Account (gMSA) guide from Microsoft in its Windows Containers documentation.

Kubernetes supports gMSAs for Windows pods and containers as of version 1.18. See the Configure GMSA for Windows Pods and containers Kubernetes article for details on how to configure it. Keep in mind that not all cloud providers supports gMSAs with Kubernetes. For example, Azure Kubernetes Service doesn't support this feature.

You can't use Basic authentication with Kubernetes.

Azure v1 and Microsoft Identity Platform

For these providers, there is no special configuration to do other than setting the WFGEN_AUTH_MODE variable. For configuration instructions, see the WorkflowGen for Azure guide.

Active Directory Federation Services (AD FS), Auth0, and Okta

For these providers, there is no special configuration to do other than setting the WFGEN_AUTH_MODE variable. For configuration instructions, see the WorkflowGen Technical Guide.

Configuring your license

In order to configure your license, you need to set a specific environment variable with your license and copy your license file into a volume exposed to the WorkflowGen container. To do this, you first need to create a license volume or have your license at a specific path.

Create a volume

docker volume create licenses

This will create a volume at a specific path on your file system (typically C:\ProgramData\Docker\volumes\licenses\_data) managed by Docker. You can get the path to the volume by executing the following command:

docker volume inspect -f "{{.Mountpoint}}" licenses

Then, you need to copy your license file to this location:

Copy-Item C:\Path\To\WorkflowGen.lic $(docker volume inspect -f "{{.Mountpoint}}" licenses)

Now, you can run the WorkflowGen container like so:

docker container run `
    # ...
    --env WFGEN_APP_SETTING_ApplicationSerialNumber=YOUR-WFG-LIC-NUM `
    --mount "type=volume,src=licenses,dst=C:\wfgen\licenses,readonly" `
    # ...
    advantys/workflowgen:7.16.0-win-ltsc2019

Use a specific path

Here, you'll provide a path that you control as a volume to the container. You only need to pass the path when you run WorkflowGen:

docker container run `
    # ...
    --env WFGEN_APP_SETTING_ApplicationSerialNumber=YOUR-WFG-LIC-NUM `
    --mount "type=bind,src=C:\Path\To\Your\Licenses,dst=C:\wfgen\licenses,readonly" `
    # ...
    advantys/workflowgen:7.16.0-win-ltsc2019

Bringing the WorkflowGen website offline

You can bring the web applications inside WorkflowGen's container offline by executing a script embedded in the image. This is useful to ensure that the site is still available when you want to perform maintenance tasks on its data without anything new being written. With pure containers, you can execute the following command:

docker container exec -i wfgen powershell C:\set-state.ps1 Offline

With Kubernetes, you can use kubectl:

kubectl exec -i wfgen-pod -- powershell C:\set-state.ps1 Offline

You must do this for each WorkflowGen container that is running. The recommended approach is to scale down the number of containers to one and execute the set-state.ps1 script once.

If you browse to your WorkflowGen website, you'll see the default offline web page. You can customize this web page by adding your own HTML file at the path <wfgen appdata>\Templates\server\offline.htm. If this file is present, it will be taken instead of the default one. If you have a volume for WorkflowGen's data, you can execute the following script:

$offlinePath = ".\offline.htm"
$serverTemplatePath = [io.path]::Combine(
    $(docker volume inspect --format "{{ .Mountpoint }}" wfgdata),
    "appdata" , "Template", "server"
)

if (-not (Test-Path $serverTemplatePath)) {
    New-Item $serverTemplatePath -ItemType Directory -Force
}

Copy-Item $offlinePath $serverTemplatePath

You can bring the site back online by executing the following command:

Docker CLI

docker container exec -i wfgen powershell C:\set-state.ps1 Online

kubectl

kubectl exec -i wfgen-pod -- powershell C:\set-state.ps1 Online

Using an orchestrator

Kubernetes

Kubernetes also has a built-in object called ConfigMap to manage pod configuration. See the Configure a Pod to Use a ConfigMap Kubernetes article for more information and instructions on how to use it. You should use this object to configure environment variables for WorkflowGen.

You can also manage sensitive information by protecting it further in the orchestrator in a secure area. See the Secrets Kubernetes article for more information and instructions on how to use it. You should use this object to protect sensitive information such as the WorkflowGen license key, usernames, passwords, cryptographic keys, API keys, etc.

Using your own configuration files

In order to use your own configuration files, you should build your own WorkflowGen image using the WorkflowGen onbuild image variant. See the Custom Image page in the WorkflowGen Image section for more information.

Using an external configuration manager

Some popular configuration managers support Docker containers out-of-the-box. Here are a few links to their specific documentation to get you started:

Chef

• Docker Cookbook

• Chef and Kubernetes

Ansible

• Ansible – Getting started with Docker

• Manage Kubernetes (K8s) objects

Puppet

• How to run Puppet in Docker

• How to Install and Configure Kubernetes with the Puppet Kubernetes Module