Configuration

Aperçu

Cette section explique comment configurer complètement un conteneur WorkflowGen, y compris le fichier web.config, la configuration d'iisnode pour les applications Node.js, les chaînes de connexion à la base de données, etc. Tout est configurable via une variable d'environnement, à l'exception du fichier de licence configuré via un volume.

Variables d'environnement WorkflowGen

L'image WorkflowGen fournit un certain nombre de variables d'environnement spécifiques permettant des configurations spécifiques. Le tableau suivant décrit chacun d’entre eux :

Variable	Description et valeurs
WFGEN_ADMIN_USERNAME	Le nom d'utilisateur pour le compte administrateur WorkflowGen Changer cette valeur est utile lorsque vous configurez cette image avec un fournisseur OpenID. Vous pouvez le définir sur un nom d'utilisateur existant sur le fournisseur auquel vous avez accès. Ensuite, lorsque vous accédez à WorkflowGen, vous pouvez vous authentifier auprès de celui-ci et il vous connectera en tant qu'administrateur. Par exemple, si vous avez un nom d'utilisateur sur votre fournisseur nommé [e-mail], vous pouvez définir cette variable d'environnement sur ce nom d'utilisateur et vous en authentifier dans le conteneur pour disposer d'un accès administrateur à WorkflowGen. ✏️ Note : Si vous modifiez cette valeur, veillez également à mettre à jour la base de données. Valeur par défaut : wfgen_admin
WFGEN_DATABASE_CONNECTION_STRING	Variable requise La chaîne de connexion de la source de base de données principale Cette variable d'environnement doit être présente ou le conteneur générera une erreur et se fermera.
WFGEN_DATABASE_READONLY_ CONNECTION_STRING	La chaîne de connexion de la source de base de données en lecture seule pour une configuration de base de données avec des réplicas
WFGEN_AUTH_MODE	Cette variable indique quelle méthode d'authentification doit être utilisée par WorkflowGen Valeurs possibles : adfs application (par défaut) auth0 azure-v1 basic ms-identity-v2 okta windows
WFGEN_GEN_APP_SYM_ENCRYPT_KEY	Indique si ApplicationSecurityPasswordSymmetricEncryptionKey doit être généré ou non si aucune valeur n'est fournie. Si Y, ApplicationSecurityPasswordSymmetricEncryptionKey est régénéré lorsque le conteneur redémarre. Il n'est pas compatible pour une utilisation en production car les secrets seront cryptés avec des clés différentes. Par conséquent, utilisez Y uniquement pour développer ou tester un scénario à conteneur unique. Valeurs possibles : Y (par défaut), N
WFGEN_LICENSE_FILE_NAME	Nom du fichier (y compris l'extension) de la licence requis dans le volume C:\licences Si aucun nom n'est spécifié, le premier fichier trouvé est utilisé.
WFGEN_START_SERVICE	Indique ce que le conteneur doit exécuter Vous pouvez exécuter l'application Web WorkflowGen ou les services Windows, ou les deux. Dans un cluster, vous souhaiterez probablement avoir plusieurs conteneurs en mode d'application Web et un seul conteneur en mode Windows Services. Vous pouvez également en diviser davantage en exécutant plusieurs conteneurs en mode application Web, un conteneur en mode moteur et un conteneur en mode de synchronisation d'annuaire. Valeurs possibles : all (par défaut) dir_sync engine web_apps win_services
WFGEN_MACHINE_KEY_VALIDATION_KEY	Représente la propriété validationKey de l'élément machineKey dans le fichier web.config Par défaut, IIS en génère une lorsqu'elle n'y est pas. Il est recommandé d'utiliser cette variable d'environnement pour partager la clé d'ordinateur entre les instances de ce conteneur (par exemple, dans une batterie de serveurs Web). Consultez les articles Microsoft Résolution des erreurs de code d'authentification de message de l'état d'affichage et MachineKeySection Class pour plus de détails.
WFGEN_MACHINE_KEY_DECRYPTION_KEY	Représente la propriété decryptionKey de l'élément machineKey dans le fichier web.config Par défaut, IIS en génère une lorsqu'elle n'y est pas. Il est recommandé d'utiliser cette variable d'environnement pour partager la clé d'ordinateur entre les instances de ce conteneur (par exemple, dans une batterie de serveurs Web). Consultez les articles Microsoft Résolution des erreurs de code d'authentification de message de l'état d'affichage et MachineKeySection Class pour plus de détails.
WFGEN_MACHINE_KEY_VALIDATION_ALG	Représente la propriété de validation de l'élément machineKey dans le fichier web.config Le nom de l'algorithme utilisé pour générer la clé de validation. Par défaut : HMACSHA256
WFGEN_MACHINE_KEY_DECRYPTION_ALG	Représente la propriété de déchiffrement de l'élément machineKey dans le fichier web.config Le nom de l'algorithme utilisé pour générer la clé de déchiffrement. Par défaut : AES
WFGEN_DEPENDENCY_CHECK_INTERVAL	Temps entre les tentatives de vérification de dépendance en millisecondes Par défaut : 1000 (1 seconde)
WFGEN_DEPENDENCY_CHECK_RETRIES	Nombre de tentatives à effectuer pour chaque vérification de dépendance Par défaut : 10
WFGEN_DEPENDENCY_CHECK_ENABLED	Indique si la vérification de dépendance doit être effectué ou non Valeurs possibles : Y (par défaut), N
WFGEN_GRAPHQL_CORS_ENABLED	Active les en-têtes CORS pour l'API GraphQL Valeurs possibles : Y (par défaut), N
WFGEN_GRAPHQL_CORS_ALLOWED_ORIGINS	Liste des origines séparées par des virgules à partir desquelles CORS autorisera les demandes Par défaut : *

Variables d'environnement basées sur le format

L'image WorkflowGen expose également diverses variables d'environnement basées sur un format spécifique afin de configurer des éléments plus génériques.

web.config

Dans WorkflowGen, le fichier web.config est le point principal de la configuration. Dans la mesure où un conteneur est par définition éphémère, toute modification apportée dans le Panneau de configuration ne persisterait pas entre les redémarrages de conteneur.

Pour définir les propriétés de configuration dans le fichier web.config, vous devez utiliser un format spécifique pour une variable d'environnement qui contiendra la valeur de la propriété que vous souhaitez définir. Ce format est WFGEN_APP_SETTING_<nom>.

Par exemple, si vous souhaitez définir la propriété ApplicationUrl dans le fichier web.config sur https://macompagnie.fr/wfgen, vous devez définir la variable d'environnement WFGEN_APP_SETTING_ApplicationUrl=https://macompagnie.fr/wfgen dans le conteneur.

📌 Exemple avec la commande run

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

Pour une liste des paramètres web.config, ainsi que leurs descriptions et leurs valeurs possibles, consultez l'annexe Paramètres de configuration Web et d'application du Guide technique WorkflowGen.

Configuration iisnode pour les applications Node.js

Vous pouvez également définir des propriétés iisnode spécifiques pour chaque application Node.js. Pour ce faire, vous devez définir une variable d’environnement au format suivant : WFGEN_IISNODE_<nom de l'application NodeJS>_<nom de la propriété>.

• Remplacez <nom de l'application NodeJS> par le nom de l'application Node.js (AUTH, HOOKS, GRAPHQL ou SCIM).

• Remplacez <nom de la propriété> par le nom de la propriété que vous souhaitez définir pour le nœud XML <iisnode/> dans le fichier web.config de l'application Node.js spécifique.

Par exemple, si vous souhaitez définir la propriété iisnode loggingEnabled dans l'application Auth sur true, vous devez définir la variable d'environnement WFGEN_IISNODE_AUTH_loggingEnabled=true.

📌 Exemple avec la commande run

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

Options iisnode spéciales pour les applications Node.js

Il existe des options spéciales que vous pouvez activer pour chaque application Node.js en définissant une variable d'environnement qui a le modèle suivant : WFGEN_ENABLE_IISNODE_OPTION_<nom app NodeJS>. Ensuite, vous remplacez <nom app NodeJS> par le nom de l'application Node.js (AUTH par exemple) et la valeur doit être l'une des suivantes :

Nom de la valeur	Description
exposelogs	Expose les journaux de l'application via http. Ils seront ensuite disponibles sur https://example.com/wfgen/auth/iisnode si l'application Node.js choisie est AUTH. ✏️ Note : Cette option est uniquement à des fins de débogage. Il n'est pas recommandé de l'utiliser en production.

Configuration de trace

Vous pouvez activer le traçage .NET pour différents composants WorkflowGen à l'aide de variables d'environnement. Utilisez le modèle WFGEN_TRACE_<component>_<option>=<value> avec <component> comme nom du composant sur lequel vous souhaitez définir l'option, <option> comme nom de l'option à définir et <value> comme valeur de l'option.

Composants disponibles

• WEB_APPS (applications Web)

• ENGINE (service de moteur)

• DIR_SYNC (service de synchronisation d'annuaire)

• NODE (composants Node.js)

Options

Nom	Description
LEVEL	Contrôle la quantité d'informations tracées et donc écrites dans les fichiers Valeurs possibles : ActivityTracing All Critical Error Information Off (par défaut) Verbose Warning Pour plus d'informations sur les niveaux de traçage .NET, consultez l'article Microsoft SourceLevels Énumération.
INDENT	Contrôle l'indentation dans les logs de trace Valeur par défaut : 4 (maximum : 8)

📌 Exemple

Pour activer le traçage pour les applications Web avec une indentation de 2 et tracer uniquement les erreurs pour le moteur avec une indentation de 0, vous devez configurer les variables d'environnement comme suit :

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

Configuration de la base de données

Chaîne de connexion principale

La chaîne de connexion principale peut être configurée via la variable d'environnement WFGEN_DATABASE_CONNECTION_STRING. Vous pouvez mettre n'importe quelle chaîne dans cette variable et sa valeur sera placée dans le fichier web.config de WorkflowGen au niveau de la chaîne de connexion MainDbSource.

Voici comment spécifier la chaîne de connexion à l'aide de la commande run :

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

Chaîne de connexion en lecture seule

Si vous avez un réplica en lecture seule, vous pouvez également le configurer dans le conteneur. Vous pouvez le spécifier avec la variable d'environnement WFGEN_DATABASE_READONLY_CONNECTION_STRING. Il sera ajoutée au fichier web.config de WorkflowGen en tant que nouvelle entrée dans les chaînes de connexion sous le nom ReadOnlyDbSource.

Voici comment spécifier la chaîne de connexion en lecture seule avec la commande run :

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

Chaînes de connexion personnalisées

Vous pouvez également configurer davantage de connexions aux sources de données personnalisées si vous en avez besoin. Ils peuvent être configurés à l'aide d'un format de variable d'environnement spécifique : WFGEN_CUSTOM_CONNECTION_STRING_<nom>=<chaîne_connexion>.

Par exemple, si vous souhaitez une source de données nommée MyDataSource avec la valeur de chaîne de connexion MyConnectionString dans le fichier web.config de WorkflowGen, spécifiez la variable d'environnement suivante : WFGEN_CUSTOM_CONNECTION_STRING_MyDataSource=MyConnectionString.

📌 Exemple avec la commande run

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

Lorsque vous utilisez un orchestrateur tel que Kubernetes, vous souhaiterez probablement sécuriser les secrets à l'aide de leurs outils de gestion de secrets intégrés. Suivez le guide spécifique destiné à votre orchestrateur pour savoir comment créer un secret.

Pour Kubernetes, consultez https://kubernetes.io/docs/concepts/configuration/secret/ (disponible en anglais uniquement).

Il est recommandé d'injecter ces secrets dans les conteneurs WorkflowGen sous forme de fichiers, car ils ne seront pas exposés en tant que variables d'environnement et ils seront supprimés du conteneur lorsqu'il sera arrêté ou supprimé.

La gestion des secrets n'est possible qu'avec un orchestrateur.

Pour obtenir la valeur secrète dans le fichier, vous devez suffixer toute variable d'environnement pour laquelle vous voulez obtenir la valeur de cette manière avec _FILE et définir sa valeur sur le chemin du fichier contenant le secret. Le conteneur obtiendra alors la valeur dans le fichier au niveau du chemin spécifié et définira la variable d'environnement sans le suffixe avec cette valeur.

Par exemple, supposons que vous souhaitiez définir le numéro de série de la licence dans le fichier web.config sur WFG-SOME-LICENSE-KEY à l'aide de la variable d'environnement WFGEN_APP_SETTING_ApplicationSerialNumber, mais que vous souhaitiez utiliser un secret pour la valeur. Il vous suffit de suffixer le nom de la variable d'environnement avec _FILE pour qu'il devienne WFGEN_APP_SETTING_ApplicationSerialNumber_FILE. Définissez ensuite la valeur de cette variable sur le chemin du fichier contenant le numéro de série.

📌 Exemple avec l'orchestrateur Docker Swarm

# 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

Pour Kubernetes, vous créez un ConfigMap qui complète votre secret comme ceci :

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'

Ensuite, vous devez mapper le ConfigMap en tant que variables d'environnement et monter le secret en tant que volume comme ceci :

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

Configuration du mode d'authentification

Pour tous les modes d'authentification, vous devez définir WFGEN_APP_SETTING_ApplicationUrl etWFGEN_APP_SETTING_ApplicationSerialNumber afin d'éviter les comportements indésirables.

Authentification d'application

Pour laisser WorkflowGen gérer l'authentification et le stockage des mots de passe utilisateur, vous n'avez pas besoin de configurer quoi que ce soit de spécial dans le conteneur. Gardez à l'esprit que le nom d'utilisateur par défaut du compte administratif WorkflowGen est wfgen_admin.

Authentification Windows et de base

Pour que les modes d'authentification Windows ou de base fonctionnent, votre hôte doit se trouver dans une forêt Active Directory. La création d'un compte d'utilisateur sur l'hôte pour l'authentification de base ne fonctionnera pas, car le serveur Web IIS à l'intérieur du conteneur tentera de trouver un compte d'utilisateur enregistré dans le conteneur au lieu de l'hôte. Pour cette raison, vous avez besoin d'Active Directory.

Pour configurer votre hôte Docker pour qu'il fonctionne avec Active Directory pour authentifier les utilisateurs, suivez le guide de compte de service géré de groupe de Microsoft dans sa documentation Conteneurs Windows.

Kubernetes supporte les gMSA pour les pods et conteneurs Windows à partir de la version 1.18. Consultez l'article Kubernetes Configure GMSA for Windows Pods and containers pour plus de détails sur la façon de le configurer. Gardez à l'esprit que tous les fournisseurs de cloud ne supportent pas les gMSA avec Kubernetes. Par exemple, Azure Kubernetes Service ne supporte pas cette fonctionnalité.

Vous ne pouvez pas utiliser l'authentification de base avec Kubernetes.

Azure v1 et Microsoft Identity Platform

Pour ces fournisseurs, il n'y a pas de configuration spéciale à faire autre que la définition de la variable WFGEN_AUTH_MODE. Pour obtenir des instructions de configuration, consultez le guide WorkflowGen pour Azure.

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

Pour ces fournisseurs, il n'y a pas de configuration spéciale à faire autre que la définition de la variable WFGEN_AUTH_MODE. Pour obtenir des instructions de configuration, consultez le Guide technique de WorkflowGen.

Configuration de votre licence

Pour configurer votre licence, vous devez définir une variable d'environnement spécifique avec votre licence et copier votre fichier de licence dans un volume exposé au conteneur WorkflowGen. Pour ce faire, vous devez d’abord créer un volume de licence ou disposer de votre licence sur un chemin spécifique.

Créez un volume

docker volume create licenses

Cela créera un volume sur un chemin spécifique de votre système de fichiers (généralement C:\ProgramData\Docker\volumes\licenses\_data) géré par Docker. Vous pouvez obtenir le chemin du volume en exécutant la commande suivante :

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

Ensuite, vous devez copier votre fichier de licence à cet emplacement :

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

Maintenant, vous pouvez exécuter le conteneur WorkflowGen comme suit :

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

Utilisez un chemin spécifique

Ici, vous fournissez un chemin que vous contrôlez en tant que volume vers le conteneur. Il vous suffit de passer le chemin lorsque vous exécutez 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

Mettre le site Web WorkflowGen hors ligne

Vous pouvez mettre les applications Web dans le conteneur WorkflowGen hors ligne en exécutant un script intégré à l'image. Cela est utile pour garantir que le site est toujours disponible lorsque vous souhaitez effectuer des tâches de maintenance sur ses données sans que rien de nouveau ne soit écrit. Avec des conteneurs purs, vous pouvez exécuter la commande suivante :

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

Avec Kubernetes, vous pouvez utiliser kubectl :

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

Vous devez effectuer cette opération pour chaque conteneur WorkflowGen en cours d'exécution. L'approche recommandée consiste à réduire le nombre de conteneurs à un et à exécuter le script set-state.ps1 une fois.

Si vous accédez à votre site Web WorkflowGen, vous verrez la page Web hors ligne par défaut. Vous pouvez personnaliser cette page Web en ajoutant votre propre fichier HTML dans le chemin <wfgen appdata>\Templates\server\offline.htm. Si ce fichier est présent, il sera pris à la place du fichier par défaut. Si vous disposez d'un volume pour les données de WorkflowGen, vous pouvez exécuter le script suivant:

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

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

Copy-Item $offlinePath $serverTemplatePath

Vous pouvez remettre le site en ligne en exécutant la commande suivante :

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

Utilisation d'un orchestrateur

Kubernetes

Kubernetes dispose également d’un outil intégré de gestion de la configuration appelé ConfigMaps. Consultez l'article Configure a Pod to Use a ConfigMap de Kubernetes (disponible en anglais uniquement) pour plus d'informations. Vous devez utiliser cet objet pour configurer les variables d'environnement pour WorkflowGen.

Vous pouvez également gérer des informations sensibles en les protégeant davantage dans l'orchestrateur dans une zone sécurisée. Consultez l'article Secrets de Kubernetes (disponible en anglais uniquement) pour plus d'informations et des instructions sur son utilisation. Vous devez utiliser cet objet pour protéger des informations sensibles telles que la clé de licence WorkflowGen, les noms d'utilisateur, les mots de passe, les clés cryptographiques, les clés API, etc.

Utilisation de vos propres fichiers de configuration

Pour utiliser vos propres fichiers de configuration, vous devez créer votre propre image WorkflowGen à l'aide de la variante d'image WorkflowGen onbuild. Consultez la page Image personnalisée dans la section Image WorkflowGen pour plus d'informations.

Utilisation d'un gestionnaire de configuration externe

Certains gestionnaires de configuration courants supportent les conteneurs Docker prêts à l'emploi. Voici quelques liens vers leur documentation spécifique (disponible en anglais uniquement) pour vous aider à démarrer :

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