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:
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
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
run
commandFor 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
, orSCIM
).Replace
<property name>
with the name of the property you want to set for the<iisnode/>
XML node in the specific Node.js application'sweb.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
run
commandSpecial 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:
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:
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:
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
run
commandSecrets
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
For Kubernetes, you would create a ConfigMap that complements your secret like this:
Then, you would map the ConfigMap as environment variables and mount the secret as a volume like this:
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
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:
Then, you need to copy your license file to this location:
Now, you can run the WorkflowGen container like so:
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:
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:
With Kubernetes, you can use kubectl:
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:
You can bring the site back online by executing the following command:
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
Ansible
Puppet
Last updated